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

page
number
default:"1"
Page number
limit
number
default:"20"
Items per page (max 100)
cursor
string
Cursor returned as pagination.nextCursor. Only used with attribute filtering. Use cursor instead of page when filtering by attribute.
status
string
Filter by status: active, unsubscribed, bounced, or all. Use all to disable status filtering.
query
string
Free-text search across email, first name, last name, and tags
email
string
Legacy alias for a partial email search
tags
string
Comma-separated tag names. A subscriber must have all provided tags.
attribute
string
Filter by a custom attribute using attributeName:value syntax, such as plan:pro or mrr:50. Use attributeName: only with empty-check operators.
attributeOperator
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.
list
string
Subscriber list ID or exact list name. The API tries ID first, then exact name.
listId
string
Filter by subscriber list ID.
listName
string
Filter by exact subscriber list name when the ID is not known.
segmentId
string
Filter by an existing segment ID

Responses