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

# Get live segment counts

> How many contacts a saved segment reaches today. The counts on
`GET /v1/segments/{id}` are the ones its last membership refresh left
behind, dated by `counts.refreshed_at`, and they can lag or still be
zero after a create; this counts the segment's criteria against the
latest data now. It only reads, and saves and changes nothing. Each
count is a scan of the account's contacts, so it has its own budget
on top of the request limit: 20 per minute and 600 per UTC day for
each user, charged only when a count runs. A token with no user
shares one such budget per account.

Live counts need the account to be on the latest segment engine.
An account that is not yet is refused with
`403 live_counts_unavailable`: the merchant can ask Privy support to
migrate the account, and retrying does not help. An account whose
live answers Privy is checking is refused with
`403 live_counts_suspended`: the suspension lifts on its own within
a week, or sooner through Privy support, and retrying in the same
session does not help. The endpoint needs the account's new segment
builder, and answers `403 segment_builder_required` without it.
When live counts are paused or a count fails for the moment, the
answer is `503 counts_unavailable`; retry it after its `Retry-After`.
When a count runs out of time or memory, which an account's size can
make happen on every call, the answer is `422 counts_too_large`; Privy is
notified, and a retry does not help. When Privy cannot count the
saved criteria, the answer is `500 counts_failed`; Privy is notified,
and a plain retry rarely helps.
A saved condition the live engine cannot count as written, or that
reads all-time activity the account does not have, is
`422 segment_not_countable`: the segment's criteria are not the
request's to change, so read its refreshed counts instead.
A live count can differ from the refreshed one, and
from the members `GET /v1/segments/{id}/contacts` lists, until the
next refresh.

**Required scope:** `segments_read`




## OpenAPI

````yaml openapi/privy-api.yaml GET /segments/{id}/counts
openapi: 3.1.0
info:
  title: Privy API
  version: '1.0'
  description: >
    The Privy API lets you programmatically manage your contact list and read
    what you have set up in Privy.

    Create, update, unsubscribe, and remove contacts; report orders;

    and read your campaigns, flows, segments, orders, store products, coupon
    pools,

    performance reports, and account setup.
servers:
  - url: https://api.privy.com/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Account
    description: Retrieve information about the authenticated Privy account.
  - name: Contacts
    description: Manage your contact list.
  - name: Imports
    description: >-
      Read your contact import history — CSV uploads, connected-provider syncs,
      and SMS consent imports.
  - name: Tags
    description: Read your contact tags — Privy tags and tags synced from Shopify.
  - name: Campaigns
    description: >-
      Read your message campaigns — email and SMS newsletters, plus the messages
      your flows send.
  - name: Displays
    description: >-
      Read your on-site displays (popups, flyouts, banners, embedded forms,
      landing pages).
  - name: Coupons
    description: Read your coupon pools, their code inventory, and individual codes.
  - name: Reports
    description: >-
      Read performance reporting — signups, views, conversion rates, and
      attributed revenue — for your business, displays, and flows.
  - name: Flows
    description: Read your automation flows and their configuration.
  - name: Segments
    description: Read your customer segments and their membership.
  - name: Orders
    description: Report orders placed in your store and read your order history.
  - name: Products
    description: Read the product catalog and collections of your connected store.
  - name: Events
    description: Ingest custom events to trigger Flows and other automations.
