List customers

View as Markdown
Return matching records as data[], with pagination.has_more and pagination.next_cursor. Each item uses the same native payload as single-record retrieval. Required start_time/end_time are epoch seconds with an inclusive start and exclusive end, spanning at most 31 days. limit is 1–50 (default 20); sort_order is asc or desc (default desc). Optional filter applies the same standard field matching as the dashboard. The record contains the current customer_analytics, meta_analytics and native timeline object. It preserves the customer portion of the analytics webhook; it does not reconstruct a historical profile. For larger datasets, use [Create export](/v0/api-reference/exports/create-export) to obtain a CSV download link. Each export supports at most 31 days, 100,000 records and 100 MB; split longer periods into adjacent windows.

Authentication

AuthorizationBearer
Existing private account API key from Developer Hub. Keep it on your backend.

Query parameters

service_idstringRequired1-255 characters

Required authorized service. Client identity is derived from the API key. Nonempty, at most 255 characters; whitespace-only values and control characters are rejected.

time_fieldenumOptionalDefaults to last_interaction_at

Timestamp used for filtering and ordering. Only last_interaction_at is currently supported for this resource.

Allowed values:
start_timelongRequired0-253402300799

Inclusive start in Unix epoch seconds. Must precede end_time; maximum window is 31 days. Milliseconds are invalid.

end_timelongRequired0-253402300799
Exclusive end in Unix epoch seconds. Maximum window is 31 days. Milliseconds are invalid.
sort_orderenumOptionalDefaults to desc

Order by last_interaction_at, then ID in the same direction. asc returns oldest first; desc returns newest first. Keep the same sort_order when continuing with a cursor.

Allowed values:
limitintegerOptional1-50Defaults to 20

Maximum records per page. Accepts integers from 1 to 50; defaults to 20.

cursorstringOptional1-4096 characters

Opaque continuation token, 1–4,096 characters; expires after 15 minutes. Repeat the same filters and sort_order. Omit for the first page. Copy pagination.next_cursor from the previous response; see the pagination walkthrough for first and next-page requests.

filterstringOptional

Dashboard filters as one URL-encoded JSON object (maximum 16 KB). All conditions must match. See the schema for fields, operators, and value constraints.

Response

Successful response.
datalist of objects
Current customer profiles and their native analytics and timeline for this page.
paginationobject

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error