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

# Count calls

> How many of an agent's calls match, in all and by status, type, ended reason, sentiment and outcome.

Takes the same filters as `GET /v1/calls` and counts every call that list would page through.
Each breakdown lists only the values some matching call holds, most calls first; a call with no
value for one, such as no sentiment yet, is in `total_count` but in none of that breakdown's
entries. Counts of a busy agent with only `status` set can be up to 12 minutes old. Counts that
search transcripts answer 503 `query_timeout` when they match too much to read in time.



## OpenAPI

````yaml /api-reference/v1/openapi.json get /v1/calls/counts
openapi: 3.1.0
info:
  description: >-
    Authenticate every request with an org API key: `Authorization: Bearer
    phk_…`.
  title: Phonely API
  version: '1'
servers:
  - description: US
    url: https://api.us.phonely.ai
  - description: AU
    url: https://api.au.phonely.ai
security: []
paths:
  /v1/calls/counts:
    get:
      tags:
        - Calls
      summary: Count calls
      description: >-
        How many of an agent's calls match, in all and by status, type, ended
        reason, sentiment and outcome.


        Takes the same filters as `GET /v1/calls` and counts every call that
        list would page through.

        Each breakdown lists only the values some matching call holds, most
        calls first; a call with no

        value for one, such as no sentiment yet, is in `total_count` but in none
        of that breakdown's

        entries. Counts of a busy agent with only `status` set can be up to 12
        minutes old. Counts that

        search transcripts answer 503 `query_timeout` when they match too much
        to read in time.
      operationId: get_call_counts
      parameters:
        - description: The agent whose calls to read.
          in: query
          name: agent_id
          required: true
          schema:
            description: The agent whose calls to read.
            minLength: 1
            title: Agent Id
            type: string
        - description: >-
            Only calls in these statuses; repeat for several. Defaults to
            `completed`, `ended`, `in_progress` and `in_warm_transfer`.
          in: query
          name: status
          required: false
          schema:
            anyOf:
              - items:
                  $ref: '#/components/schemas/CallStatus'
                type: array
              - type: 'null'
            description: >-
              Only calls in these statuses; repeat for several. Defaults to
              `completed`, `ended`, `in_progress` and `in_warm_transfer`.
            title: Status
        - description: >-
            Only calls of these types, as a call's `type` reports them; repeat
            for several.
          in: query
          name: type
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Only calls of these types, as a call's `type` reports them; repeat
              for several.
            title: Type
        - description: >-
            Only calls that started at or after this time (ISO 8601 with a
            timezone).
          in: query
          name: started_from
          required: false
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: 'null'
            description: >-
              Only calls that started at or after this time (ISO 8601 with a
              timezone).
            title: Started From
        - description: Only calls that started before this time (ISO 8601 with a timezone).
          in: query
          name: started_before
          required: false
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: 'null'
            description: >-
              Only calls that started before this time (ISO 8601 with a
              timezone).
            title: Started Before
        - description: >-
            Only calls that ended for these reasons, as a call's `ended_reason`
            reports them; repeat for several.
          in: query
          name: ended_reason
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Only calls that ended for these reasons, as a call's
              `ended_reason` reports them; repeat for several.
            title: Ended Reason
        - description: >-
            Only calls with these sentiments, as a call's `sentiment` reports
            them; repeat for several.
          in: query
          name: sentiment
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Only calls with these sentiments, as a call's `sentiment` reports
              them; repeat for several.
            title: Sentiment
        - description: >-
            Only calls with these outcomes, exactly as a call's `outcome`
            reports them; repeat for several.
          in: query
          name: outcome
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Only calls with these outcomes, exactly as a call's `outcome`
              reports them; repeat for several.
            title: Outcome
        - description: >-
            Only calls with this customer, exactly as a call's
            `customer_phone_number` reports it, such as `+14155550123`. Encode
            the `+` as `%2B` in the URL, or it arrives as a space.
          in: query
          name: customer_phone_number
          required: false
          schema:
            anyOf:
              - minLength: 1
                type: string
              - type: 'null'
            description: >-
              Only calls with this customer, exactly as a call's
              `customer_phone_number` reports it, such as `+14155550123`. Encode
              the `+` as `%2B` in the URL, or it arrives as a space.
            title: Customer Phone Number
        - description: >-
            Only calls whose `customer_phone_number` contains this text, such as
            `5550123`. Not with `customer_phone_number`.
          in: query
          name: customer_phone_number_contains
          required: false
          schema:
            anyOf:
              - maxLength: 64
                minLength: 1
                type: string
              - type: 'null'
            description: >-
              Only calls whose `customer_phone_number` contains this text, such
              as `5550123`. Not with `customer_phone_number`.
            title: Customer Phone Number Contains
        - description: >-
            Only calls where the agent or the customer said this text, ignoring
            case. Needs `started_from`, at most 31 days before `started_before`
            (or now).
          in: query
          name: transcript_contains
          required: false
          schema:
            anyOf:
              - maxLength: 100
                minLength: 1
                type: string
              - type: 'null'
            description: >-
              Only calls where the agent or the customer said this text,
              ignoring case. Needs `started_from`, at most 31 days before
              `started_before` (or now).
            title: Transcript Contains
        - description: >-
            Only calls whose analytics fields hold these options, each as
            `<field_id>:<option_id>` from the agent's `GET
            /v1/agents/{id}/call-analysis`. Options of one field combine with
            OR, different fields with AND. Repeat for several, at most 200.
          in: query
          name: analytics_field
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Only calls whose analytics fields hold these options, each as
              `<field_id>:<option_id>` from the agent's `GET
              /v1/agents/{id}/call-analysis`. Options of one field combine with
              OR, different fields with AND. Repeat for several, at most 200.
            title: Analytics Field
        - description: >-
            Only calls that took part in this A/B experiment, on either arm, as
            a call's `experiment_ids` reports it.
          in: query
          name: experiment_id
          required: false
          schema:
            anyOf:
              - minLength: 1
                type: string
              - type: 'null'
            description: >-
              Only calls that took part in this A/B experiment, on either arm,
              as a call's `experiment_ids` reports it.
            title: Experiment Id
        - description: Only calls placed by this campaign.
          in: query
          name: campaign_id
          required: false
          schema:
            anyOf:
              - minLength: 1
                type: string
              - type: 'null'
            description: Only calls placed by this campaign.
            title: Campaign Id
        - description: >-
            Only calls that lasted at least this long. Like
            `max_duration_seconds`, it matches only calls with a duration
            (`duration_seconds` not `null`).
          in: query
          name: min_duration_seconds
          required: false
          schema:
            anyOf:
              - minimum: 0
                type: number
              - type: 'null'
            description: >-
              Only calls that lasted at least this long. Like
              `max_duration_seconds`, it matches only calls with a duration
              (`duration_seconds` not `null`).
            title: Min Duration Seconds
        - description: >-
            Only calls that lasted at most this long. Like
            `min_duration_seconds`, it matches only calls with a duration
            (`duration_seconds` not `null`).
          in: query
          name: max_duration_seconds
          required: false
          schema:
            anyOf:
              - minimum: 0
                type: number
              - type: 'null'
            description: >-
              Only calls that lasted at most this long. Like
              `min_duration_seconds`, it matches only calls with a duration
              (`duration_seconds` not `null`).
            title: Max Duration Seconds
        - description: Optional. Must be the key's org.
          in: header
          name: Phonely-Organization
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Optional. Must be the key's org.
            title: Phonely-Organization
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallCounts'
          description: Successful Response
          headers:
            Phonely-Organization:
              description: The authorized organization for this request.
              schema:
                type: string
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: >-
            The request is invalid: a malformed body, a bad or unknown field, or
            an unknown query parameter.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The API key is missing, invalid or revoked.
          headers:
            WWW-Authenticate:
              description: Always `Bearer`.
              schema:
                type: string
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '`Phonely-Organization` must name the key''s organization.'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Rate limited. Retry after the number of seconds in `Retry-After`.
          headers:
            Retry-After:
              description: Seconds until the request can be retried.
              schema:
                type: integer
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An unexpected error. Contact support with the request ID.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: >-
            Authentication, authorization or another required service is
            temporarily unavailable; or, as `query_timeout`, a read matched too
            much to finish in time: narrow its filters rather than retrying it
            as sent.
      security:
        - HTTPBearer: []
components:
  schemas:
    CallStatus:
      description: >-
        Where a call is in its lifecycle, including the outcomes of pay-per-call
        transfers. Known values: `completed`, `ended`, `in_progress`,
        `in_warm_transfer`, `queued`, `queueing`, `redial_scheduled`,
        `cancelled`, `dnc`, `failed`, `transferred_sold`,
        `transferred_not_sold`, `transferred_pending_sale`,
        `rev_share_pending_qualification`, `transferred_busy`,
        `transferred_no_answer`, `transferred_failed`. More can be added, so
        handle values you don't recognize.
      title: CallStatus
      type: string
      x-extensible-enum:
        - completed
        - ended
        - in_progress
        - in_warm_transfer
        - queued
        - queueing
        - redial_scheduled
        - cancelled
        - dnc
        - failed
        - transferred_sold
        - transferred_not_sold
        - transferred_pending_sale
        - rev_share_pending_qualification
        - transferred_busy
        - transferred_no_answer
        - transferred_failed
    CallCounts:
      additionalProperties: false
      description: How many of an agent's calls match the filters, in all and by value.
      properties:
        agent_id:
          description: The agent whose calls were counted.
          title: Agent Id
          type: string
        ended_reason:
          description: Matching calls by `ended_reason`, most first.
          items:
            $ref: '#/components/schemas/CallValueCount'
          title: Ended Reason
          type: array
        object:
          const: call_counts
          default: call_counts
          description: The type of this object, always `call_counts`.
          title: Object
          type: string
        outcome:
          description: Matching calls by `outcome`, most first.
          items:
            $ref: '#/components/schemas/CallValueCount'
          title: Outcome
          type: array
        sentiment:
          description: Matching calls by `sentiment`, most first.
          items:
            $ref: '#/components/schemas/CallValueCount'
          title: Sentiment
          type: array
        status:
          description: Matching calls by `status`, most first.
          items:
            $ref: '#/components/schemas/CallValueCount'
          title: Status
          type: array
        total_count:
          description: How many calls match.
          title: Total Count
          type: integer
        type:
          description: Matching calls by `type`, most first.
          items:
            $ref: '#/components/schemas/CallValueCount'
          title: Type
          type: array
      required:
        - object
        - agent_id
        - total_count
        - status
        - type
        - ended_reason
        - sentiment
        - outcome
      title: CallCounts
      type: object
    ErrorResponse:
      additionalProperties: false
      description: The body of every `/v1` error.
      properties:
        error:
          $ref: '#/components/schemas/Error'
          description: What went wrong.
      required:
        - error
      title: ErrorResponse
      type: object
    CallValueCount:
      additionalProperties: false
      description: How many matching calls hold one value.
      properties:
        count:
          description: How many matching calls hold it.
          title: Count
          type: integer
        value:
          description: The value, exactly as a call in the list reports it.
          title: Value
          type: string
      required:
        - value
        - count
      title: CallValueCount
      type: object
    Error:
      additionalProperties: false
      properties:
        code:
          description: >-
            What went wrong, stable and machine-readable. Known values:
            `validation_failed`, `invalid_cursor`, `invalid_api_key`,
            `insufficient_access`, `organization_mismatch`, `forbidden`,
            `not_found`, `method_not_allowed`, `conflict`,
            `agent_limit_reached`, `agent_too_large`, `sms_setup_required`,
            `opportunity_analysis_not_set_up`, `precondition_failed`,
            `payload_too_large`, `unsupported_media_type`,
            `precondition_required`, `rate_limited`, `internal_error`,
            `knowledge_processing_failed`, `bad_gateway`, `service_unavailable`,
            `gateway_timeout`, `query_timeout`. More can be added, so handle
            values you don't recognize.
          title: Code
          type: string
          x-extensible-enum:
            - validation_failed
            - invalid_cursor
            - invalid_api_key
            - insufficient_access
            - organization_mismatch
            - forbidden
            - not_found
            - method_not_allowed
            - conflict
            - agent_limit_reached
            - agent_too_large
            - sms_setup_required
            - opportunity_analysis_not_set_up
            - precondition_failed
            - payload_too_large
            - unsupported_media_type
            - precondition_required
            - rate_limited
            - internal_error
            - knowledge_processing_failed
            - bad_gateway
            - service_unavailable
            - gateway_timeout
            - query_timeout
        details:
          description: One entry per problem field. Empty when the error has none.
          items:
            $ref: '#/components/schemas/ErrorDetail'
          title: Details
          type: array
        message:
          description: For people. Wording can change; branch on `code`.
          title: Message
          type: string
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Also in the `X-Request-Id` header. Quote it to support.
          title: Request Id
      required:
        - code
        - message
        - details
        - request_id
      title: Error
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        field:
          description: >-
            The field the issue is about, as sent: `agent_id`, `limit`. Empty
            when none.
          title: Field
          type: string
        issue:
          description: >-
            What is wrong with the field. Known values: `required`,
            `unknown_field`, `invalid_json`, `invalid_type`, `invalid_value`,
            `out_of_range`, `invalid_cursor`, `read_only_field`. More can be
            added, so handle values you don't recognize.
          title: Issue
          type: string
          x-extensible-enum:
            - required
            - unknown_field
            - invalid_json
            - invalid_type
            - invalid_value
            - out_of_range
            - invalid_cursor
            - read_only_field
        message:
          description: 'For people: what is wrong with this field.'
          title: Message
          type: string
      required:
        - field
        - issue
        - message
      title: ErrorDetail
      type: object
  securitySchemes:
    HTTPBearer:
      description: 'An org API key: `Authorization: Bearer phk_…`'
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.