Subscribers
List Subscribers
List subscribers with pagination and filtering
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
List Subscribers