Skip to main content
GET
List Subscribers
List subscribers with stable pagination and optional filtering by status, free-text query, tags, list, segment, attribute, or email. Without an attribute filter, results are ordered by createdAt descending, with subscriber ID used as a tie-breaker so page boundaries stay deterministic when multiple subscribers have the same creation time. With an attribute filter, results use ClickHouse-first cursor pagination and are ordered by subscriber ID ascending. Attribute-filtered responses do not include a total count; use pagination.nextCursor until it is null.

Query Parameters

number
default:"1"
Page number
number
default:"20"
Items per page (max 100)
string
Cursor returned as pagination.nextCursor. Only used with attribute filtering. Use cursor instead of page when filtering by attribute.
string
Filter by status: active, unsubscribed, bounced, or all. Use all to disable status filtering.
string
Free-text search across email, first name, last name, and tags
string
Legacy alias for a partial email search
string
Comma-separated tag names. A subscriber must have all provided tags.
string
Filter by a custom attribute using attributeName:value syntax, such as plan:pro or mrr:50. Use attributeName: only with empty-check operators.
string
default:"is"
Attribute operator. Direct cursor pagination supports inclusion operators: is, contains, gt, gte, lt, lte, and is_not_empty. For exclusion operators such as is_not, not_contains, or is_empty, create a saved segment and pass segmentId.
string
Subscriber list ID or exact list name. The API tries ID first, then exact name.
string
Filter by subscriber list ID.
string
Filter by exact subscriber list name when the ID is not known.
string
Filter by an existing segment ID

Responses