> ## Documentation Index > Fetch the complete documentation index at: https://developers.kit.com/llms.txt > Use this file to discover all available pages before exploring further. # List 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. ## OpenAPI ````yaml /api-reference/v4.json get /v4/subscribers openapi: 3.0.3 info: title: Kit API version: '4.0' servers: - url: https://api.kit.com security: [] paths: /v4/subscribers: get: tags: - Subscribers summary: List subscribers description: >- 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. parameters: - name: after description: To fetch next page of results, use `?after=` in: query required: false schema: type: string nullable: true - name: before description: To fetch previous page of results, use `?before=` in: query required: false schema: type: string nullable: true - name: created_after description: >- Filter subscribers who have been created after this date (format yyyy-mm-dd) in: query required: false schema: type: string example: '2023-01-17T11:43:55Z' - name: created_before description: >- Filter subscribers who have been created before this date (format yyyy-mm-dd) in: query required: false schema: type: string example: '2023-02-18T11:43:55Z' - name: email_address in: query required: false schema: type: string example: subscriber89@kit.dev,subscriber90@kit.dev,subscriber91@kit.dev - name: include in: query required: false schema: type: string example: attribution,tags,location description: >- Comma-separated list of additional fields to include on each subscriber. Valid options: `attribution`, `tags`, `location`, `canceled_at`. `canceled_at` may only be used together with `status=cancelled`. - name: include_total_count description: >- Set to `true` to include the `total_count` in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages. in: query required: false schema: type: boolean example: false - name: per_page description: Number of results per page. Default 500, maximum 1000. in: query required: false schema: type: number nullable: true example: 10 - name: slim in: query required: false schema: type: boolean example: false description: >- When `true`, omits expensive optional fields from the response. Produces a faster, smaller response — useful when extra fields are not needed. - name: sort_field in: query required: false schema: type: string example: cancelled_at - name: sort_order in: query required: false schema: type: string enum: - asc - desc example: asc - name: status description: >- Filter subscribers who have this status (`active`, `inactive`, `bounced`, `complained`, `cancelled` or `all`). Defaults to `active`. in: query required: false schema: type: string enum: - active - inactive - bounced - complained - cancelled - all example: bounced - name: updated_after description: >- Filter subscribers who have been updated after this date (format yyyy-mm-dd) in: query required: false schema: type: string example: '2023-01-17T11:43:55Z' - name: updated_before description: >- Filter subscribers who have been updated before this date (format yyyy-mm-dd) in: query required: false schema: type: string example: '2023-02-18T11:43:55Z' responses: '200': description: >- Returns subscriber attribution, tags, and primary location when requested via the include param content: application/json: schema: type: object properties: subscribers: type: array items: type: object properties: id: type: integer first_name: type: string nullable: true email_address: type: string state: type: string enum: - active - cancelled - bounced - complained - inactive created_at: type: string fields: type: object properties: category: type: string nullable: true attribution: type: object description: Returned when `include` contains `attribution`. nullable: true properties: referrer: type: string nullable: true utm_source: type: string nullable: true utm_medium: type: string nullable: true utm_campaign: type: string nullable: true utm_term: type: string nullable: true utm_content: type: string nullable: true source_type: type: string nullable: true source_name: type: string nullable: true source_mechanism: type: string nullable: true source_mechanism_id: type: integer nullable: true required: - referrer - utm_source - utm_medium - utm_campaign - utm_term - utm_content - source_type - source_name - source_mechanism - source_mechanism_id tags: type: array description: Returned when `include` contains `tags`. items: type: object properties: id: type: integer nullable: true name: type: string nullable: true location: type: object description: Returned when `include` contains `location`. nullable: true properties: city: type: string nullable: true state: type: string nullable: true country: type: string nullable: true latitude: type: number nullable: true format: float longitude: type: number nullable: true format: float timezone: type: string nullable: true required: - city - state - country - latitude - longitude - timezone canceled_at: type: string format: date-time nullable: true description: >- Returned when `include` contains `canceled_at`. Requires `status=cancelled`. required: - id - state - first_name - email_address - created_at - fields pagination: type: object properties: has_previous_page: type: boolean has_next_page: type: boolean start_cursor: type: string end_cursor: type: string per_page: type: integer required: - has_previous_page - has_next_page - start_cursor - end_cursor - per_page required: - subscribers - pagination example: subscribers: - id: 200 state: active first_name: Alice email_address: alice@convertkit.dev created_at: '2023-01-27T11:43:55Z' fields: category: One attribution: referrer: https://t.co/abc123 utm_source: twitter utm_medium: cpc utm_campaign: spring_launch utm_term: newsletter+for+creators utm_content: hero_cta source_type: form_subscription source_name: Welcome Form source_mechanism: landing_page source_mechanism_id: null tags: - id: 1 name: VIP location: city: Portland state: OR country: US latitude: 45.5 longitude: -122.6 timezone: America/Los_Angeles - id: 201 state: active first_name: Benito email_address: benito@convertkit.dev created_at: '2023-02-03T11:43:55Z' fields: {} attribution: referrer: https://creator.kit.com/jane-smith utm_source: kit utm_medium: referral utm_campaign: null utm_term: null utm_content: null source_type: form_subscription source_name: Jane Smith's Recommendations source_mechanism: recommendations source_mechanism_id: null tags: - id: 2 name: Newsletter location: city: Austin state: TX country: US latitude: 30.27 longitude: -97.74 timezone: America/Chicago - id: 202 state: active first_name: Camille email_address: camille@convertkit.dev created_at: '2023-02-10T11:43:55Z' fields: {} attribution: referrer: null utm_source: null utm_medium: null utm_campaign: null utm_term: null utm_content: null source_type: api_subscription source_name: Partner Integration source_mechanism: api source_mechanism_id: 12345 tags: [] location: null - id: 203 state: active first_name: Elliot email_address: elliot@convertkit.dev created_at: '2023-02-13T11:43:55Z' fields: {} attribution: referrer: null utm_source: null utm_medium: null utm_campaign: null utm_term: null utm_content: null source_type: null source_name: null source_mechanism: null source_mechanism_id: null tags: - id: 3 name: Imported location: city: null state: null country: null latitude: null longitude: null timezone: null pagination: has_previous_page: false has_next_page: false start_cursor: MjAyMy0wMS0yNyAxMTo0Mzo1NSBVVEM= end_cursor: MjAyMy0wMi0xMyAxMTo0Mzo1NSBVVEM= per_page: 500 '401': description: Returns a 401 if the token and/or account cannot be authenticated content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - The access token is invalid '422': description: >- raises an error when sorting on cancelled_at without the cancelled status content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - >- The status param must be `cancelled` if sort_field is `cancelled_at` security: - API Key: [] - OAuth2: [] components: securitySchemes: API Key: description: Authenticate API requests via an API Key type: apiKey in: header name: X-Kit-Api-Key OAuth2: description: Authenticate API requests via an OAuth token type: oauth2 flows: authorizationCode: authorizationUrl: https://api.kit.com/v4/oauth/authorize tokenUrl: https://api.kit.com/v4/oauth/token refreshUrl: https://api.kit.com/v4/oauth/token scopes: read: Read access to Kit API v4 write: Write access to Kit API v4 ````