> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Subscribers

> List subscribers with pagination and filtering

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

<ParamField query="page" type="number" default="1">
  Page number
</ParamField>

<ParamField query="limit" type="number" default="20">
  Items per page (max 100)
</ParamField>

<ParamField query="cursor" type="string">
  Cursor returned as `pagination.nextCursor`. Only used with `attribute`
  filtering. Use `cursor` instead of `page` when filtering by attribute.
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `active`, `unsubscribed`, `bounced`, or `all`. Use `all` to
  disable status filtering.
</ParamField>

<ParamField query="query" type="string">
  Free-text search across email, first name, last name, and tags
</ParamField>

<ParamField query="email" type="string">
  Legacy alias for a partial email search
</ParamField>

<ParamField query="tags" type="string">
  Comma-separated tag names. A subscriber must have all provided tags.
</ParamField>

<ParamField query="attribute" type="string">
  Filter by a custom attribute using `attributeName:value` syntax, such as
  `plan:pro` or `mrr:50`. Use `attributeName:` only with empty-check operators.
</ParamField>

<ParamField query="attributeOperator" type="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`.
</ParamField>

<ParamField query="list" type="string">
  Subscriber list ID or exact list name. The API tries ID first, then exact
  name.
</ParamField>

<ParamField query="listId" type="string">
  Filter by subscriber list ID.
</ParamField>

<ParamField query="listName" type="string">
  Filter by exact subscriber list name when the ID is not known.
</ParamField>

<ParamField query="segmentId" type="string">
  Filter by an existing segment ID
</ParamField>

```bash theme={null}
curl "https://api.sequenzy.com/api/v1/subscribers?page=1&limit=100&status=active&list=Master%20List" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```bash theme={null}
curl "https://api.sequenzy.com/api/v1/subscribers?attribute=mrr%3A50&attributeOperator=gte" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```bash theme={null}
curl "https://api.sequenzy.com/api/v1/subscribers?attribute=mrr%3A50&attributeOperator=gte&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Responses

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "subscribers": [
      {
        "id": "sub_abc123",
        "email": "user@sequenzy.com",
        "firstName": "John",
        "lastName": "Doe",
        "status": "active",
        "emailProvider": "gmail",
        "tags": ["customer", "newsletter"],
        "customAttributes": { "plan": "pro" },
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 100,
      "total": 150,
      "totalPages": 2
    }
  }
  ```

  ```json 200 theme={null}
  {
    "success": true,
    "subscribers": [
      {
        "id": "sub_abc123",
        "email": "user@sequenzy.com",
        "firstName": "John",
        "lastName": "Doe",
        "status": "active",
        "emailProvider": "gmail",
        "tags": ["customer", "newsletter"],
        "customAttributes": { "mrr": 99 },
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 100,
      "total": null,
      "totalPages": null,
      "nextCursor": "NEXT_CURSOR",
      "hasMore": true,
      "orderBy": "subscriber_id_asc"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "success": false,
    "error": "Unauthorized"
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": "status must be one of active, unsubscribed, bounced, or all"
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": "Attribute filters must include a value after \"attributeName:\"."
  }
  ```

  ```json 404 theme={null}
  {
    "success": false,
    "error": "Segment not found"
  }
  ```

  ```json 404 theme={null}
  {
    "success": false,
    "error": "List not found"
  }
  ```

  ```json 500 theme={null}
  {
    "success": false,
    "error": "Internal server error"
  }
  ```
</ResponseExample>