List persons

Purpose

Use this call to read the persons of a list page by page. Send the cursor_next of one answer as cursor of the next call. An empty cursor_next means there is no next page.

Request

POST <API_BASE_URL>/persons. All calls are POST under your API address. Replace <API_BASE_URL> with the API address provided with your access.

Send a permanent API token in the token field of the body, or a user token in the token header. See authentication.

Content type: application/json.

Field	Type	Required	Description
`token`	string (uuid)	if no header	Your permanent API token. Required unless you send a user token in the `token` header.
`list_id`	string (uuid)	no	The list to read. When left out, the default list is used.
`limit`	number or string	no	The largest number of records per page.
`cursor`	string	no	The cursor of the last record of the previous page.
`thumbs`	boolean	no	Include the stored images, base64 encoded.
`embeddings`	boolean	no	Include the stored vectors, base64 encoded.

Response

HTTP 200. One page of the list, sent bare. This operation does not wrap its success in the status envelope.

Field	Type	Description
`persons`	array of object	The page, at most `limit` records long. Each record has the fields of get person.
`cursor_next`	string	The cursor of the last record of this page. An empty string when there is no next page.

Errors

400: The body failed validation. The answer has status of error and a details list with one entry per offending field (path, expected, actual).
401: The token is missing, expired or unknown.
404: A referenced entity does not exist.

A refusal can also come before the operation runs: an address outside your IP allowlist, a token bound to another address, or a body that is not valid JSON. See response format and errors.

Example

Request:

curl -X POST "<API_BASE_URL>/persons" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "<your permanent API token>",
    "list_id": "<person list id>",
    "limit": 50
  }'

Response:

{
  "persons": [
    {
      "person_id": "<person id>",
      "list_id": "<person list id>",
      "created": "2026-01-01T10:00:00.000Z",
      "updated": "2026-01-01T10:00:00.000Z",
      "fields": [
        "<your reference>"
      ],
      "group_id": "<group id>",
      "source_id": "<source id>",
      "features": [],
      "status": "init",
      "yaw": 4,
      "thumbs": [],
      "embeddings": []
    }
  ],
  "cursor_next": ""
}