> ## 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 call logs for the authenticated tenant

> Returns a paginated list of call logs with summary information. Use query parameters to filter by status, phone number, direction, etc.

Returns a paginated list of call logs with summary information.
Use query parameters to filter by status, phone number, direction, etc.

### Query parameters

<ParamField query="status" type="string">
  Filter by call status
</ParamField>

<ParamField query="outcome" type="string">
  Filter by normalized terminal outcome: answered, voicemail, no\_answer, busy, failed
</ParamField>

<ParamField query="from_number" type="string">
  Filter by caller phone number
</ParamField>

<ParamField query="to_number" type="string">
  Filter by called phone number
</ParamField>

<ParamField query="direction" type="string">
  Filter by call direction (inbound/outbound)
</ParamField>

<ParamField query="escalated" type="boolean">
  Filter by escalation status
</ParamField>

<ParamField query="from_date" type="string">
  Only calls after this ISO8601 datetime
</ParamField>

<ParamField query="to_date" type="string">
  Only calls before this ISO8601 datetime
</ParamField>

<ParamField query="min_duration" type="integer (int32)">
  Minimum call duration in seconds
</ParamField>

<ParamField query="max_duration" type="integer (int32)">
  Maximum call duration in seconds
</ParamField>

<ParamField query="transcript_search" type="string">
  Search transcript text (case-insensitive)
</ParamField>

<ParamField query="call_sid" type="string">
  Filter by Twilio call SID
</ParamField>

<ParamField query="limit" type="integer (int64)">
  Maximum number of results (default 50, max 100)
</ParamField>

<ParamField query="offset" type="integer (int64)">
  Legacy offset-based pagination. Prefer `cursor` (keyset pagination)
  for any list longer than a few hundred rows.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque keyset cursor returned by a previous response's `next_cursor`.
  Pass it back to fetch the next page; takes precedence over `offset`.
</ParamField>

### Response

`CallLogsListResponse`

<ResponseField name="calls" type="CallLogSummary[]" required>
  Compact call summaries

  <Expandable title="CallLogSummary">
    <ResponseField name="direction" type="string" required>
      Call direction: 'inbound' or 'outbound'
    </ResponseField>

    <ResponseField name="duration_seconds" type="integer,null (int32)">
      Call duration in seconds
    </ResponseField>

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

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

    <ResponseField name="from_number" type="string,null">
      Caller phone number
    </ResponseField>

    <ResponseField name="function_call_count" type="integer" required>
      Number of AI function calls made during the conversation
    </ResponseField>

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

    <ResponseField name="outcome" type="string,null">
      Normalized terminal outcome: answered, voicemail, no\_answer, busy, failed
    </ResponseField>

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

    <ResponseField name="status" type="string" required>
      Call status: in\_progress, completed, failed, escalated, busy, no\_answer, canceled
    </ResponseField>

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

    <ResponseField name="to_number" type="string,null">
      Called phone number
    </ResponseField>

    <ResponseField name="transcript_length" type="integer" required>
      Number of transcript turns
    </ResponseField>
  </Expandable>
</ResponseField>

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

<ResponseField name="next_cursor" type="string,null">
  Opaque cursor to pass back as `?cursor=...` to fetch the next page.
  `null` when this is the last page. Prefer this over `offset` for
  large tenants — it is O(log n) regardless of page depth.
</ResponseField>

<ResponseField name="ok" type="boolean" required>
  Whether the request succeeded
</ResponseField>

<ResponseField name="tenant" type="string" required>
  Authenticated tenant identifier
</ResponseField>

### Status codes

| Code  | Meaning                        |
| ----- | ------------------------------ |
| `200` | List of call logs              |
| `400` | Invalid query filter           |
| `401` | Unauthorized                   |
| `500` | Internal server error          |
| `503` | Call logging is not configured |

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.voice.stateset.com/api/v1/call-logs' \
    --header 'Authorization: Bearer YOUR_API_KEY'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "calls": [
      {
        "direction": "inbound",
        "duration_seconds": 142,
        "ended_at": "2024-01-15T10:32:22Z",
        "escalated": false,
        "from_number": "+15555555678",
        "function_call_count": 3,
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "outcome": null,
        "started_at": "2024-01-15T10:30:00Z",
        "status": "completed",
        "stream_sid": "MZ1234567890abcdef1234567890abcdef",
        "to_number": "+15555551234",
        "transcript_length": 12
      }
    ],
    "count": 25,
    "next_cursor": null,
    "ok": true,
    "tenant": "tenant_123"
  }
  ```
</ResponseExample>