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

# Calls

> Retrieve call detail records (CDRs) and call insights for SIP trunk calls

The Calls API lets you retrieve call detail records (CDRs) and quality insights for calls made through your SIP trunks.

## API Endpoint

```text theme={null}
https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Call/
```

***

## The Call Object

### Attributes

**call\_uuid** `string`

Unique call identifier.

**from\_number** `string`

Caller ID. On India domestic calls retried through [automatic carrier failover](https://plivo.com/docs/voice/concepts/carrier-failover.md), this field records the fallback caller ID used on the retry, not the number you originally sent.

**to\_number** `string`

Destination number.

**call\_direction** `string`

Direction. Values: `inbound`, `outbound`.

**call\_duration** `integer`

Actual call duration in seconds.

**bill\_duration** `integer`

Billed duration in seconds.

**billed\_duration** `integer`

Billed duration (may differ based on billing interval).

**initiation\_time** `string`

When call was initiated (UTC).

**answer\_time** `string`

When call was answered (UTC).

**end\_time** `string`

When call ended (UTC).

**hangup\_cause\_name** `string`

Reason for hangup.

**hangup\_cause\_code** `integer`

Numeric hangup cause code.

**hangup\_source** `string`

Who ended the call. Values: `customer`, `carrier`, `zentrunk`.

**total\_rate** `string`

Per-minute rate (USD).

**total\_amount** `string`

Total cost (USD).

**trunk\_domain** `string`

Trunk domain used.

**from\_country** `string`

Caller's country (ISO2).

**to\_country** `string`

Destination country (ISO2).

**transport\_protocol** `string`

Protocol used (e.g., `udp`, `tcp`).

**srtp** `boolean`

Whether SRTP encryption was used.

**secure\_trunking** `boolean`

Whether secure trunking was enabled.

**secure\_trunking\_rate** `string`

Secure trunking per-minute rate.

**stir\_verification** `string`

STIR/SHAKEN status.

**attestation\_indicator** `string`

Attestation level. Values: `A`, `B`, `C`.

### Example Response

```json theme={null}
{
  "call_uuid": "90b6eb07-796c-4d86-a4fd-44ed11667ddb",
  "from_number": "+12025551234",
  "to_number": "+13125551234",
  "call_direction": "outbound",
  "call_duration": 180,
  "bill_duration": 180,
  "billed_duration": 180,
  "end_time": "2024-01-15 14:32:00",
  "hangup_cause_name": "normal_hangup",
  "hangup_source": "carrier",
  "total_rate": "0.00500",
  "total_amount": "0.01500",
  "initiation_time": "2024-01-15 14:28:48",
  "answer_time": "2024-01-15 14:29:00",
  "trunk_domain": "93667062664669661.zt.plivo.com",
  "from_country": "US",
  "to_country": "US",
  "transport_protocol": "udp",
  "srtp": false,
  "hangup_cause_code": 3000,
  "secure_trunking": false,
  "secure_trunking_rate": "0.00000",
  "stir_verification": "Verified",
  "attestation_indicator": "A"
}
```

***

## Retrieve a Call

Get the call detail record (CDR) for a specific call.

```text theme={null}
GET https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Call/{call_uuid}/
```

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Call/90b6eb07-796c-4d86-a4fd-44ed11667ddb/
```

### Response

Returns the Call object for the specified call UUID.

***

## List All Calls

Retrieve CDRs for all calls with optional filtering.

```text theme={null}
GET https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Call/
```

### Query Parameters

**from\_number** `string`

Filter by caller ID (exact or prefix).

**to\_number** `string`

Filter by destination (exact or prefix).

**call\_direction** `string`

Filter by direction. Values: `inbound`, `outbound`.

**hangup\_cause\_code** `integer`

Filter by hangup cause code.

**hangup\_source** `string`

Filter by hangup source. Values: `customer`, `carrier`, `zentrunk`.

**stir\_verification** `string`

Filter by STIR status. Values: `Verified`, `Not Verified`, `Not Applicable`.

**bill\_duration** `integer`

Filter by duration in seconds. Supports variants: `bill_duration__gt`, `bill_duration__gte`, `bill_duration__lt`, `bill_duration__lte`.

**end\_time** `string`

Filter by call end time. Format: `YYYY-MM-DD HH:MM[:ss]` (UTC). Supports variants: `end_time__gt`, `end_time__gte`, `end_time__lt`, `end_time__lte`.

**limit** `integer`

Results per page. Max: 20. Default: 20.

**offset** `integer`

Pagination offset. Default: 0.

> [!NOTE]
>
> You can retrieve only calls from the last 90 days. Without an `end_time` filter, the API searches the last 30 days.

### Example Request

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    "https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Call/?call_direction=outbound&end_time__gte=2024-01-01%2000:00&limit=20"
```

### Response

**api\_id** `string`

Unique identifier for the API request.

**meta** `object`

Pagination metadata: `limit` (results per page), `offset` (items skipped), `total_count` (total matching calls).

**objects** `array`

Array of call objects — see [The Call Object](#the-call-object).

```json theme={null}
{
  "api_id": "a04ad809-3b78-4bbe-9baf-acfc7800b10f",
  "meta": {
    "limit": 20,
    "offset": 0,
    "total_count": 2,
    "previous": null,
    "next": null
  },
  "objects": [
    {
      "call_uuid": "90b6eb07-796c-4d86-a4fd-44ed11667ddb",
      "from_number": "+12025551111",
      "to_number": "+13125551234",
      "call_direction": "outbound",
      "call_duration": 180,
      "bill_duration": 180,
      "stir_verification": "Verified",
      "attestation_indicator": "A"
    }
  ]
}
```

***

## Retrieve Call Insights

Get quality metrics for a specific call.

```text theme={null}
GET https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Call/{call_uuid}/Insights/
```

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Call/c9d6be3d-94c3-4b38-a2eb-8063ca404d77/Insights/
```

### Response

**api\_id** `string`

Unique identifier for the API request.

**call\_uuid** `string`

Unique call identifier.

**from** `object`

Details of the caller: `carrier`, `number`, and `region`.

**to** `object`

Details of the destination: `carrier`, `number`, and `region`.

**hangup\_cause** `string`

Reason for hangup.

**hangup\_source** `string`

Who ended the call. Values: `customer`, `carrier`, `zentrunk`.

**rtt** `string`

Round-trip time in milliseconds. High values indicate network latency.

**jitter** `string`

Variance in packet delay (ms). Causes robotic-sounding audio.

**packet\_loss** `string`

Percentage of lost packets. Causes broken audio.

**post\_dial\_delay** `float`

Time from call initiation to ringing (ms).

**plivo\_quality\_score** `string`

Quality rating from 1-5. Higher is better.

```json theme={null}
{
  "api_id": "a63df7e3-9f24-4aae-2152-dc8f92548290",
  "call_uuid": "c9d6be3d-94c3-4b38-a2eb-8063ca404d77",
  "from": {
    "carrier": "Verizon Wireless",
    "number": "+12025551234",
    "region": "US"
  },
  "to": {
    "carrier": "AT&T",
    "number": "+13125551234",
    "region": "US"
  },
  "hangup_cause": "normal_hangup",
  "hangup_source": "customer",
  "rtt": "24",
  "jitter": "3",
  "packet_loss": "0",
  "post_dial_delay": 1000.0,
  "plivo_quality_score": "4.2"
}
```

### Insights Metrics

**rtt** `string`

Round-trip time in milliseconds. High values indicate network latency.

**jitter** `string`

Variance in packet delay (ms). Causes robotic-sounding audio.

**packet\_loss** `string`

Percentage of lost packets. Causes broken audio.

**post\_dial\_delay** `float`

Time from call initiation to ringing (ms).

**plivo\_quality\_score** `string`

Quality rating from 1-5. Higher is better.

### Quality Score Guidelines

| Score | Quality |
| - | - |
| `4.0 - 5.0` | Excellent |
| `3.0 - 4.0` | Good |
| `2.0 - 3.0` | Fair |
| `1.0 - 2.0` | Poor |

***

## STIR/SHAKEN Verification

The `stir_verification` field indicates call authenticity:

| Value | Description |
| - | - |
| `Verified` | Caller verified with attestation level A |
| `Not Verified` | Attestation level B or C |
| `Not Applicable` | Non-US calls or cloud calls (WebRTC/SIP) |

***

## Hangup Sources

| Source | Description |
| - | - |
| `customer` | Your infrastructure ended the call |
| `carrier` | The terminating carrier ended the call |
| `zentrunk` | Plivo's SIP trunking platform ended the call |

***

## Related

* [Trunks](https://plivo.com/docs/sip-trunking/api/trunks.md) - Manage SIP trunks
* [Hangup Codes](https://plivo.com/docs/sip-trunking/troubleshooting/zentrunk-hangup-codes.md) - Complete hangup cause reference