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

# List Calls

> StateSet Voice API operation.

StateSet Voice API operation.

### Query parameters

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

### Response

`object`

<ResponseField name="ok" type="boolean" required />

<ResponseField name="count" type="integer" required>
  Number of calls in this page
</ResponseField>

<ResponseField name="calls" type="CallLog[]" required>
  <Expandable title="CallLog">
    <ResponseField name="answered_by" type="AnsweredBy,null" />

    <ResponseField name="call_sid" type="string,null">
      Twilio call SID
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      When this record was created (ISO 8601)
    </ResponseField>

    <ResponseField name="direction" type="CallDirection" required>
      Direction of the call
    </ResponseField>

    <ResponseField name="duration_seconds" type="integer,null (int32)">
      Duration of the call in seconds
    </ResponseField>

    <ResponseField name="ended_at" type="string" required>
      When the call ended (ISO 8601)
    </ResponseField>

    <ResponseField name="error_message" type="string,null">
      Error message if call failed
    </ResponseField>

    <ResponseField name="escalated" type="boolean" required>
      Whether the call was escalated to a human
    </ResponseField>

    <ResponseField name="escalation_reason" type="string,null">
      Reason for escalation
    </ResponseField>

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

    <ResponseField name="function_calls" type="FunctionCallEntry[]" required>
      Functions called during the conversation

      <Expandable title="FunctionCallEntry">
        <ResponseField name="arguments" type="object" required>
          Arguments passed to the function
        </ResponseField>

        <ResponseField name="duration_ms" type="integer,null (int64)">
          How long the function took to execute in milliseconds
        </ResponseField>

        <ResponseField name="name" type="string" required>
          Name of the function called
        </ResponseField>

        <ResponseField name="result" type="object">
          Result returned by the function
        </ResponseField>

        <ResponseField name="timestamp" type="string" required>
          When the function was called (ISO 8601)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Unique identifier for this call log
    </ResponseField>

    <ResponseField name="model" type="string,null">
      AI model used
    </ResponseField>

    <ResponseField name="outcome" type="CallOutcome,null" />

    <ResponseField name="recording_url" type="string,null">
      URL to the call recording (from Twilio)
    </ResponseField>

    <ResponseField name="started_at" type="string" required>
      When the call started (ISO 8601)
    </ResponseField>

    <ResponseField name="status" type="CallStatus" required>
      Current status of the call
    </ResponseField>

    <ResponseField name="stream_sid" type="string" required>
      Twilio stream SID
    </ResponseField>

    <ResponseField name="summary" type="string,null">
      LLM-generated summary of the call
    </ResponseField>

    <ResponseField name="system_prompt_key" type="string,null">
      System prompt key used
    </ResponseField>

    <ResponseField name="tenant_id" type="string" required>
      Tenant that owns this call
    </ResponseField>

    <ResponseField name="to_number" type="string,null">
      Called phone number (E.164 format)
    </ResponseField>

    <ResponseField name="transcript" type="TranscriptEntry[]" required>
      Full conversation transcript

      <Expandable title="TranscriptEntry">
        <ResponseField name="content" type="string" required>
          Content of the message
        </ResponseField>

        <ResponseField name="role" type="string" required>
          Role of the speaker: 'user', 'assistant', or 'system'
        </ResponseField>

        <ResponseField name="timestamp" type="string" required>
          When this message was spoken (ISO 8601)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="updated_at" type="string" required>
      When this record was last updated (ISO 8601)
    </ResponseField>

    <ResponseField name="voice" type="string,null">
      Voice used for TTS
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="next_cursor" type="string,null" required>
  Cursor for the next page; null when this page is the last one
</ResponseField>

### Status codes

| Code  | Meaning                                              |
| ----- | ---------------------------------------------------- |
| `200` | Page of the tenant's call history, most recent first |
| `404` | Customer self-serve plane disabled                   |

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.voice.stateset.com/api/v1/customer/calls' \
    --header "Authorization: Bearer $STATESET_VOICE_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "ok": true,
    "count": 2,
    "calls": [
      {
        "answered_by": "human",
        "call_sid": "CA1234567890abcdef1234567890abcdef",
        "created_at": "2024-01-15T10:30:00Z",
        "direction": "inbound",
        "duration_seconds": 142,
        "ended_at": "2024-01-15T10:32:22Z",
        "error_message": "WebSocket connection closed unexpectedly",
        "escalated": false,
        "escalation_reason": "Customer requested to speak with a human agent",
        "from_number": "+15555555678",
        "function_calls": [],
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "model": "gpt-4o-realtime-preview",
        "outcome": "answered",
        "recording_url": "https://api.twilio.com/2010-04-01/Accounts/AC123/Recordings/RE456.json",
        "started_at": "2024-01-15T10:30:00Z",
        "status": "in_progress",
        "stream_sid": "MZ1234567890abcdef1234567890abcdef",
        "summary": "Customer called to check order status for order #12345. Agent confirmed the order shipped yesterday.",
        "system_prompt_key": "default",
        "tenant_id": "tenant-123",
        "to_number": "+15555551234",
        "transcript": [],
        "updated_at": "2024-01-15T10:32:22Z",
        "voice": "alloy"
      }
    ],
    "next_cursor": "string"
  }
  ```
</ResponseExample>