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

# List calls

> Returns your call history, newest first, one page at a time, with search and filters.

Each call has the fields described in [Call fields](https://docs.olimi.ai/api-reference/endpoint/calls/calls.md#call-fields), plus `hasSummary`, `hasTranscript`, `hasRecording` and `isCallback`. For the summary, recording and transcript themselves, use [Get a call](https://docs.olimi.ai/api-reference/endpoint/calls/get-call.md).

Use `meta.totalPages` to know when you've fetched every page. All filters can be combined.

## How search works

`search` is split into words. A call matches if **any** word matches:

* **Contact name:** the word appears in the contact's first or last name, or is spelled similarly. Not case-sensitive.
* **Phone number:** a word made only of digits, optionally starting with `+`, also matches the contact's phone number when it contains it. Numbers are stored in E.164 form (`+201001234567`), so use digits as they appear there: no spaces, dashes or brackets.
* **Account code:** the word equals the call's account code exactly.
* **Call reference:** a word of 28 characters or more also matches the full `callSid`.

## Filtering by tag

Repeat `tags` once per tag. A call matches if it has **any** of them:

```bash theme={null}
curl "https://api-eg.olimi.ai/api/v2/calls?tags=interested&tags=callback" \
  -H "X-API-KEY: YOUR_API_KEY"
```

> [!WARNING]
>
> To filter by a single tag, you still have to send `tags` twice: `?tags=interested&tags=interested`. A lone `?tags=interested` is rejected with `422`, and `?tags[]=interested` is ignored.

Tag names are the ones you manage in the Dashboard.

Common causes of a `422` validation error:

* `status` or `callType` isn't one of the listed values.
* `agentId` or `didNumberId` isn't a valid UUID.
* `createdFrom` or `createdTo` isn't an ISO 8601 date.
* `durationFrom` or `durationTo` is negative or not a number.
* `tags` was sent only once.

A `campaignId` that's neither a valid UUID nor the word `null` returns `400` `failed_update_data` instead.


## OpenAPI

````yaml get /api/v2/calls
openapi: 3.0.1
info:
  title: Customer Management API
  description: API for managing customer lists and customers within those lists
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api-eg.olimi.ai
security:
  - bearerAuth: []
paths:
  /api/v2/calls:
    get:
      tags:
        - Calls
      summary: List calls
      description: >-
        Returns your call history, newest first, one page at a time, with search
        and filters.
      parameters:
        - name: page
          in: query
          required: false
          description: Page number, starting at `1`.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          required: false
          description: Calls per page.
          schema:
            type: integer
            minimum: 1
            default: 10
        - name: search
          in: query
          required: false
          description: >-
            Finds calls by contact name, phone number, account code or call
            reference. See [How search
            works](/api-reference/endpoint/calls/list-calls#how-search-works).
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Only calls with this status.
          schema:
            type: string
            enum:
              - pending
              - in_progress
              - answered
              - not_answered
              - failed
        - name: callType
          in: query
          required: false
          description: Only calls of this type.
          schema:
            type: string
            enum:
              - inbound
              - outbound
              - web
        - name: agentId
          in: query
          required: false
          description: Only calls made or answered by this agent.
          schema:
            type: string
            format: uuid
        - name: campaignId
          in: query
          required: false
          description: >-
            Only calls from this campaign. Send the word `null` for calls that
            aren't part of any campaign. Anything else that isn't a valid UUID
            returns `400` `failed_update_data`.
          schema:
            type: string
        - name: didNumberId
          in: query
          required: false
          description: Only calls on this phone number of yours.
          schema:
            type: string
            format: uuid
        - name: accountCode
          in: query
          required: false
          description: >-
            Only calls with this account code from your phone system. Exact
            match.
          schema:
            type: string
        - name: tags
          in: query
          required: false
          style: form
          explode: true
          description: >-
            Only calls with **any** of these tags. Repeat the parameter for each
            tag, and repeat it even for one tag. See [Filtering by
            tag](/api-reference/endpoint/calls/list-calls#filtering-by-tag).
          schema:
            type: array
            items:
              type: string
        - name: isWidget
          in: query
          required: false
          description: >-
            `true` returns only calls whose contact came from your website
            widget, including follow-up calls to them. `false` isn't a reliable
            "everything else" filter, because it also drops calls whose contact
            has no widget flag; filter by `callType` instead.
          schema:
            type: boolean
        - name: createdFrom
          in: query
          required: false
          description: Only calls created at or after this time (ISO 8601).
          schema:
            type: string
            format: date-time
        - name: createdTo
          in: query
          required: false
          description: Only calls created at or before this time (ISO 8601).
          schema:
            type: string
            format: date-time
        - name: durationFrom
          in: query
          required: false
          description: Only calls at least this many seconds long.
          schema:
            type: integer
            minimum: 0
        - name: durationTo
          in: query
          required: false
          description: Only calls at most this many seconds long.
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: A page of calls.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallListResponse'
        '400':
          description: >-
            `failed_update_data`: `campaignId` is neither a valid UUID nor
            `null`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: The `X-API-KEY` header is missing or the key isn't valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: A query parameter didn't pass validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      security:
        - apiKeyAuth: []
components:
  schemas:
    CallListResponse:
      type: object
      properties:
        message:
          type: string
          example: Calls fetched successfully
        meta:
          $ref: '#/components/schemas/PaginationMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/CallListItem'
    ApiError:
      type: object
      properties:
        statusCode:
          type: integer
          example: 404
        errorCode:
          type: string
          description: Machine-readable error code.
          example: agent_not_found
        message:
          type: string
          description: Human-readable text. May change; don't match on it.
          example: Agent not found
    ValidationError:
      type: object
      properties:
        statusCode:
          type: integer
          example: 422
        message:
          type: array
          items:
            type: string
          description: What went wrong. Human-readable.
          example:
            - name must be shorter than or equal to 100 characters
        error:
          type: string
          example: Unprocessable Entity
    PaginationMeta:
      type: object
      properties:
        totalItems:
          type: integer
          description: Total items across all pages.
          example: 12
        itemCount:
          type: integer
          description: Items on this page.
          example: 10
        itemsPerPage:
          type: integer
          description: The `limit` used.
          example: 10
        totalPages:
          type: integer
          description: Number of pages.
          example: 2
        currentPage:
          type: integer
          description: The `page` returned.
          example: 1
    CallListItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The call's ID.
          example: c41f8e27-3b9a-4d6e-8f15-2a7c9e0b4d63
        callSid:
          type: string
          nullable: true
          description: The call's reference in the phone network. Searchable in full.
          example: CA7d3f1c9e2b8a4f60d5e1c7b93a2f8e41d6
        status:
          type: string
          enum:
            - pending
            - in_progress
            - answered
            - not_answered
            - failed
          description: >-
            See [Call status
            values](/api-reference/endpoint/calls/calls#call-status-values).
          example: answered
        callType:
          type: string
          enum:
            - inbound
            - outbound
            - web
          description: See [Call types](/api-reference/endpoint/calls/calls#call-types).
          example: outbound
        durationInSec:
          type: integer
          description: How long the call lasted, in seconds.
          example: 184
        isInterested:
          type: boolean
          nullable: true
          description: >-
            Whether the contact seemed interested, judged from the conversation.
            `null` when not determined.
          example: true
        tags:
          type: array
          nullable: true
          items:
            type: string
          description: Tags applied to the call.
          example:
            - interested
        tagsWithColors:
          type: array
          items:
            $ref: '#/components/schemas/CallTagWithColor'
          description: The same tags with their colour.
        customKeys:
          type: array
          items:
            $ref: '#/components/schemas/CallCustomKey'
          description: >-
            Values extracted from the conversation, one per custom key. `null`
            when none were extracted.
          nullable: true
        retryCount:
          type: integer
          description: Which retry this call was. `0` for the first attempt.
          example: 0
        isFinal:
          type: boolean
          description: >-
            Whether no more attempts will be made to reach this contact. See
            [When a call is
            final](/api-reference/endpoint/calls/calls#when-a-call-is-final).
          example: true
        createdAt:
          type: string
          format: date-time
          description: When the call was created (UTC).
          example: '2026-09-28T10:22:41.307Z'
        agent:
          $ref: '#/components/schemas/CallAgentRef'
        contact:
          $ref: '#/components/schemas/CallContactRef'
        campaign:
          $ref: '#/components/schemas/CallCampaignRef'
        didNumber:
          $ref: '#/components/schemas/CallDidNumberRef'
        hasSummary:
          type: boolean
          description: Whether the call has a summary.
          example: true
        hasTranscript:
          type: boolean
          description: >-
            Whether conversation data was recorded. Can be `true` for a call
            with no spoken turns.
          example: true
        hasRecording:
          type: boolean
          description: Whether the call has a recording.
          example: true
        isCallback:
          type: boolean
          description: Whether this call was a callback the contact asked for.
          example: false
    CallTagWithColor:
      type: object
      properties:
        name:
          type: string
          example: interested
        color:
          type: string
          nullable: true
          example: '#16A34A'
    CallCustomKey:
      type: object
      properties:
        key:
          type: string
          example: preferred_branch
        value:
          type: string
          example: Nasr City
    CallAgentRef:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 0d6a3f7e-5b8c-4b1e-9a51-2f1d7c9e4a10
        name:
          type: string
          example: Renewals Agent
    CallContactRef:
      type: object
      nullable: true
      properties:
        id:
          type: string
          format: uuid
          example: b2f7c4e1-8a3d-4c59-9e06-1d5a7f3b8c42
        phoneNumber:
          type: string
          example: '+201001234567'
          description: >-
            Usually E.164. Website widget contacts and some inbound callers may
            have another format or an empty value.
        firstName:
          type: string
          nullable: true
          example: Ahmed
        lastName:
          type: string
          nullable: true
          example: Hassan
        callbackScheduled:
          type: boolean
          description: Whether the contact asked to be called back.
          example: false
    CallCampaignRef:
      type: object
      nullable: true
      properties:
        id:
          type: string
          format: uuid
          example: 3e8b5d21-7c4a-4f96-a1d0-6b2e9c7f4a58
        name:
          type: string
          example: September renewals
        maxRetries:
          type: integer
          example: 2
      description: >-
        `null` for calls outside a campaign, and for calls whose campaign was
        deleted.
    CallDidNumberRef:
      type: object
      nullable: true
      properties:
        id:
          type: string
          format: uuid
          example: d5a2e8c1-4f7b-4a93-b6d0-1e9c3f7a2b84
        phoneNumber:
          type: string
          example: '+20225550100'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````

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