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

# Calls

> List call records, retrieve transcripts and recordings, and initiate outbound calls.

The Calls API gives you access to your complete call history — including transcripts, recordings, sentiment analysis, and AI-generated summaries — and lets you programmatically place outbound calls from any agent.

## List calls

Returns a paginated list of call records. Use query parameters to filter by agent, direction, or date range.

<ParamField query="agent_id" type="string">
  Filter results to calls handled by a specific agent.
</ParamField>

<ParamField query="direction" type="string">
  Filter by call direction. Accepted values: `"inbound"` or `"outbound"`.
</ParamField>

<ParamField query="from" type="string">
  Return calls on or after this date and time (ISO 8601, e.g. `"2025-03-01T00:00:00Z"`).
</ParamField>

<ParamField query="to" type="string">
  Return calls on or before this date and time (ISO 8601).
</ParamField>

<ParamField query="limit" type="integer">
  Number of results per page. Default: `20`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.boltcall.org/v1/calls?direction=inbound&limit=20" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({ direction: 'inbound', limit: '20' });
  const response = await fetch(`https://api.boltcall.org/v1/calls?${params}`, {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
  });
  const { data, meta } = await response.json();
  ```

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

  response = requests.get(
      'https://api.boltcall.org/v1/calls',
      params={'direction': 'inbound', 'limit': 20},
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
  )
  result = response.json()
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": [
    {
      "id": "call_xyz789",
      "agent_id": "agent_abc123",
      "direction": "inbound",
      "caller": "+1987654321",
      "duration_seconds": 142,
      "status": "completed",
      "sentiment": "positive",
      "recording_url": "https://api.boltcall.org/v1/calls/call_xyz789/recording",
      "transcript_url": "https://api.boltcall.org/v1/calls/call_xyz789/transcript",
      "created_at": "2025-03-20T09:15:00Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 156 }
}
```

***

## Get a call

Returns full details for a single call, including the turn-by-turn transcript and AI summary.

**Path parameter**

<ParamField path="call_id" type="string" required>
  The unique ID of the call to retrieve.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.boltcall.org/v1/calls/call_xyz789 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.boltcall.org/v1/calls/call_xyz789', {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
  });
  const call = await response.json();
  ```

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

  call = requests.get(
      'https://api.boltcall.org/v1/calls/call_xyz789',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
  ).json()
  ```
</CodeGroup>

```json Response theme={null}
{
  "id": "call_xyz789",
  "agent_id": "agent_abc123",
  "direction": "inbound",
  "caller": "+1987654321",
  "duration_seconds": 142,
  "status": "completed",
  "sentiment": "positive",
  "summary": "Caller requested appointment for Friday.",
  "tags": ["appointment", "new-customer"],
  "recording_url": "https://...",
  "transcript": [
    { "role": "agent", "text": "Hello, thanks for calling..." },
    { "role": "caller", "text": "Hi, I'd like to book..." }
  ],
  "created_at": "2025-03-20T09:15:00Z"
}
```

<Expandable title="Response fields">
  <ResponseField name="id" type="string">
    Unique call identifier.
  </ResponseField>

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

  <ResponseField name="direction" type="string">
    `"inbound"` or `"outbound"`.
  </ResponseField>

  <ResponseField name="caller" type="string">
    Phone number of the caller in E.164 format.
  </ResponseField>

  <ResponseField name="duration_seconds" type="integer">
    Total call duration in seconds.
  </ResponseField>

  <ResponseField name="status" type="string">
    Call status: `"completed"`, `"missed"`, or `"failed"`.
  </ResponseField>

  <ResponseField name="sentiment" type="string">
    AI-detected caller sentiment: `"positive"`, `"neutral"`, or `"negative"`.
  </ResponseField>

  <ResponseField name="summary" type="string">
    AI-generated summary of the call.
  </ResponseField>

  <ResponseField name="tags" type="string[]">
    Auto-applied tags based on call content.
  </ResponseField>

  <ResponseField name="recording_url" type="string">
    URL to download the call recording (authenticated).
  </ResponseField>

  <ResponseField name="transcript" type="object[]">
    Turn-by-turn conversation. Each item has `role` (`"agent"` or `"caller"`) and `text`.
  </ResponseField>

  <ResponseField name="created_at" type="string">
    ISO 8601 timestamp when the call started.
  </ResponseField>
</Expandable>

***

## Initiate an outbound call

Places an outbound call from an agent to a specified phone number. The agent uses the optional `context` to brief itself before the call.

<ParamField body="agent_id" type="string" required>
  ID of the agent that will place the call.
</ParamField>

<ParamField body="to" type="string" required>
  Destination phone number in E.164 format (e.g. `"+15550001111"`).
</ParamField>

<ParamField body="context" type="string">
  Briefing context shown to the agent before it dials. Use this to provide lead details, appointment reminders, or campaign instructions.
</ParamField>

<Note>
  Outbound calls are placed immediately on receiving the request. Ensure the agent is in `"active"` status before calling this endpoint.
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.boltcall.org/v1/calls/outbound \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "agent_id": "agent_abc123",
      "to": "+15550001111",
      "context": "Follow up on dental cleaning inquiry"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.boltcall.org/v1/calls/outbound', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      agent_id: 'agent_abc123',
      to: '+15550001111',
      context: 'Follow up on dental cleaning inquiry',
    }),
  });
  const call = await response.json();
  ```

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

  call = requests.post(
      'https://api.boltcall.org/v1/calls/outbound',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      json={
          'agent_id': 'agent_abc123',
          'to': '+15550001111',
          'context': 'Follow up on dental cleaning inquiry',
      },
  ).json()
  ```
</CodeGroup>

```json Response theme={null}
{
  "id": "call_out001",
  "status": "ringing",
  "agent_id": "agent_abc123",
  "to": "+15550001111",
  "created_at": "2025-03-20T14:30:00Z"
}
```

Subscribe to the `call_completed` [webhook event](/api/webhooks) to receive the full call result when it ends.