List subscribers
Lists subscribers with stable pagination and optional filtering by status, free-text query, tags, list, segment, attribute, or email. Non-attribute results are ordered by createdAt descending with subscriber ID as a deterministic tie-breaker. Attribute-filtered results use ClickHouse-first cursor pagination ordered by subscriber ID ascending and do not include a total count.
Pulling a full audience: every response includes pagination.nextCursor and pagination.hasMore. Follow nextCursor rather than incrementing page. Cursor pagination keeps results stable while subscribers are being created or deleted mid-pull (page numbers can skip or repeat rows as the underlying set shifts) and skips the total-count query, so pagination.total and pagination.totalPages are null on cursor requests. Combined with limit=1000, a 10,000-subscriber export takes ten requests instead of a hundred.
Query parameters
Page number. Cannot be combined with cursor.
Number of items per page (max 1000)
Opaque cursor returned as pagination.nextCursor. Cannot be combined with page. Attribute-filtered requests return their own cursor, which is not interchangeable with the default-ordering cursor.
Pass false to skip the total-count query on page-numbered requests. Cursor requests always skip it.
Filter by subscriber status. Use all to disable status filtering.
Free-text search across email, first name, last name, and tags
Legacy alias for a partial email search
Comma-separated tag names. Subscribers must have all provided tags.
Custom attribute filter using attributeName:value syntax, such as plan:pro or mrr:50.
Attribute filter operator for direct cursor pagination. Use saved segments for exclusion operators such as is_not, not_contains, or is_empty.
Subscriber list ID or exact list name. The API tries ID first, then exact name.
Filter by subscriber list ID.
Filter by exact subscriber list name when the list ID is not known.
Filter by an existing segment ID
Response
Successful response
Example response
{
"success": true,
"subscribers": [
{
"id": "sub_abc123",
"email": "user@example.com",
"externalId": "user_123",
"firstName": "John",
"lastName": "Doe",
"phone": "+15551234567",
"smsStatus": "subscribed",
"status": "active",
"emailProvider": "gmail",
"tags": [
"premium",
"newsletter"
],
"customAttributes": {
"plan": "pro",
"signupSource": "website"
}
}
],
"pagination": {
"page": 1,
"limit": 1000,
"total": 8718,
"totalPages": 9,
"nextCursor": "eyJ2ZXJzaW9uIjoxLCJzb3J0IjoiY3JlYXRlZF9hdF9kZXNjX2lkX2Rlc2MifQ",
"hasMore": true,
"orderBy": "created_at_desc_id_desc"
}
}