paths:
  /segments/{id}/counts:
    get:
      tags:
        - Segments
      summary: Get live segment counts
      description: >
        How many contacts a saved segment reaches today. The counts on

        `GET /v1/segments/{id}` are the ones its last membership refresh left

        behind, dated by `counts.refreshed_at`, and they can lag or still be

        zero after a create; this counts the segment's criteria against the

        latest data now. It only reads, and saves and changes nothing. Each

        count is a scan of the account's contacts, so it has its own budget

        on top of the request limit: 20 per minute and 600 per UTC day for

        each user, charged only when a count runs. A token with no user

        shares one such budget per account.


        Live counts need the account to be on the latest segment engine.

        An account that is not yet is refused with

        `403 live_counts_unavailable`: the merchant can ask Privy support to

        migrate the account, and retrying does not help. An account whose

        live answers Privy is checking is refused with

        `403 live_counts_suspended`: the suspension lifts on its own within

        a week, or sooner through Privy support, and retrying in the same

        session does not help. The endpoint needs the account's new segment

        builder, and answers `403 segment_builder_required` without it.

        When live counts are paused or a count fails for the moment, the

        answer is `503 counts_unavailable`; retry it after its `Retry-After`.

        When a count runs out of time or memory, which an account's size can

        make happen on every call, the answer is `422 counts_too_large`; Privy
        is

        notified, and a retry does not help. When Privy cannot count the

        saved criteria, the answer is `500 counts_failed`; Privy is notified,

        and a plain retry rarely helps.

        A saved condition the live engine cannot count as written, or that

        reads all-time activity the account does not have, is

        `422 segment_not_countable`: the segment's criteria are not the

        request's to change, so read its refreshed counts instead.

        A live count can differ from the refreshed one, and

        from the members `GET /v1/segments/{id}/contacts` lists, until the

        next refresh.


        **Required scope:** `segments_read`
      operationId: getSegmentCounts
      parameters:
        - $ref: '#/components/parameters/AccountIdParam'
        - name: id
          in: path
          required: true
          description: >-
            The segment's unique identifier (returned as `id` in segment
            responses). Ids are opaque public strings — a numeric id from a
            Privy dashboard URL is not a valid API id and will 404; list
            segments and match by name instead.
          schema:
            type: string
          example: Rz5T2kW8pB
      responses:
        '200':
          $ref: '#/components/responses/LiveSegmentCounts'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/LiveCountsForbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: >-
            `segment_not_countable` when a saved condition cannot be counted
            live as written, or reads all-time activity the account does not
            have (read the segment's refreshed counts instead), or
            `counts_too_large` when the count ran out of time or memory for this
            account (Privy is notified, and a retry does not help).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: segment_not_countable
                  message: >-
                    This segment cannot be counted live as saved. The counts
                    from its last refresh are on GET /v1/segments/{id}.
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/LiveCountsFailed'
        '503':
          $ref: '#/components/responses/LiveCountsUnavailable'
      security:
        - bearerAuth: []
components:
  parameters:
    AccountIdParam:
      name: Privy-Account-Id
      in: header
      required: false
      description: >
        Target a subaccount instead of the main connected account.

        Pass a subaccount `id` from get_account's `subaccounts` list. Only
        direct subaccounts

        of the connected account are reachable — omit this for the main account
        itself.
      schema:
        type: string
      example: S1U2B3A4C5C6T7
  responses:
    LiveSegmentCounts:
      description: The counts the conditions reach today.
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  total_count:
                    type: integer
                    description: >-
                      Every matching contact, whether or not they can be
                      reached.
                  mailable_count:
                    type: integer
                    description: Matching contacts who can be emailed.
                  textable_count:
                    type: integer
                    description: Matching contacts who can be texted.
          example:
            data:
              total_count: 1930
              mailable_count: 1284
              textable_count: 312
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: unauthorized
              message: Bearer token is missing or invalid
    LiveCountsForbidden:
      description: >-
        `insufficient_scope` when the token lacks `segments_read`,
        `live_counts_unavailable` when the account is not counted live,
        `live_counts_suspended` while its live answers are being checked, or
        `segment_builder_required` when the account does not yet have the new
        segment builder.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: live_counts_unavailable
              message: >-
                This Privy account is not eligible for live segment counts yet.
                Contact Privy support to migrate your account to the latest
                version.
    NotFound:
      description: >-
        The requested resource does not exist or does not belong to your
        account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: not_found
              message: Not found
    RateLimited:
      description: Rate limit exceeded. Retry after the specified time.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
          example: 42
        X-RateLimit-Limit-Minute:
          description: Maximum requests allowed per minute.
          schema:
            type: integer
          example: 60
        X-RateLimit-Remaining-Minute:
          description: Requests remaining in the current minute window.
          schema:
            type: integer
          example: 0
        X-RateLimit-Reset-Minute:
          description: Unix timestamp when the minute window resets.
          schema:
            type: integer
          example: 1711929600
        X-RateLimit-Limit-Day:
          description: Maximum requests allowed per day.
          schema:
            type: integer
          example: 10000
        X-RateLimit-Remaining-Day:
          description: Requests remaining in the current day window.
          schema:
            type: integer
          example: 9500
        X-RateLimit-Reset-Day:
          description: Unix timestamp when the day window resets.
          schema:
            type: integer
          example: 1712016000
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: rate_limited
              message: Rate limit exceeded
    LiveCountsFailed:
      description: >-
        Privy could not count criteria that passed validation, or the live
        engine refused the query built from them. Privy is notified; a plain
        retry rarely helps.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: counts_failed
              message: >-
                Live segment counts failed for this request. Privy has been
                notified.
    LiveCountsUnavailable:
      description: >-
        Live counts are paused or the count failed for the moment
        (`counts_unavailable`); `Retry-After` gives the seconds to wait before
        retrying.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
          example: 60
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: counts_unavailable
              message: >-
                Live segment counts are not available right now. Try again
                shortly.
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - invalid_client
                - invalid_scope
                - unauthorized
                - insufficient_scope
                - forbidden
                - paid_plan_required
                - api_access_required
                - segment_builder_required
                - not_found
                - no_connected_store
                - conflict
                - contacts_not_ready
                - validation_failed
                - idempotency_key_reused
                - rate_limited
                - store_unavailable
                - store_rate_limited
                - not_a_draft
                - design_changed
                - sms_missing
                - email_missing
                - ab_test_draft
                - idempotency_key_reused
                - template_unavailable
                - design_unavailable
                - render_failed
              example: validation_failed
            message:
              type: string
              example: One or more fields are invalid
            details:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                    example: email
                  message:
                    type: string
                    example: is required
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API token or OAuth access token
      description: >
        Send either an API token or an OAuth access token as

        `Authorization: Bearer <token>`. See the Authentication page for
        details.

````