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

# List Calls

> Retrieves a paginated list of call logs for a specific organization

## List Calls

Retrieves a paginated list of call logs for a specific organization. This endpoint can be accessed using either a tenant API key or an organization API key. The organization ID must be specified as a query parameter regardless of which authentication method is used.

<Note>
  This endpoint returns basic call information. For detailed call information
  including transcript and recording URLs, use the [Get
  Call](/api-reference/endpoint/get-call) endpoint.
</Note>

### Headers

<ParamField header="Authorization" type="string" required>
  API key is required. Enter either your tenant-specific or
  organization-specific API key in the format `Bearer YOUR-API-KEY`
</ParamField>

### Query Parameters

<ParamField query="organizationId" type="string" required>
  The ID of the organization to list calls for
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for pagination (minimum: 1)
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Number of items per page (minimum: 1, maximum: 50)
</ParamField>

<ParamField query="callType" type="string">
  Filter calls by type. Must be one of: `Inbound`, `Outbound`, `Web`. Invalid values will return a 400 error.
</ParamField>

<ParamField query="agentName" type="string">
  Filter calls by agent name (partial match supported).
</ParamField>

<ParamField query="from" type="string" format="date-time">
  Start date for date range filter (ISO 8601 format: `2025-05-01T00:00:00Z`). If both `from` and `to` are provided, `from` must be before or equal to `to`.
</ParamField>

<ParamField query="to" type="string" format="date-time">
  End date for date range filter (ISO 8601 format: `2025-06-01T00:00:00Z`). If both `from` and `to` are provided, `to` must be after or equal to `from`.
</ParamField>

<ParamField query="userPrimaryIntent" type="string">
  Filter calls by the user's primary intent detected during the call.
</ParamField>

<ParamField query="sort" type="string" default="desc">
  Sort order for results. Possible values: `asc`, `desc`, `duration_desc`, `duration_asc`.
</ParamField>

### Response

<ResponseField name="calls" type="array">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the call
    </ResponseField>

    <ResponseField name="organizationId" type="string">
      Organization ID the call belongs to
    </ResponseField>

    <ResponseField name="callType" type="string">
      Type of call: `Inbound`, `Outbound`, or `Web`
    </ResponseField>

    <ResponseField name="agentId" type="string" nullable>
      ID of the agent/assistant that handled the call
    </ResponseField>

    <ResponseField name="agentName" type="string" nullable>
      Name of the agent/assistant
    </ResponseField>

    <ResponseField name="teamId" type="string" nullable>
      ID of the team that owns the assistant. `null` for organizations that don't use teams.
    </ResponseField>

    <ResponseField name="teamName" type="string" nullable>
      Name of the team that owns the assistant. `null` for organizations that don't use teams.
    </ResponseField>

    <ResponseField name="phoneNumber" type="string" nullable>
      Phone number associated with the call
    </ResponseField>

    <ResponseField name="callStartedAt" type="string" format="date-time" nullable>
      Timestamp when the call started (ISO 8601 format: `2025-05-28T14:20:15Z`)
    </ResponseField>

    <ResponseField name="callEndedAt" type="string" format="date-time" nullable>
      Timestamp when the call ended (ISO 8601 format: `2025-05-28T14:23:15Z`)
    </ResponseField>

    <ResponseField name="callDurationSeconds" type="string" nullable>
      Duration of the call in seconds
    </ResponseField>

    <ResponseField name="userPhoneNumber" type="string" nullable>
      Phone number of the user (if available)
    </ResponseField>

    <ResponseField name="createdAt" type="string" format="date-time">
      When the call record was created (ISO 8601 format: `2025-05-28T14:23:45Z`)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="properties">
    <ResponseField name="page" type="integer">
      Current page number
    </ResponseField>

    <ResponseField name="limit" type="integer">
      Number of items per page
    </ResponseField>

    <ResponseField name="total" type="integer">
      Total number of calls matching the filter criteria
    </ResponseField>

    <ResponseField name="totalPages" type="integer">
      Total number of pages available
    </ResponseField>

    <ResponseField name="hasNextPage" type="boolean">
      Whether there is a next page available
    </ResponseField>

    <ResponseField name="hasPreviousPage" type="boolean">
      Whether there is a previous page available
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Request

```bash theme={null}
curl -X GET "https://allomia.com/api/calls?organizationId=a1b2c3d4-e5f6-7890-abcd-123456789012&page=1&limit=10&callType=Inbound&from=2025-05-01T00%3A00%3A00Z&to=2025-06-01T00%3A00%3A00Z&sort=desc" \
  -H "Authorization: Bearer YOUR-API-KEY"
```

### Example Response

```json theme={null}
{
  "calls": [
    {
      "id": "f6a7b8c9-d0e1-2345-fabc-678901234567",
      "organizationId": "a1b2c3d4-e5f6-7890-abcd-123456789012",
      "callType": "Inbound",
      "agentId": "g7b8c9d0-e1f2-3456-abcd-789012345678",
      "agentName": "Dr. Smith Assistant",
      "teamId": "t1e2a3m4-5678-9012-abcd-ef1234567890",
      "teamName": "Front Desk",
      "phoneNumber": "+15559876543",
      "callStartedAt": "2025-05-28T14:20:15Z",
      "callEndedAt": "2025-05-28T14:23:15Z",
      "callDurationSeconds": "180",
      "userPhoneNumber": "+15551234567",
      "createdAt": "2025-05-28T14:23:45Z"
    },
    {
      "id": "h8c9d0e1-f2a3-4567-bcde-890123456789",
      "organizationId": "a1b2c3d4-e5f6-7890-abcd-123456789012",
      "callType": "Inbound",
      "agentId": "g7b8c9d0-e1f2-3456-abcd-789012345678",
      "agentName": "Dr. Smith Assistant",
      "teamId": null,
      "teamName": null,
      "phoneNumber": "+15559876543",
      "callStartedAt": "2025-05-27T09:10:34Z",
      "callEndedAt": "2025-05-27T09:12:34Z",
      "callDurationSeconds": "120",
      "userPhoneNumber": "+15552345678",
      "createdAt": "2025-05-27T09:12:34Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "totalPages": 5,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}
```

### Error Responses

<AccordionGroup>
  <Accordion title="400: Invalid request data">
    The API performs comprehensive validation and returns detailed error information.

    **Invalid callType:**

    ```json theme={null}
    {
      "error": "Invalid request data",
      "details": [
        {
          "field": "callType",
          "message": "Invalid enum value. Expected 'Inbound' | 'Outbound' | 'Web', received 'fax'",
          "code": "invalid_enum_value"
        }
      ]
    }
    ```

    **Invalid date format:**

    ```json theme={null}
    {
      "error": "Invalid request data",
      "details": [
        {
          "field": "from",
          "message": "Invalid date format. Expected ISO 8601 format (e.g., 2025-05-01T00:00:00Z)",
          "code": "custom"
        }
      ]
    }
    ```

    **Invalid date range (`from` after `to`):**

    ```json theme={null}
    {
      "error": "Invalid request data",
      "details": [
        {
          "field": "from",
          "message": "The 'from' date must be before or equal to the 'to' date",
          "code": "custom"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="401: Unauthorized">
    ```json theme={null}
    {
      "error": "Invalid or missing API key"
    }
    ```
  </Accordion>

  <Accordion title="404: Organization not found">
    ```json theme={null}
    {
      "error": "Organization not found"
    }
    ```
  </Accordion>

  <Accordion title="500: Error">
    ```json theme={null}
    {
      "error": "Internal server error occurred"
    }
    ```
  </Accordion>
</AccordionGroup>