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

# List Calls

Retrieve a paginated list of calls for your organization.

### Query Parameters

<ParamField query="limit" type="integer" default="50">
  Maximum number of calls to return (1-100).
</ParamField>

<ParamField query="cursor" type="string">
  Base64-encoded cursor from previous response for pagination. Omit for first page.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful.
</ResponseField>

<ResponseField name="data" type="array">
  List of call summary objects.
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata.

  * `next_cursor`: Cursor for fetching next page
  * `has_more`: Boolean indicating if more results exist
  * `page_size`: Number of results in current page
</ResponseField>

### Call Summary Fields

<ResponseField name="call_sid" type="string" required>
  Unique call identifier (format: `call_` prefix + alphanumeric).
</ResponseField>

<ResponseField name="to_number" type="string" required>
  Phone number that was called (E.164 format).
</ResponseField>

<ResponseField name="from_number" type="string">
  Caller phone number (E.164 format).
</ResponseField>

<ResponseField name="agent_id" type="string" required>
  ID of the agent that handled the call.
</ResponseField>

<ResponseField name="agent_name" type="string">
  Name of the agent.
</ResponseField>

<ResponseField name="call_type" type="string">
  Type of call: `inbound`, `outbound`, or `preview`.
</ResponseField>

<ResponseField name="status" type="string">
  Current call status (e.g., `completed`, `ringing`, `in_progress`).
</ResponseField>

<ResponseField name="recording_enabled" type="boolean">
  Whether recording was enabled for this call.
</ResponseField>

<ResponseField name="total_cost" type="number">
  Total cost in credits.
</ResponseField>

<ResponseField name="duration_seconds" type="number">
  Call duration in seconds.
</ResponseField>

<ResponseField name="turn_count" type="number">
  Number of conversation turns.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO8601 timestamp when the call was created.
</ResponseField>

<ResponseField name="end_reason" type="string">
  Reason why the call ended (e.g., `tool_end_call`, `user_hangup`).
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "call_sid": "call_abc123def456",
        "to_number": "+15559876543",
        "from_number": "+15551234567",
        "agent_id": "agent_xyz789",
        "agent_name": "Sales Rep",
        "client_id": "org_123",
        "call_type": "outbound",
        "status": "completed",
        "recording_enabled": true,
        "total_cost": 12.35,
        "duration_seconds": 120.5,
        "turn_count": 7,
        "created_at": "2026-03-09T10:00:00Z",
        "updated_at": "2026-03-09T10:02:30Z",
        "start_time": "2026-03-09T10:00:05Z",
        "end_time": "2026-03-09T10:02:25Z",
        "end_reason": "tool_end_call",
        "billing_status": "billed"
      }
    ],
    "pagination": {
      "next_cursor": "eyJjYWxsX3NpZCI6ICJjYWxsX2FiYzEyMyJ9",
      "has_more": true,
      "page_size": 50
    }
  }
  ```
</ResponseExample>

<Note>
  This endpoint uses cursor-based pagination. Use the `next_cursor` from the response
  to fetch subsequent pages. Omit the cursor parameter for the first page.
</Note>