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

# Call management API

> API endpoints for retrieving call logs, live calls, recordings, and call statistics.

## Get call history

Retrieve paginated call logs with optional filtering.

```
GET /api/v1/calls
```

### Query parameters

| Parameter     | Type   | Description                                       |
| ------------- | ------ | ------------------------------------------------- |
| `limit`       | number | Records per page (1-200, default: 20)             |
| `offset`      | number | Records to skip                                   |
| `direction`   | string | Filter: `inbound`, `outbound`, or `internal`      |
| `disposition` | string | Filter: `ANSWERED`, `NO ANSWER`, `FAILED`, `BUSY` |
| `from`        | string | Filter by caller number                           |
| `to`          | string | Filter by destination number                      |
| `date_from`   | string | Start date (ISO format)                           |
| `date_to`     | string | End date (ISO format)                             |
| `search`      | string | Search across all fields                          |

### Example

```bash theme={null}
curl -X GET "https://your-server:8000/api/v1/calls?limit=10&direction=inbound" \
  -H "X-API-Key: ak_your_api_key"
```

### Response

```json theme={null}
{
  "data": [
    {
      "id": "123",
      "from_number": "9944421125",
      "to_number": "1001",
      "direction": "inbound",
      "status": "ANSWERED",
      "duration": 145,
      "talk_time": 120,
      "started_at": "2026-04-13T10:30:00Z",
      "ended_at": "2026-04-13T10:32:25Z",
      "recording_url": "/api/v1/calls/123/recording"
    }
  ],
  "total": 150,
  "page": 1,
  "pages": 15
}
```

## Get live calls

Retrieve currently active calls.

```
GET /api/v1/calls/live
```

### Example

```bash theme={null}
curl -X GET https://your-server:8000/api/v1/calls/live \
  -H "X-API-Key: ak_your_api_key"
```

### Response

```json theme={null}
[
  {
    "channel_id": "PJSIP/1001-00000001",
    "from": "9944421125",
    "to": "1001",
    "direction": "inbound",
    "status": "answered",
    "duration": 45
  }
]
```

## Get call count

```
GET /api/v1/calls/count
```

Returns the total number of calls matching the given filters. Accepts the same query parameters as the call history endpoint.

## Get call statistics

```
GET /api/v1/calls/stats
```

Returns aggregated call statistics for the dashboard:

```json theme={null}
{
  "total_calls": 1250,
  "inbound": 800,
  "outbound": 350,
  "internal": 100,
  "answered": 1100,
  "missed": 150,
  "avg_duration": 180,
  "weekly": [
    {"date": "2026-04-07", "inbound": 120, "outbound": 50},
    {"date": "2026-04-08", "inbound": 115, "outbound": 55}
  ]
}
```

## Get call recording

Download a call's audio recording.

```
GET /api/v1/calls/{callId}/recording
```

Requires `calls.recording` permission. Returns the audio file directly.

### Example

```bash theme={null}
curl -X GET "https://your-server:8000/api/v1/calls/123/recording" \
  -H "X-API-Key: ak_your_api_key" \
  -o recording.wav
```

## Get call journey

Retrieve the step-by-step journey of a call.

```
GET /api/v1/calls/{linkedId}/journey
```

### Response

```json theme={null}
{
  "linkedid": "abc-123",
  "caller": "9944421125",
  "destination": "1001",
  "status": "answered",
  "total_duration": 145,
  "answered_by": "1001",
  "steps": [
    {
      "time": "2026-04-13T10:30:00Z",
      "action": "Queue",
      "from": "9944421125",
      "to": "5001",
      "duration": 25,
      "status": "queued"
    },
    {
      "time": "2026-04-13T10:30:25Z",
      "action": "Bridged",
      "from": "9944421125",
      "to": "1001",
      "duration": 120,
      "status": "answered"
    }
  ]
}
```

## Transfer a call

```
POST /api/v1/calls/transfer
```

### Request body

```json theme={null}
{
  "call_id": "PJSIP/1001-00000001",
  "destination": "1002",
  "type": "blind"
}
```

## Hang up a call

```
POST /api/v1/calls/hangup-channel
```

### Request body

```json theme={null}
{
  "channel_id": "PJSIP/1001-00000001",
  "reason": "normal"
}
```