---
title: "List subscribers"
method: GET
path: "/v4/subscribers"
tags: ["Subscribers"]
---

# List subscribers

`GET /v4/subscribers`

Returns a cursor-paginated list of subscribers in the account. By default only `active` subscribers are returned — use `status` (`active`, `inactive`, `bounced`, `complained`, `cancelled`, or `all`) to widen the search. Look a subscriber up by exact `email_address`, filter by `created_after`/`created_before` and `updated_after`/`updated_before`, and sort with `sort_field` (`id`, `updated_at`, or `cancelled_at`) and `sort_order`.

Use `include` (comma-separated: `attribution`, `tags`, `location`, `canceled_at`) to embed extra fields on each subscriber — including `canceled_at` without `status=cancelled` returns a `422`. Set `slim=true` to omit the `fields` object (custom field values) for a faster, smaller response.

For engagement-based searches (opens, clicks, sends), use [Filter subscribers by engagement](/api-reference/subscribers/filter-subscribers-by-engagement-sign-up-date-state-and-tags) instead.

## Query parameters

- `after` string, nullable
- `before` string, nullable
- `created_after` string
- `created_before` string
- `email_address` string
- `include` string
- `include_total_count` boolean
- `per_page` number, nullable
- `slim` boolean
- `sort_field` string
- `sort_order` 'asc' | 'desc'
- `status` 'active' | 'inactive' | 'bounced' | 'complained' | 'cancelled' | 'all'
- `updated_after` string
- `updated_before` string

## Response `200`

Returns subscriber attribution, tags, and primary location when requested via the include param

- object
  - `subscribers` object[], required
    - `id` integer, required
    - `first_name` string, nullable, required
    - `email_address` string, required
    - `state` 'active' | 'cancelled' | 'bounced' | 'complained' | 'inactive', required
    - `created_at` string, required
    - `fields` object, required
      - `category` string, nullable
    - `attribution` object, nullable — Returned when `include` contains `attribution`.
      - `referrer` string, nullable, required
      - `utm_source` string, nullable, required
      - `utm_medium` string, nullable, required
      - `utm_campaign` string, nullable, required
      - `utm_term` string, nullable, required
      - `utm_content` string, nullable, required
      - `source_type` string, nullable, required
      - `source_name` string, nullable, required
      - `source_mechanism` string, nullable, required
      - `source_mechanism_id` integer, nullable, required
    - `tags` object[] — Returned when `include` contains `tags`.
      - `id` integer, nullable
      - `name` string, nullable
    - `location` object, nullable — Returned when `include` contains `location`.
      - `city` string, nullable, required
      - `state` string, nullable, required
      - `country` string, nullable, required
      - `latitude` number, float, nullable, required
      - `longitude` number, float, nullable, required
      - `timezone` string, nullable, required
    - `canceled_at` string, date-time, nullable — Returned when `include` contains `canceled_at`. Requires `status=cancelled`.
  - `pagination` object, required
    - `has_previous_page` boolean, required
    - `has_next_page` boolean, required
    - `start_cursor` string, required
    - `end_cursor` string, required
    - `per_page` integer, required

## Other responses

- `401` — Returns a 401 if the token and/or account cannot be authenticated
- `422` — raises an error when sorting on cancelled_at without the cancelled status

---

[API](https://skmtc.net/kit/apis/kit-api.md) · [All operations](https://skmtc.net/kit/apis/kit-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kit/kit-api/revisions/0df0c90d12da/schema)