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

# List Call Logs

> Returns a paginated list of call transcripts and logs for a specific agent

## Path Parameters

<ParamField path="agentId" type="string" required>
  The agent ID to retrieve call logs for (UUID format)
</ParamField>

## Query Parameters

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

<ParamField query="limit" type="integer" default="50">
  Number of items per page (max 100)
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  # Get call logs for an agent
  curl "https://api.telzino.com/v1/agents/123e4567-e89b-12d3-a456-426614174000/call-logs?page=1&limit=50" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const agentId = '123e4567-e89b-12d3-a456-426614174000';

  const response = await fetch(
    `https://api.telzino.com/v1/agents/${agentId}/call-logs?page=1&limit=50`,
    { headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' } }
  );

  const { data, pagination } = await response.json();

  // Access transcript data
  data.forEach(log => {
    console.log(`Call on ${log.call_started_at}: ${log.entry_count} messages, ${log.call_duration}s`);
    console.log(log.transcript_text);
  });
  ```

  ```python Python theme={null}
  import requests

  agent_id = '123e4567-e89b-12d3-a456-426614174000'

  response = requests.get(
      f'https://api.telzino.com/v1/agents/{agent_id}/call-logs',
      params={'page': 1, 'limit': 50},
      headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'}
  )

  data = response.json()

  # Access transcript data
  for log in data['data']:
      print(f"Call: {log['call_started_at']} - Duration: {log['call_duration']}s")
      print(log['transcript_text'])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "log-123e4567-e89b-12d3-a456-426614174000",
        "agent_id": "123e4567-e89b-12d3-a456-426614174000",
        "room_name": "sipRoom-_123e4567-e89b-12d3-a456-426614174000_1704067800",
        "transcript_text": "[0.50s] agent: Hello! How can I help you today?\n[3.20s] user: I have a question about my order.\n[5.10s] agent: I'd be happy to help with your order. What's your order number?",
        "transcript_json": [
          {
            "text": "Hello! How can I help you today?",
            "speaker": "agent",
            "timestamp": 0.5,
            "is_partial": false,
            "created_at": 0.5
          },
          {
            "text": "I have a question about my order.",
            "speaker": "user",
            "timestamp": 3.2,
            "is_partial": false,
            "created_at": 3.2
          },
          {
            "text": "I'd be happy to help with your order. What's your order number?",
            "speaker": "agent",
            "timestamp": 5.1,
            "is_partial": false,
            "created_at": 5.1
          }
        ],
        "entry_count": 15,
        "call_duration": 180,
        "call_started_at": "2024-01-15T14:30:00.000Z",
        "call_ended_at": "2024-01-15T14:33:00.000Z",
        "session_data": {
          "room_name": "sipRoom-_123e4567...",
          "agent_id": "123e4567-e89b-12d3-a456-426614174000",
          "total_entries": 15,
          "final_entries": 15,
          "caller_id": "+14155551234"
        },
        "summary_text": "Order Status Inquiry\n\nCustomer called to check on order #12345. Agent confirmed the order was shipped and provided tracking number.\n\n**Action Items:**\n- ✓ Provided tracking number to customer\n- None pending\n\n**Sentiment:** Positive",
        "recording_url": "https://telzino-recordings.s3.amazonaws.com/calls/123e4567.ogg",
        "created_at": "2024-01-15T14:33:05.000Z",
        "updated_at": "2024-01-15T14:33:10.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 245,
      "totalPages": 5,
      "hasNext": true,
      "hasPrev": false
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": "invalid_token",
    "error_description": "Missing or invalid authorization token"
  }
  ```

  ```json 403 theme={null}
  {
    "error": "forbidden",
    "error_description": "No access to this agent"
  }
  ```

  ```json 404 theme={null}
  {
    "error": "not_found",
    "error_description": "Agent not found"
  }
  ```
</ResponseExample>

## Call Log Object

### Core Fields

| Field       | Type   | Description                       |
| ----------- | ------ | --------------------------------- |
| `id`        | string | Unique call log identifier (UUID) |
| `agent_id`  | string | Agent that handled the call       |
| `room_name` | string | Room identifier for the call      |

### Transcript Data

| Field             | Type    | Description                                                        |
| ----------------- | ------- | ------------------------------------------------------------------ |
| `transcript_text` | string  | Plain text version with timestamps (e.g., `[0.50s] agent: Hello!`) |
| `transcript_json` | array   | Structured transcript entries (see below)                          |
| `entry_count`     | integer | Total number of transcript entries                                 |
| `summary_text`    | string  | AI-generated summary of the call (Markdown format)                 |

**transcript\_json entry structure:**

```json theme={null}
{
  "text": "Message content",
  "speaker": "agent" | "user" | "system",
  "timestamp": 0.5,
  "is_partial": false,
  "created_at": 0.5
}
```

<Info>
  **System entries** are logged for events like call transfers, webhook executions, and call end reasons.
</Info>

### Call Timing

| Field             | Type     | Description                      |
| ----------------- | -------- | -------------------------------- |
| `call_duration`   | integer  | Call duration in seconds         |
| `call_started_at` | datetime | When the call started (ISO 8601) |
| `call_ended_at`   | datetime | When the call ended (ISO 8601)   |

### Session Metadata

| Field                        | Type    | Description                                   |
| ---------------------------- | ------- | --------------------------------------------- |
| `session_data`               | object  | Additional session information                |
| `session_data.caller_id`     | string  | Caller's phone number (e.g., `+14155551234`)  |
| `session_data.total_entries` | integer | Total transcript entries (including partials) |
| `session_data.final_entries` | integer | Final (non-partial) transcript entries        |

### Recording

| Field           | Type   | Description                                            |
| --------------- | ------ | ------------------------------------------------------ |
| `recording_url` | string | URL to call recording (if `enable_recording` was true) |

<Note>
  Recording URLs are pre-signed S3 URLs. They may expire after a period of time. Store recordings in your own storage if you need permanent access.
</Note>

### Timestamps

| Field        | Type     | Description                   |
| ------------ | -------- | ----------------------------- |
| `created_at` | datetime | When the log was created      |
| `updated_at` | datetime | When the log was last updated |

## AI Summary Format

The `summary_text` field contains an AI-generated summary in Markdown format:

```markdown theme={null}
Topic in 3-5 words

1-2 sentence summary of the call.

**Action Items:**
- ✓ Completed action
- Pending follow-up

**Sentiment:** Positive | Neutral | Negative
```