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

# List Calls

> Returns your project's calls, newest first by default, filtered and one page at a time. Choose the fields to return in `returnedFields`. `period` only filters when you also send `timeZone` (or a `CUSTOM` range with `startPeriod`): without them, calls from all time are listed.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/voice-agents/conversations/list
openapi: 3.0.1
info:
  title: Hamsa API
  description: >-
    The Hamsa API: voice agents and their calls, phone numbers, batch calls and
    knowledge bases; speech to text, text to speech, voices and AI content.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tryhamsa.com
security: []
paths:
  /v1/voice-agents/conversations/list:
    post:
      summary: List calls
      description: >-
        Returns your project's calls, newest first by default, filtered and one
        page at a time. Choose the fields to return in `returnedFields`.
        `period` only filters when you also send `timeZone` (or a `CUSTOM` range
        with `startPeriod`): without them, calls from all time are listed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - returnedFields
              properties:
                returnedFields:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    enum:
                      - time
                      - cost
                      - status
                      - channelType
                      - agentName
                      - agentId
                      - callNumbers
                      - release
                      - performanceMetrics
                      - turns
                      - isTakenOver
                      - toolFailed
                      - analytics
                  description: >-
                    Fields to fill for each call. `callNumbers` returns
                    `callParams`. `performanceMetrics`, `turns`, `isTakenOver`,
                    `toolFailed` and `analytics` need extra reads: ask only for
                    what you show.
                  example:
                    - time
                    - status
                    - channelType
                    - agentName
                voiceAgentId:
                  type: string
                  format: uuid
                  description: Only this agent's calls.
                  example: 48f7656f-098b-4c43-b165-7cfd2cc8ac30
                take:
                  type: number
                  minimum: 1
                  maximum: 30
                  default: 10
                  description: Calls per page (1-30).
                  example: 10
                skip:
                  type: number
                  minimum: 1
                  default: 1
                  description: Page number, starting at 1.
                  example: 1
                channelType:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    enum:
                      - Web
                      - Telephone
                      - HamsaTalk
                      - Chat Agent
                  description: Only calls on these channels.
                  example:
                    - Telephone
                status:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    enum:
                      - PENDING
                      - IN_PROGRESS
                      - COMPLETED
                      - NO_ANSWER
                      - FAILED
                      - FORWARDED
                      - TERMINATED
                  description: >-
                    Only calls with these statuses. Ignored when
                    `returnActiveCalls` is `true`. An `IN_PROGRESS` call is
                    listed only if it started in the last hour, the same window
                    as `returnActiveCalls`; other statuses in the filter are not
                    limited.
                  example:
                    - COMPLETED
                sortField:
                  type: string
                  enum:
                    - time
                    - duration
                    - cost
                  description: >-
                    Sort by start time, length or cost. Used only together with
                    `sortOrder`; otherwise newest first.
                  example: time
                sortOrder:
                  type: string
                  enum:
                    - asc
                    - desc
                  example: desc
                returnActiveCalls:
                  type: boolean
                  default: false
                  description: >-
                    `true`: only calls in progress that started in the last
                    hour.
                  example: false
                search:
                  type: string
                  minLength: 1
                  description: >-
                    A call ID or agent ID (exact UUID), or part of the caller's
                    phone number.
                  example: '+9665'
                duration:
                  type: object
                  required:
                    - condition
                    - firstValue
                  description: Call length filter, in whole seconds.
                  properties:
                    condition:
                      type: string
                      enum:
                        - IS_LESS_THAN
                        - IS_GREATER_THAN
                        - IS_BETWEEN
                        - IS_EQUAL_TO
                      description: >-
                        `IS_BETWEEN` includes both values and needs
                        `secondValue`.
                      example: IS_GREATER_THAN
                    firstValue:
                      type: integer
                      minimum: 0
                      example: 60
                    secondValue:
                      type: integer
                      minimum: 0
                      description: Upper bound for `IS_BETWEEN`, at least `firstValue`.
                      example: 300
                versionNumbers:
                  type: array
                  minItems: 1
                  items:
                    type: integer
                    minimum: 1
                  description: Only calls answered by these agent versions.
                  example:
                    - 3
                environmentId:
                  type: string
                  format: uuid
                  description: Only calls that used this environment.
                  example: a2c4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f
                chosenBySplit:
                  type: boolean
                  description: >-
                    Only calls where an A/B split picked the version (`true`),
                    or the others (`false`).
                  example: true
                draft:
                  type: boolean
                  description: >-
                    `true`: only draft test calls. `false`: only calls answered
                    by a version.
                  example: false
                isResolved:
                  type: boolean
                  description: >-
                    Only calls judged resolved (`true`) or not (`false`). Calls
                    not analysed yet never match.
                  example: true
                isHandedOff:
                  type: boolean
                  description: Only calls handed (or not) to a person.
                  example: false
                sentiment:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    enum:
                      - positive
                      - neutral
                      - negative
                  description: Only calls with these sentiments.
                  example:
                    - negative
                hasErrors:
                  type: boolean
                  description: Only calls with (or without) errors.
                  example: true
                hasKbGap:
                  type: boolean
                  description: Only calls with (or without) a knowledge gap.
                  example: true
                period:
                  type: string
                  enum:
                    - LAST_HOUR
                    - TODAY
                    - YESTERDAY
                    - THIS_WEEK
                    - THIS_MONTH
                    - CUSTOM
                  default: TODAY
                  description: >-
                    Time range: `LAST_HOUR`, `TODAY` (default), `YESTERDAY`,
                    `THIS_WEEK` (weeks start on Sunday), `THIS_MONTH`, or
                    `CUSTOM` (send `startPeriod` and `endPeriod`). Day, week and
                    month boundaries are computed in `timeZone`. Applied only
                    with `timeZone` (or `startPeriod` for `CUSTOM`).
                  example: THIS_WEEK
                startPeriod:
                  type: string
                  pattern: ^[0-9]{13}$
                  description: >-
                    Start of a `CUSTOM` range: Unix timestamp in milliseconds
                    (13 digits), as a string.
                  example: '1761955200000'
                endPeriod:
                  type: string
                  pattern: ^[0-9]{13}$
                  description: >-
                    End of a `CUSTOM` range: Unix timestamp in milliseconds (13
                    digits), as a string.
                  example: '1762560000000'
                timeZone:
                  type: string
                  minLength: 1
                  description: >-
                    IANA time zone for the period boundaries, for example
                    `Asia/Riyadh`. Send it for `period` to filter: without it,
                    calls from all time are listed.
                  example: Asia/Riyadh
            examples:
              basic:
                summary: This week's completed calls
                value:
                  returnedFields:
                    - time
                    - status
                    - channelType
                    - agentName
                    - callNumbers
                  status:
                    - COMPLETED
                  period: THIS_WEEK
                  timeZone: Asia/Riyadh
                  take: 10
                  skip: 1
                  sortField: time
                  sortOrder: desc
              active:
                summary: Calls in progress
                value:
                  returnedFields:
                    - time
                    - agentName
                    - callNumbers
                  returnActiveCalls: true
              custom:
                summary: Custom range, long calls of one agent
                value:
                  returnedFields:
                    - time
                    - cost
                    - status
                    - analytics
                  voiceAgentId: 48f7656f-098b-4c43-b165-7cfd2cc8ac30
                  period: CUSTOM
                  startPeriod: '1761955200000'
                  endPeriod: '1762560000000'
                  duration:
                    condition: IS_BETWEEN
                    firstValue: 60
                    secondValue: 300
              release:
                summary: Unhappy calls of version 3
                value:
                  returnedFields:
                    - time
                    - release
                    - analytics
                  versionNumbers:
                    - 3
                  sentiment:
                    - negative
                  period: THIS_MONTH
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: success
                  data:
                    type: object
                    properties:
                      total:
                        type: integer
                        description: Number of calls that match the filters.
                        example: 128
                      filtered:
                        type: integer
                        description: Number of calls on this page.
                        example: 10
                      conversations:
                        type: array
                        items:
                          $ref: '#/components/schemas/ConversationListItem'
        '400':
          description: >-
            Invalid body, for example `take` above 30 (`TakeExceedsMaximum`), an
            unknown `returnedFields` value, or `period: CUSTOM` without
            `startPeriod` and `endPeriod`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '401':
          description: 'Unauthorized: missing or invalid API key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '403':
          description: >-
            Your API key or role does not have the `call_history:read`
            permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '500':
          description: Server Side Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ConversationListItem:
      type: object
      description: >-
        One call. Only `id`, `duration` and the fields you asked for in
        `returnedFields` are filled.
      properties:
        id:
          type: string
          format: uuid
          example: 849e77c6-5cb3-479a-a985-7fab630e2c78
        duration:
          type: number
          nullable: true
          description: Call length in seconds.
          example: 74
        time:
          type: string
          format: date-time
          description: When the call started (`time`).
          example: '2026-11-02T10:06:08.109Z'
        cost:
          type: number
          description: Call cost (`cost`).
          example: 5
        status:
          type: string
          enum:
            - PENDING
            - IN_PROGRESS
            - COMPLETED
            - NO_ANSWER
            - FAILED
            - FORWARDED
            - TERMINATED
          description: '`status`.'
          example: COMPLETED
        channelType:
          type: string
          nullable: true
          enum:
            - Web
            - Telephone
            - HamsaTalk
            - Chat Agent
          description: '`channelType`.'
          example: Telephone
        agentId:
          type: string
          format: uuid
          description: '`agentId`.'
          example: 48f7656f-098b-4c43-b165-7cfd2cc8ac30
        agentName:
          type: string
          description: '`agentName`.'
          example: Support Agent
        callParams:
          type: object
          nullable: true
          additionalProperties: true
          description: Phone numbers of the call (`callNumbers`).
          example:
            userNumber: '+966500000001'
            machineNumber: '+966500000002'
        release:
          $ref: '#/components/schemas/ConversationRelease'
        performanceMetrics:
          type: object
          description: Average processing times in milliseconds (`performanceMetrics`).
          properties:
            asrProcessingTime:
              type: number
              example: 320
            llmResponseTime:
              type: number
              example: 910
            ttsGenerationTime:
              type: number
              example: 410
            totalProcessingTime:
              type: number
              example: 1640
        turns:
          type: integer
          description: Number of transcript entries (`turns`).
          example: 14
        isTakenOver:
          type: boolean
          description: '`true` when a person took over the call (`isTakenOver`).'
          example: false
        toolFailed:
          type: boolean
          description: '`true` when a tool call failed during the call (`toolFailed`).'
          example: false
        analytics:
          $ref: '#/components/schemas/ConversationCallAnalytics'
    ErrorSchema:
      type: object
      properties:
        code:
          type: integer
          description: >-
            Service error code: the HTTP status with a service prefix (for
            example `8404`). Missing when the service has no code for that
            status.
          example: 8404
        message:
          type: string
          description: >-
            What went wrong. Some services (calls and recordings) put the error
            key here, for example `CallNotFoundOrUnavailable`, and send no
            `messageKey`.
          example: Policy not found!
        messageKey:
          type: string
          description: >-
            Stable key for the error, safe to match on in code. Not returned by
            every service.
          example: PolicyNotFound
        params:
          type: object
          additionalProperties: true
          description: >-
            Details for some errors (for example `reason`). Not returned by
            every service.
          example:
            reason: NO_DRAFT
    ConversationRelease:
      type: object
      nullable: true
      description: >-
        Which agent release answered the call. `null` for calls made before
        releases were recorded.
      properties:
        versionId:
          type: string
          nullable: true
          example: 5e7a9c1b-3d2f-4a6e-8b0c-1f2e3d4c5b6a
        versionNumber:
          type: integer
          nullable: true
          description: Version number, e.g. `3` for v3.
          example: 3
        draftRevisionId:
          type: string
          nullable: true
          description: Set when the call tested a draft.
          example: null
        environmentId:
          type: string
          nullable: true
          example: a2c4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f
        environmentName:
          type: string
          nullable: true
          example: prod
        environmentRevisionId:
          type: string
          nullable: true
          example: 0c2e4a6b-8d1f-4e3a-9b5c-7d9e1f3a5b7c
        chosenBySplit:
          type: boolean
          nullable: true
          description: '`true` when an A/B split picked this version.'
          example: false
    ConversationCallAnalytics:
      type: object
      nullable: true
      description: >-
        The call's analytics. `null` while the call has none. `isResolved` and
        `sentiment` stay `null` until the call has been analysed.
      properties:
        status:
          type: string
          enum:
            - PENDING
            - IN_PROGRESS
            - COMPLETED
            - FAILED
            - FORWARDED
          example: COMPLETED
        isResolved:
          type: boolean
          nullable: true
          example: true
        isHandedOff:
          type: boolean
          description: '`true` when the call was handed to a person.'
          example: false
        sentiment:
          type: string
          nullable: true
          enum:
            - positive
            - neutral
            - negative
          example: neutral
        totalProcessingTimeMs:
          type: integer
          nullable: true
          description: Speech recognition + LLM + speech generation time, in milliseconds.
          example: 1840
        errors:
          type: object
          properties:
            any:
              type: boolean
              example: false
            asr:
              type: boolean
              example: false
            llm:
              type: boolean
              example: false
            tts:
              type: boolean
              example: false
        kbGapType:
          type: string
          nullable: true
          enum:
            - KB_MISSING_DATA
            - API_DATA_GAP
            - AGENT_RETRIEVAL_FAILURE
          description: Why the agent could not answer from its knowledge, if it couldn't.
          example: null
        outOfScopeRequests:
          type: array
          nullable: true
          items:
            type: string
          description: '`[]`: checked, nothing out of scope. `null`: not checked.'
          example:
            - refund status
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Pass the API key in the Authorization header, You need to put Token
        keyword before the API key. e.g. 'Authorization: Token <api-key>'

````

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