Beta

Find Lists

Last updated Nov 19, 2026View as MarkdownAgent setup / MCP
GET
/v1/lists

Find saved Lists in the selected Workspace. A restricted definition returns only recovery metadata, never an empty List. Use get_list_members for current members.

Authorization

headerAuthorizationBearer <token>

A signed-in SMB user's access token. Workspace-scoped operations also require SMB-Workspace-Id.

Query Parameters

after?string
Length1 <= length <= 4096
counts?boolean

Add counts by kind (null if too many).

ids?string

Only these Lists (comma-separated, up to 100).

Match^list_[0-7][0-9A-HJKMNP-TV-Z]{25}(,list_[0-7][0-9A-HJKMNP-TV-Z]{25}){0,99}$
limit?integer
Range1 <= value <= 100
Default50
member_counts?boolean

false: skip member counts (ask next with ids).

query?string

Name contains this text.

Length1 <= length <= 200
sort?"name"

name: A to Z. Default: order made.

Value in"name"
status?string
Default"active"
Value in"active""archived""all"
subject_type?string
Value in"business""person"

Header Parameters

SMB-Workspace-Id*string
Formatuuid

Response Body

Successful authorized response.

application/json
  1. response
data*
request_id*string
curl -X GET 'https://example.com/v1/lists' \  -H 'SMB-Workspace-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'
{  "data": {    "lists": [      {        "id": "string",        "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",        "name": "string",        "description": "string",        "definition": {          "schema_version": "smb.list.v1",          "subject_type": "business",          "rule": {            "kind": "field",            "field": "name",            "operator": "eq",            "value": "string"          }        },        "version": -9007199254740991,        "lifecycle_status": "active",        "count": {          "status": "unknown",          "value": null,          "as_of": null,          "fewer_than": -9007199254740991        },        "columns": [          {            "column_id": "8f0515e3-00f6-4dd0-8153-321f1f40863d",            "name": "string",            "value_type": "text",            "position": 0,            "options": [              {                "id": "string",                "label": "string",                "color": "gray"              }            ]          }        ],        "view": {          "data_columns": [            "string"          ]        }      }    ],    "next_cursor": "string",    "counts": {      "business": 0,      "person": 0    }  },  "request_id": "string"}