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

# Account & Billing llms-full.txt

> Complete machine-readable documentation content for Account & Billing (Other APIs) for AI agents and LLMs

# Telnyx Other APIs: Account & Billing — Full Documentation

> Complete page content for Account & Billing (Other APIs section) of the Telnyx developer docs ([https://developers.telnyx.com](https://developers.telnyx.com)).
> Root index: [https://developers.telnyx.com/llms.txt](https://developers.telnyx.com/llms.txt) · Lightweight index for this subsection: [https://developers.telnyx.com/development/llms/other-apis-account-billing-llms-txt.md](https://developers.telnyx.com/development/llms/other-apis-account-billing-llms-txt.md)

## Usage reports

### Usage Reports

> Source: [https://developers.telnyx.com/docs/reporting/usage-reports.md](https://developers.telnyx.com/docs/reporting/usage-reports.md)

## Overview

The (v2) Usage Reports API is a single endpoint that enables viewing aggregated usage data across all of a customer's Telnyx products. It is built to be flexible and customizable, so that you have programmatic access to view data in a way that makes sense to your business and use cases. It can be used to efficiently monitor usage trends and costs, as well as to directly integrate with your internal systems.

### Query Requirements

#### Products

A product from the Options response (see next section) must be included. At this time, there is not a way to view usage for all or multiple products at once.

Products Supported:

* Sip-Trunking (sip-trunking)
* Messaging (messaging)
* Voice API (call-control)
* Wireless (wireless)
* Cloud Storage (cloud-storage)
* Inference (inference)
* Verify 2fa (verify-2fa)
* Fax API (fax-api)
* WebRTC (webrtc)
* Calls per Second (cps)
* Conference (conference)
* Video API (programmable-video)
* Call Control Features (call-control-features)
* Customer Service Record (customer-service-record)
* Media Streaming (media-streaming)
* Noise Suppression (noise-suppression)
* Text to Speech (text-to-speech)
* Speech to Text (speech-to-text)
* Recording (recording)
* Forking (forking)
* Media Storage (media-storage)
* Answering Machine Detection (amd)

#### Dates

The start and end date parameters should be in the format `YYYY-MM-DDThh:mm:ssTZD` (eg `2022-12-24T19:20:30-05:00`). This allows you to specify the timespan in your local time by including the timezone offset. The `start_date` parameter is inclusive, while the `end_date` parameter is exclusive - e.g. if you wanted data for all of February, the `start_date` would be `2023-02-01T00:00:00-00:00` and the `end_date` would be `2023-03-01T00:00:00-00:00`. Billing usage is calculated using UTC. The maximum range supported is 31 days.

Another way to specify the timespan you want is to utilize the date literals spelled out in our developer docs - [https://developers.telnyx.com/api#date-literals](https://developers.telnyx.com/api#date-literals). This can be achieved by replacing `start_date` & `end_date` with `date_range` like this: `date_range=last_1_weeks`.

To see the requested data broken out by day for the timespan selected, there is a `date` dimension available on all products. Additionally, there’s a breakout by hour available using the `date_time` dimension.

#### Format

Specifying a format is optional. The endpoint returns JSON by default. At this time, the API also supports generating a CSV file from the response by specifying `format=csv` in your query.

## Dimensions & Metrics Options Per Product

To view the products with their dimensions and metrics available for reporting, you can make a request to the endpoint below.

Metrics are the values you’re interested in, for example, the number of calls attempted or the total cost of your usage. Dimensions are how you want your data broken out, for example, by connection, messaging profile, or the traffic’s direction.

Below, you’ll see a sample of the “Options” response for Sip-Trunking. If you already know the product you want and are looking for only its supported dimensions/metrics, you can pass the product parameter as shown in the example. If you want to see all products, simply leave off the product parameter.

##### Request:

*Don't forget to update `YOUR_API_KEY` here.*

```
curl --location 'https://api.telnyx.com/v2/usage_reports/options?product=sip-trunking' \
--header 'Authorization: Bearer YOUR_API_KEY
```

##### Response:

```json theme={null}
{
    "data": [
        {
            "product": "sip-trunking",
            "product_dimensions": [
                "date",
                "tn_type",
                "tags",
                "billing_group_id",
                "country_code",
                "outbound_profile_id",
                "source_tn_type",
                "date_time",
                "connection_id",
                "bundle_id",
                "short_duration_call",
                "source_country_code",
                "currency",
                "is_local_calling",
                "call_type",
                "direction"
            ],
            "product_metrics": [
                "connected",
                "cost",
                "attempted",
                "call_sec",
                "completed",
                "billed_sec"
            ],
            "record_types": null
        }
    ]
}
```

## Product Examples

### SIP Trunking

#### Example 1: Simple SIP Report

Let’s say we’re interested in our sip-trunking usage for the week of January 23rd. And let’s say we want to see the total calls connected versus calls attempted and the total cost. And we need these numbers broken out by direction and country. We first make a query to the Options endpoint listed above to make sure those requirements are all supported and to see how to query for them.

These are our requirements shown next to how we’d construct our query for them:

Product: sip-trunking
product=sip-trunking
Date(s): January 23rd - 28th 2024
start\_date=2024-01-23T00:00:00-00:00end\_date=2024-01-29T00:00:00-00:00
Metrics: calls connected, calls attempted, cotal cost
metrics=connected,attempted,cost
Broken out by destination country*Note: Since we’re filtering on the direction, we must include it.*
dimensions=country\_code,direction
Outbound only
filter\[direction]=outbound
API Response’s Page Size/Number
page\[number]=1page\[size]=20

##### Request:

```
curl --location --request GET 'https://api.telnyx.com/v2/usage_reports?product=sip-trunking&start_date=2024-01-23T00:00:00-00:00&end_date=2024-01-29T00:00:00-00:00&metrics=connected,attempted,cost&dimensions=direction,country_code&filter[direction]=outbound&page[number]=1&page[size]=20' \
--header 'Authorization: Bearer YOUR_TELNYX_KEY'
```

##### Response:

From the response below, we can see that during the week in question, our account only had traffic to the US (country code = 1). Our connected versus attempted is 883,930 vs 1,245,811 calls respectively. And the total cost for those outbound calls was 1911.624 (*Note: If you had wanted the currency, that is another dimension that can be added in the query with* `dimensions=currency`).

```json theme={null}
{
  "data": [
    {
       "country_code": "1",
       "direction": "outbound",
       "product": "sip-trunking",
       "connected": 883930.0,
       "cost": 1911.6248,
       "attempted": 1245811.0
    }
  ],
  "meta": {
    "page_size": 20,
    "page_number": 1,
    "total_results": 1,
    "total_pages": 1
  }
}
```

#### Example 2: Short Duration Calls

Telnyx enforces automatic surcharges for customer accounts whose short duration calls (greater than 0 and less than or equal to 6 seconds) total 15% or more of their outbound traffic. As someone running SIP traffic, I may want to know if I’m in danger of receiving the surcharge at the end of the month. We have exposed a metric solely for the purpose of this calculation.

Product: sip-trunking
product=sip-trunking
Date(s): January 2024
start\_date=2024-01-01T00:00:00-00:00end\_date=2024-02-01T00:00:00-00:00
Metrics: calls completed
metrics=completed
Broken out by SDC (short duration call: true or false)*Note: Since we’re filtering on the direction, we must include it.*
dimensions=short\_duration\_call,direction
Outbound only
filter\[direction]=outbound
API Response’s Page Size/Number
page\[number]=1page\[size]=20

##### Request:

```
curl --location -g --request GET 'https://api.telnyx.com/v2/usage_reports?product=sip-trunking&start_date=2024-01-01T00:00:00-00:00&end_date=2024-02-01T00:00:00-00:00&metrics=completed&dimensions=direction,short_duration_call&filter[direction]=outbound&page[number]=1&page[size]=20' \
--header 'Authorization: Bearer YOUR_TELNYX_KEY'
```

##### Response:

From the response below, we can determine the percentage of our traffic that is currently considered short duration: `414515 / (414515 + 522094) = 44%`. If we wanted to take this a step further, we could see which connections are the biggest offenders by adding “connection\_id” to the dimensions list.

```json theme={null}
{
  "data": [
    {
       "short_duration_call": "false",
       "direction": "outbound",
       "product": "sip-trunking",
       "completed": 522094.0
    },
    {
       "short_duration_call": "true",
       "direction": "outbound",
       "product": "sip-trunking",
       "completed": 414515.0
    }
  ]
  ,
  "meta": {
    "page_size": 20,
    "page_number": 1,
    "total_results": 2,
    "total_pages": 1
  }
}
```

### Messaging

#### Example 1: Simple Messaging Report

In this example, we’ll put together a simple request to view our Messaging usage for a single day.

Product: messaging
product=messaging
Date(s): Today
date\_range=today
Metrics: total cost, total messages sent, total message parts
metrics=cost,count,parts
Broken out by Carrier*Note: Since we’re filtering on the direction, we must include it.*
dimensions=short\_duration\_call,direction
Outbound only
filter\[direction]=outbound
API Response’s Page Size/Number
page\[number]=1page\[size]=20

##### Request:

```
curl --location -g --request GET 'https://api.telnyx.com/v2/usage_reports?product=messaging&dimensions=direction,normalized_carrier&metrics=cost,parts,count&date_range=today&filter[direction]=outbound&page[number]=1&page[size]=20' \
--header 'Authorization: Bearer YOUR_TELNYX_KEY'
```

##### Response (abbreviated):

```json theme={null}
{
  "data": [
    ...
    {
      "normalized_carrier": "AT&T",
      "direction": "outbound",
      "product": "messaging",
      "cost": 132.4653,
      "parts": 33952.0,
      "count": 18088
    },
    {
      "normalized_carrier": "Verizon Wireless",
      "direction": "outbound",
      "product": "messaging",
      "cost": 205.2036,
      "parts": 48924.0,
      "count": 25171
    }
    ...
  ],
  "meta": {
    "page_size": 20,
    "page_number": 1,
    "total_results": 27,
    "total_pages": 2
  }
}
```

#### Example 2: Alphanumeric by MNC/MCC

This example is a little more complex, and lays out a monthly Messaging report of our Alphanumeric traffic per country, broken out by MCC (Mobile Country Code) and MNC (Mobile Network Code).

Product: messaging
product=messaging
Date(s): January 2024
start\_date=2024-01-01T00:00:00-00:00end\_date=2024-02-01T00:00:00-00:00
Metrics: total cost, total message parts
metrics=cost,parts
Dimensions: mcc, mnc, destination country, status\_v2
dimensions=direction,mcc,mnc,country\_iso,product\_name,status\_v2
Filters: alphanumeric, outbound, billable statuses only
filter\[product\_name]=alphanumeric\_idfilter\[direction]=outboundfilter\[status\_v2]=deliveredfilter\[status\_v2]=delivery\_failedfilter\[status\_v2]=delivery\_unconfirmed

##### Request:

```
curl --location -g --request GET 'https://api.telnyx.com/v2/usage_reports?start_date=2024-01-01T00:00:00-00:00&end_date=2024-02-01T00:00:00-00:00&product=messaging&metrics=parts,cost&dimensions=direction,mcc,mnc,country_iso,product_name,status_v2&filter[product_name]=alphanumeric_id&filter[direction]=outbound&filter[status_v2]=delivered&filter[status_v2]=delivery_failed&filter[status_v2]=delivery_unconfirmed' \
--header 'Authorization: Bearer YOUR_TELNYX_KEY'
```

##### Response (abbreviated):

```json theme={null}
{
  "data": [
    ...
    {
      "status_v2": "delivered",
      "mnc": "01",
      "mcc": "270",
      "product_name": "alphanumeric_id",
      "country_iso": "LU",
      "direction": "outbound",
      "product": "messaging",
      "cost": 9.519,
      "parts": 167.0
    },
    {
      "status_v2": "delivered",
      "mnc": "01",
      "mcc": "272",
      "product_name": "alphanumeric_id",
      "country_iso": "IE",
      "direction": "outbound",
      "product": "messaging",
      "cost": 659.2542,
      "parts": 18623.0
    },
    ...
  ],
  "meta": {
    "page_size": 20,
    "page_number": 1,
    "total_results": 100,
    "total_pages": 5
  }
}
```

***

## Session analysis

### Session Analysis

> Source: [https://developers.telnyx.com/docs/reporting/session-analysis.md](https://developers.telnyx.com/docs/reporting/session-analysis.md)

# Session Analysis API Usage Guide

Understand the full cost and event tree for any Telnyx AI or voice session — from a single inference call to complex multi-product conversations.

***

## What is Session Analysis?

Session Analysis gives you a complete view of costs and events for any usage session on the Telnyx platform:

* **Full event tree** — parent events, child events, and their relationships
* **Rollup costs** — per-event costs plus cumulative totals across the session
* **Product linkages** — how different Telnyx products interacted in a single session

This is especially valuable for AI-powered sessions, where a single call can involve multiple Telnyx products — AI Voice Assistant, inference, speech-to-text, text-to-speech, call control, SIP trunking, and more — all layered into one conversation.

### When to Use It

| Use Case                      | Why Session Analysis Helps                                                                                         |
| :---------------------------- | :----------------------------------------------------------------------------------------------------------------- |
| **AI session cost breakdown** | See the full cost tree for an AI assistant call, broken down by inference turns, STT/TTS, and infrastructure costs |
| **Troubleshooting**           | Trace the complete event chain to debug unexpected call flow or billing issues                                     |
| **Usage auditing**            | Verify which products and services were consumed during a session                                                  |
| **Cost optimization**         | Identify which components of an AI session drive the most cost and optimize accordingly                            |

***

## Core Concepts

### Record Types

A **record type** identifies the category of usage event for a Telnyx product. Each record type maps to a specific product and has defined relationships to other record types.

Example: `ai-voice-assistant` is the record type for AI Voice Assistant sessions, which have `inference` events as children.

### Sessions

A **session** is a tree of related usage events. The **root event** is the primary event you're analyzing. **Child events** are related usage that occurred as part of that session.

**Example:** An AI Voice Assistant call involves a `call-session` root with a `call-control` child, which in turn has an `ai-voice-assistant` child with `inference` events underneath — each representing one LLM turn in the conversation.

### Relationships

Events are connected via **relationships**:

| Relationship | Direction      | Example                                                                   |
| :----------- | :------------- | :------------------------------------------------------------------------ |
| `child_of`   | Parent → Child | An `ai-voice-assistant` event has `inference` children (one per LLM turn) |
| `parent_of`  | Child → Parent | An `inference` event has a parent `ai-voice-assistant` session            |

Relationships are defined via **field mappings** — the child's `local_field` matches the parent's `parent_field`. For example, `inference` events link to their `ai-voice-assistant` parent via the `conversation_id` field.

### Cost Rollup

Each event node includes:

* **`event_cost`** — Cost of this individual event
* **`cumulative_cost`** — This event's cost plus all descendant costs

The root event's `cumulative_cost` equals the total session cost. For AI sessions, this means the `call-session` cumulative cost includes everything — the AI assistant, each inference turn, STT, TTS, call control, and SIP trunking — rolled up into one number.

***

## Endpoints

### 1. List All Record Types

```
GET /v2/session_analysis/metadata
```

Returns all available record types, their relationships, and query parameter options.

**Response includes:**

* `record_types[]` — Array of all record types with their parent/child relationships
* `query_parameters` — Valid parameters for session analysis queries
* `meta` — Total count and last updated timestamp

**Example:**

```shell theme={null}
curl "https://api.telnyx.com/v2/session_analysis/metadata" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### 2. Get Record Type Details

```
GET /v2/session_analysis/metadata/{record_type}
```

Returns metadata for a specific record type with additional details:

* Valid child and parent relationships
* Example query URLs
* Recommended max depth for traversal

**Example:**

```shell theme={null}
curl "https://api.telnyx.com/v2/session_analysis/metadata/ai-voice-assistant" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### 3. Get Session Analysis

```
GET /v2/session_analysis/{record_type}/{event_id}
```

Retrieves the full session analysis tree for a specific event.

**Path Parameters:**

| Parameter     | Type   | Description                                                                              |
| :------------ | :----- | :--------------------------------------------------------------------------------------- |
| `record_type` | string | The record type identifier (see [Record Types Reference](#record-types-reference) below) |
| `event_id`    | UUID   | The event's unique identifier                                                            |

You can find event IDs in the individual webhooks or detail records for the applicable event.

**Which record type should I use?** If you're analyzing a call made with your AI assistant, start with `call-session`. This gives you the full picture — AI assistant sessions, inference events, call control, SIP trunking, and all other products in one tree. Use the metadata endpoint to explore other starting points for different products.

**Query Parameters:**

| Parameter          | Type     | Default  | Description                                                           |
| :----------------- | :------- | :------- | :-------------------------------------------------------------------- |
| `include_children` | boolean  | `true`   | Include child events in the response                                  |
| `max_depth`        | integer  | `2`      | Maximum traversal depth (1-5)                                         |
| `expand`           | string   | `record` | Only `record` (include full record data) or `none` (omit record data) |
| `date_time`        | ISO 8601 | —        | Timestamp to narrow index selection (improves performance)            |

**Example:**

```shell theme={null}
curl "https://api.telnyx.com/v2/session_analysis/call-session/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d?include_children=true&max_depth=3&date_time=2026-03-17" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

***

## Response Structure

### Top-Level Fields

```json theme={null}
{
 "session_id": "4c9d22b0-1e4b-11f1-83a0-02420aef51a1",
 "cost": {
 "total": "0.009800",
 "currency": "USD"
 },
 "root": { /* EventNode */ },
 "meta": {
 "event_count": 3,
 "products": ["ai-voice-assistant", "inference", "callcontrol-cdrs"]
 }
}
```

| Field              | Description                             |
| :----------------- | :-------------------------------------- |
| `session_id`       | Identifier for the analyzed session     |
| `cost.total`       | Total session cost (sum of all events)  |
| `cost.currency`    | ISO 4217 currency code                  |
| `root`             | Root event node (tree structure)        |
| `meta.event_count` | Total events in the tree                |
| `meta.products`    | Unique products involved in the session |

### Event Node Structure

Each event in the tree follows this structure:

```json theme={null}
{
 "id": "4c9d22b0-1e4b-11f1-83a0-02420aef51a1",
 "product": "callcontrol-cdrs",
 "event_name": "callcontrol-cdrs",
 "relationship": null,
 "cost": {
 "event_cost": "0.000000",
 "cumulative_cost": "0.009800",
 "currency": "USD"
 },
 "links": {
 "self": "/v2/session_analysis/call-control/4c9d22b0-...",
 "records": "/v2/detail_records?record_type=call-control&id=4c9d22b0-..."
 },
 "record": { /* Full detail record */ },
 "children": [ /* Array of child EventNodes */ ]
}
```

| Field                  | Description                                          |
| :--------------------- | :--------------------------------------------------- |
| `id`                   | Event identifier                                     |
| `product`              | Internal product identifier                          |
| `event_name`           | Event type name                                      |
| `relationship`         | How this event relates to its parent (null for root) |
| `cost.event_cost`      | Cost of this individual event                        |
| `cost.cumulative_cost` | This event + all descendants                         |
| `links.self`           | Link to this analysis node                           |
| `links.records`        | Link to underlying detail records                    |
| `record`               | Full detail record data (varies by record type)      |
| `children`             | Child event nodes                                    |

### Relationship Object

For child events, the `relationship` field explains the connection:

```json theme={null}
{
 "type": "child_of",
 "via": {
 "local_field": "conversation_id",
 "parent_field": "conversation_id"
 },
 "parent_id": "4c9063e0-1e4b-11f1-b789-02420aef51a1"
}
```

| Field              | Description                                   |
| :----------------- | :-------------------------------------------- |
| `type`             | Relationship type (`child_of` or `parent_of`) |
| `via.local_field`  | Field on this record that links to parent     |
| `via.parent_field` | Field on the parent record that's matched     |
| `parent_id`        | Identifier of the parent event                |

Note: The `via` fields vary by relationship. AI-related linkages often use `conversation_id`, while voice/telephony relationships typically use `telnyx_session_id` or `call_session_id`.

***

## Example: AI Voice Assistant Session

A customer makes an inbound call to an AI Voice Assistant using the Telnyx Web Dialer. The assistant handles a multi-turn conversation over \~152 seconds.

**Query:**

```shell theme={null}
curl "https://api.telnyx.com/v2/session_analysis/call-session/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d?max_depth=5&include_children=true&date_time=2026-03-17" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

**Session tree:**

```
call-session (SIP Trunking) event: $0.0000 cumulative: $0.2128
├── recording event: $0.0051 cumulative: $0.0051
├── webrtc event: $0.0052 cumulative: $0.0052
├── sip-trunking event: $0.0052 cumulative: $0.0052
└── call-control event: $0.0052 cumulative: $0.1973
    └── ai-voice-assistant event: $0.1800 cumulative: $0.1921
        ├── inference event: $0.0010
        ├── inference event: $0.0015
        ├── inference event: $0.0029
        ├── inference event: $0.0033
        └── inference event: $0.0034
```

**Summary:**

| Field              | Value                                                                                          |
| :----------------- | :--------------------------------------------------------------------------------------------- |
| Total session cost | \$0.2128                                                                                       |
| Event count        | 11                                                                                             |
| Duration           | \~152 seconds                                                                                  |
| Products involved  | siptrunking-cdrs, recording-cdrs, webrtc-cdrs, callcontrol-cdrs, ai-voice-assistant, inference |

**Key observations:**

* The **call-session** root has \$0.00 event cost — it's a container for the session, not a billable event itself.
* **ai-voice-assistant** is the dominant cost at $0.18 (billed at $0.06/min for 3 billed minutes). Its cumulative cost of \$0.1921 includes 5 inference events underneath.
* Each **inference** event represents a single LLM call during the conversation — one per assistant turn. The cost per turn varies based on the model and token count.
* **call-control** has a $0.0052 event cost but a $0.1973 cumulative cost — the difference is the ai-voice-assistant subtree rolling up underneath it.
* **recording**, **webrtc**, and **sip-trunking** are leaf nodes with no children, so their event cost equals their cumulative cost.

### Understanding the AI Cost Structure

In an AI-powered call, costs come from multiple layers:

| Layer             | Record Type                                     | What You're Billed For                         |
| :---------------- | :---------------------------------------------- | :--------------------------------------------- |
| **AI Assistant**  | `ai-voice-assistant`                            | Time-based (per minute of assistant usage)     |
| **LLM Inference** | `inference`                                     | Per-turn (each LLM call is a separate event)   |
| **Call Control**  | `call-control`                                  | Time-based (per minute of call control usage)  |
| **Transport**     | `sip-trunking`, `webrtc`                        | Time-based (per minute for the voice leg)      |
| **Add-ons**       | `recording`, `speech-to-text`, `text-to-speech` | Per-use or per-minute depending on the product |

Session Analysis rolls all of these into one tree, so you can see exactly where cost accumulates — whether it's the AI assistant minute rate, the number of inference turns, or the underlying voice transport.

***

## Common Use Cases

### Debugging High-Cost AI Sessions

1. Query the session with `max_depth=5` to get the full tree
2. Look at `meta.products` to see which products were involved
3. Compare `event_cost` across children — if `ai-voice-assistant` is the driver, check how many inference turns occurred underneath
4. Check `record` fields for rate information (`rate`, `rate_measured_in`) and duration

### Finding Related Events

1. Start from any event in the tree
2. Use `relationship.via` to understand the field linkage
3. Query the parent or children directly using their `id`

### Exporting for Analysis

1. Use `expand=none` to get just the tree structure without full records
2. Flatten the tree programmatically for spreadsheet import
3. Or keep full records and parse specific fields (e.g., `rate`, `duration_sec`)

***

## Best Practices

### Performance

* **Provide `date_time`** when you know it — this narrows the index search and improves response time
* **Use appropriate `max_depth`** — start with `2`, increase only if needed. AI sessions with inference events typically need `max_depth=4` or `5` to reach the leaf level.
* **Use `expand=none`** if you only need cost rollups, not full records

### Querying

* **Start from the root event** — the most complete picture comes from the top-level event
* **Check metadata first** — `/metadata/{record_type}` shows expected children and recommended depth
* **Use `links.records`** to get the underlying detail records for deeper analysis

### Error Handling

| Status Code | Meaning            | Action                                           |
| :---------- | :----------------- | :----------------------------------------------- |
| 400         | Invalid parameters | Check `record_type` spelling, `event_id` format  |
| 403         | Forbidden          | Verify API key has access to this user's data    |
| 404         | Event not found    | Event may not exist, or `date_time` is incorrect |
| 500         | Internal error     | Retry with exponential backoff                   |

***

## Record Types Reference

### AI & Voice Intelligence

| Record Type                | Product                     | Description                            | Common Children |
| :------------------------- | :-------------------------- | :------------------------------------- | :-------------- |
| `ai-voice-assistant`       | AI Voice Assistant          | AI assistant sessions                  | `inference`     |
| `inference`                | Inference                   | AI inference events (one per LLM turn) | —               |
| `inference-speech-to-text` | Inference                   | STT-specific inference                 | —               |
| `inference-text-to-speech` | Inference                   | TTS-specific inference                 | —               |
| `summarization`            | Inference                   | Text summarization                     | —               |
| `embedding`                | Inference                   | Vector embeddings                      | —               |
| `speech-to-text`           | Speech-to-Text              | STT transcription records              | —               |
| `text-to-speech`           | Text-to-Speech              | TTS synthesis records                  | —               |
| `amd`                      | Answering Machine Detection | AMD invocations                        | —               |
| `noise-suppression`        | Noise Suppression           | Audio enhancement records              | —               |

### Voice & Telephony

| Record Type    | Product                           | Description                                                        | Common Children                                                                                             |
| :------------- | :-------------------------------- | :----------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------- |
| `call-session` | N/A                               | Root-level record for grouping related voice product usage records | `call-control`, `sip-trunking`, `recording`, `webrtc`, `siprec-client`, `fax-api`, `conference-participant` |
| `call-control` | Call Control (Programmable Voice) | Voice API call records                                             | `ai-voice-assistant`, `amd`, `media-streaming`, `speech-to-text`, `text-to-speech`, `noise-suppression`     |
| `sip-trunking` | SIP Trunking                      | SIP trunking detail records                                        | —                                                                                                           |
| `webrtc`       | WebRTC                            | WebRTC call records                                                | —                                                                                                           |

### Media & Storage

| Record Type       | Product         | Description             | Common Children |
| :---------------- | :-------------- | :---------------------- | :-------------- |
| `recording`       | Call Recording  | Call recording CDRs     | —               |
| `media_storage`   | Media Storage   | Stored media files      | —               |
| `media-streaming` | Media Streaming | Real-time audio streams | —               |
| `forking`         | Media Forking   | Forked media records    | —               |

### Conferencing

| Record Type              | Product    | Description                    | Common Children          |
| :----------------------- | :--------- | :----------------------------- | :----------------------- |
| `conference`             | Conference | Conference sessions            | `conference-participant` |
| `conference-participant` | Conference | Individual participant records | —                        |

### Messaging

| Record Type | Product   | Description             | Common Children          |
| :---------- | :-------- | :---------------------- | :----------------------- |
| `message`   | Messaging | SMS/MMS message records | `ai-messaging-assistant` |

### Video

| Record Type                      | Product            | Description         | Common Children |
| :------------------------------- | :----------------- | :------------------ | :-------------- |
| `room-session-event`             | Programmable Video | Video room sessions | —               |
| `room-session-participant-event` | Programmable Video | Video participants  | —               |
| `room-session-recording-event`   | Programmable Video | Video recordings    | —               |
| `room-session-composition-event` | Programmable Video | Video compositions  | —               |

### Other Products

| Record Type               | Product         | Description               | Common Children |
| :------------------------ | :-------------- | :------------------------ | :-------------- |
| `verify`                  | Verify (2FA)    | Verification attempts     | —               |
| `fax-api`                 | Fax API         | Fax transmission records  | —               |
| `branded-calling`         | Branded Calling | Caller ID branding        | —               |
| `siprec-client`           | SIPREC          | SIPREC recording sessions | —               |
| `sim_card_usage`          | Wireless        | SIM card data usage       | —               |
| `customer-service-record` | CSR             | Customer service records  | —               |

***

## On-Demand Reports

### On-Demand Reports

> Source: [https://developers.telnyx.com/docs/reporting/on-demand-reports.md](https://developers.telnyx.com/docs/reporting/on-demand-reports.md)

On-Demand Reports lets you query your Telnyx usage data using natural language. Instead of building filters and exporting CSVs, describe the report you want in plain English and the system generates it.

***

## Overview

On-Demand Reports uses AI to translate natural language into structured queries against your [Usage Report](/docs/reporting/usage-reports/index) data. You can request specific chart types, date ranges, groupings, and breakdowns — all from a single text input.

***

## Getting started

1. Log in to the [Mission Control Portal](https://portal.telnyx.com).
2. Navigate to **Reporting** > **[On-Demand Reports](https://portal.telnyx.com/#/reporting/on-demand-reports)**.
3. Type a query describing the report you need and submit it.

<img src="https://mintcdn.com/telnyx/CK2IQbzSNcAAKyBl/img/on-demand-reports-interface.png?fit=max&auto=format&n=CK2IQbzSNcAAKyBl&q=85&s=9d46a27d7c53622e0f622c592cac3f68" alt="On-Demand Reports query interface" width="1194" height="454" data-path="img/on-demand-reports-interface.png" />

***

## Example queries

* "Daily wireless spend for the last 10 days"
* "Number of messages by direction for last week as a pie chart"
* "Weekly total calls last quarter"
* "Average SIP cost for last 2 weeks as line graph"
* "SIP usage for the last month as a table"

***

## What you can do

| Capability                   | Description                                                                |
| ---------------------------- | -------------------------------------------------------------------------- |
| **Natural language queries** | Describe reports in plain English instead of building filters manually     |
| **Chart type selection**     | Request bar charts, pie charts, line graphs, or tabular breakdowns         |
| **Date range control**       | Specify relative ("last 10 days") or absolute ("in February") time periods |
| **Grouping and breakdowns**  | Group data by direction, product, day, week, or other dimensions           |

***

## Current limitations

* Queries run against **v2 Usage Report data** only. Products and dimensions available in Usage Reports are available here.
* **Not a general knowledge assistant** — the system answers questions about your Telnyx usage data, not general questions.
* This is the first release. Coverage and capabilities will expand over time.

***

## API Reference (Account & Billing)

### AutoRechargePreferences

* [List auto recharge preferences](https://developers.telnyx.com/api-reference/autorechargepreferences/list-auto-recharge-preferences.md): Returns the payment auto recharge preferences.
* [Update auto recharge preferences](https://developers.telnyx.com/api-reference/autorechargepreferences/update-auto-recharge-preferences.md): Update payment auto recharge preferences.

### Notifications

* [List notification channels](https://developers.telnyx.com/api-reference/notifications/list-notification-channels.md): List notification channels.
* [Create a notification channel](https://developers.telnyx.com/api-reference/notifications/create-a-notification-channel.md): Create a notification channel.
* [Get a notification channel](https://developers.telnyx.com/api-reference/notifications/get-a-notification-channel.md): Get a notification channel.
* [Update a notification channel](https://developers.telnyx.com/api-reference/notifications/update-a-notification-channel.md): Update a notification channel.
* [Delete a notification channel](https://developers.telnyx.com/api-reference/notifications/delete-a-notification-channel.md): Delete a notification channel.
* [List all Notifications Events Conditions](https://developers.telnyx.com/api-reference/notifications/list-all-notifications-events-conditions.md): Returns a list of your notifications events conditions.
* [List all Notifications Events](https://developers.telnyx.com/api-reference/notifications/list-all-notifications-events.md): Returns a list of your notifications events.
* [List all Notifications Profiles](https://developers.telnyx.com/api-reference/notifications/list-all-notifications-profiles.md): Returns a list of your notifications profiles.
* [Create a notification profile](https://developers.telnyx.com/api-reference/notifications/create-a-notification-profile.md): Create a notification profile.
* [Get a notification profile](https://developers.telnyx.com/api-reference/notifications/get-a-notification-profile.md): Get a notification profile.
* [Update a notification profile](https://developers.telnyx.com/api-reference/notifications/update-a-notification-profile.md): Update a notification profile.
* [Delete a notification profile](https://developers.telnyx.com/api-reference/notifications/delete-a-notification-profile.md): Delete a notification profile.
* [List notification settings](https://developers.telnyx.com/api-reference/notifications/list-notification-settings.md): List notification settings.
* [Add a Notification Setting](https://developers.telnyx.com/api-reference/notifications/add-a-notification-setting.md): Add a notification setting.
* [Get a notification setting](https://developers.telnyx.com/api-reference/notifications/get-a-notification-setting.md): Get a notification setting.
* [Delete a notification setting](https://developers.telnyx.com/api-reference/notifications/delete-a-notification-setting.md): Delete a notification setting.

### Addresses

* [List all addresses](https://developers.telnyx.com/api-reference/addresses/list-all-addresses.md): Returns a list of your addresses.
* [Creates an address](https://developers.telnyx.com/api-reference/addresses/creates-an-address.md): Creates an address.
* [Retrieve an address](https://developers.telnyx.com/api-reference/addresses/retrieve-an-address.md): Retrieves the details of an existing address.
* [Deletes an address](https://developers.telnyx.com/api-reference/addresses/deletes-an-address.md): Deletes an existing address.
* [Accepts this address suggestion as a new emergency address for Operator Connect and finishes the uploads of the numbers associated with it to Microsoft.](https://developers.telnyx.com/api-reference/addresses/accepts-this-address-suggestion-as-a-new-emergency-address-for-operator-connect-and-finishes-the-uploads-of-the-numbers-associated-with-it-to-microsoft.md)
* [Validate an address](https://developers.telnyx.com/api-reference/addresses/validate-an-address.md): Validates an address for emergency services.

### Billing

* [Get user balance details](https://developers.telnyx.com/api-reference/billing/get-user-balance-details.md)

### Authentication Providers

* [List all SSO authentication providers](https://developers.telnyx.com/api-reference/authentication-providers/list-all-sso-authentication-providers.md): Returns a list of your SSO authentication providers.
* [Creates an authentication provider](https://developers.telnyx.com/api-reference/authentication-providers/creates-an-authentication-provider.md): Creates an authentication provider.
* [Retrieve an authentication provider](https://developers.telnyx.com/api-reference/authentication-providers/retrieve-an-authentication-provider.md): Retrieves the details of an existing authentication provider.
* [Update an authentication provider](https://developers.telnyx.com/api-reference/authentication-providers/update-an-authentication-provider.md): Updates settings of an existing authentication provider.
* [Deletes an authentication provider](https://developers.telnyx.com/api-reference/authentication-providers/deletes-an-authentication-provider.md): Deletes an existing authentication provider.

### IP Addresses

* [List all Access IP Addresses](https://developers.telnyx.com/api-reference/ip-addresses/list-all-access-ip-addresses.md)
* [Create new Access IP Address](https://developers.telnyx.com/api-reference/ip-addresses/create-new-access-ip-address.md)
* [Retrieve an access IP address](https://developers.telnyx.com/api-reference/ip-addresses/retrieve-an-access-ip-address.md)
* [Delete access IP address](https://developers.telnyx.com/api-reference/ip-addresses/delete-access-ip-address.md)

### IP Ranges

* [List all Access IP Ranges](https://developers.telnyx.com/api-reference/ip-ranges/list-all-access-ip-ranges.md)
* [Create new Access IP Range](https://developers.telnyx.com/api-reference/ip-ranges/create-new-access-ip-range.md)
* [Delete access IP ranges](https://developers.telnyx.com/api-reference/ip-ranges/delete-access-ip-ranges.md)

### Managed Accounts

* [Lists accounts managed by the current user.](https://developers.telnyx.com/api-reference/managed-accounts/lists-accounts-managed-by-the-current-user.md): Lists the accounts managed by the current user. Users need to be explictly approved by Telnyx in order to become manager accounts.
* [Create a new managed account.](https://developers.telnyx.com/api-reference/managed-accounts/create-a-new-managed-account.md): Create a new managed account owned by the authenticated user. You need to be explictly approved by Telnyx in order to become a manager account.
* [Retrieve a managed account](https://developers.telnyx.com/api-reference/managed-accounts/retrieve-a-managed-account.md): Retrieves the details of a single managed account.
* [Update a managed account](https://developers.telnyx.com/api-reference/managed-accounts/update-a-managed-account.md): Update a single managed account.
* [Disables a managed account](https://developers.telnyx.com/api-reference/managed-accounts/disables-a-managed-account.md): Disables a managed account, forbidding it to use Telnyx services, including sending or receiving phone calls and SMS messages. Ongoing phone calls will not be…
* [Enables a managed account](https://developers.telnyx.com/api-reference/managed-accounts/enables-a-managed-account.md): Enables a managed account and its sub-users to use Telnyx services.
* [Update the amount of allocatable global outbound channels allocated to a specific managed account.](https://developers.telnyx.com/api-reference/managed-accounts/update-the-amount-of-allocatable-global-outbound-channels-allocated-to-a-specific-managed-account.md): Update the amount of allocatable global outbound channels allocated to a specific managed account.
* [Display information about allocatable global outbound channels for the current user.](https://developers.telnyx.com/api-reference/managed-accounts/display-information-about-allocatable-global-outbound-channels-for-the-current-user.md): Display information about allocatable global outbound channels for the current user. Only usable by account managers.

### Organization Users

* [List organization users](https://developers.telnyx.com/api-reference/organization-users/list-organization-users.md): Returns a list of the users in your organization.
* [Get organization user](https://developers.telnyx.com/api-reference/organization-users/get-organization-user.md): Returns a user in your organization.
* [Delete organization user](https://developers.telnyx.com/api-reference/organization-users/delete-organization-user.md): Deletes a user in your organization.
* [Get organization users groups report](https://developers.telnyx.com/api-reference/organization-users/get-organization-users-groups-report.md): Returns a report of all users in your organization with their group memberships. This endpoint returns all users without pagination and always includes group i…

### Billing Groups

* [List all billing groups](https://developers.telnyx.com/api-reference/billing-groups/list-all-billing-groups.md)
* [Create a billing group](https://developers.telnyx.com/api-reference/billing-groups/create-a-billing-group.md)
* [Get a billing group](https://developers.telnyx.com/api-reference/billing-groups/get-a-billing-group.md)
* [Update a billing group](https://developers.telnyx.com/api-reference/billing-groups/update-a-billing-group.md)
* [Delete a billing group](https://developers.telnyx.com/api-reference/billing-groups/delete-a-billing-group.md)

### Detail Records

* [Search detail records](https://developers.telnyx.com/api-reference/detail-records/search-detail-records.md): Search for any detail record across the Telnyx Platform

### MDR Detailed Reports

* [Get all MDR detailed report requests](https://developers.telnyx.com/api-reference/mdr-detailed-reports/get-all-mdr-detailed-report-requests.md): Retrieves all MDR detailed report requests for the authenticated user
* [Create a new MDR detailed report request](https://developers.telnyx.com/api-reference/mdr-detailed-reports/create-a-new-mdr-detailed-report-request.md): Creates a new MDR detailed report request with the specified filters
* [Get a specific MDR detailed report request](https://developers.telnyx.com/api-reference/mdr-detailed-reports/get-a-specific-mdr-detailed-report-request.md): Retrieves a specific MDR detailed report request by ID
* [Delete a MDR detailed report request](https://developers.telnyx.com/api-reference/mdr-detailed-reports/delete-a-mdr-detailed-report-request.md): Deletes a specific MDR detailed report request by ID

### CDR Reports

* [Get all CDR report requests](https://developers.telnyx.com/api-reference/cdr-reports/get-all-cdr-report-requests.md): Retrieves all CDR report requests for the authenticated user
* [Create a new CDR report request](https://developers.telnyx.com/api-reference/cdr-reports/create-a-new-cdr-report-request.md): Creates a new CDR report request with the specified filters
* [Get a specific CDR report request](https://developers.telnyx.com/api-reference/cdr-reports/get-a-specific-cdr-report-request.md): Retrieves a specific CDR report request by ID
* [Delete a CDR report request](https://developers.telnyx.com/api-reference/cdr-reports/delete-a-cdr-report-request.md): Deletes a specific CDR report request by ID
* [Get available CDR report fields](https://developers.telnyx.com/api-reference/cdr-reports/get-available-cdr-report-fields.md): Retrieves all available fields that can be used in CDR reports

### MDR Usage Reports

* [List MDR usage reports](https://developers.telnyx.com/api-reference/mdr-usage-reports/list-mdr-usage-reports.md): Fetch all previous requests for MDR usage reports.
* [Create a new legacy usage V2 MDR report request](https://developers.telnyx.com/api-reference/mdr-usage-reports/create-a-new-legacy-usage-v2-mdr-report-request.md): Creates a new legacy usage V2 MDR report request with the specified filters
* [Get an MDR usage report](https://developers.telnyx.com/api-reference/mdr-usage-reports/get-an-mdr-usage-report.md): Fetch single MDR usage report by id.
* [Delete a V2 legacy usage MDR report request](https://developers.telnyx.com/api-reference/mdr-usage-reports/delete-a-v2-legacy-usage-mdr-report-request.md): Deletes a specific V2 legacy usage MDR report request by ID
* [Fetch all Messaging usage reports](https://developers.telnyx.com/api-reference/mdr-usage-reports/fetch-all-messaging-usage-reports.md): Fetch all messaging usage reports. Usage reports are aggregated messaging data for specified time period and breakdown
* [Create MDR Usage Report](https://developers.telnyx.com/api-reference/mdr-usage-reports/create-mdr-usage-report.md): Submit request for new new messaging usage report. This endpoint will pull and aggregate messaging data in specified time period.
* [Retrieve messaging report](https://developers.telnyx.com/api-reference/mdr-usage-reports/retrieve-messaging-report.md): Fetch a single messaging usage report by id
* [Delete MDR Usage Report](https://developers.telnyx.com/api-reference/mdr-usage-reports/delete-mdr-usage-report.md): Delete messaging usage report by id
* [Generate and fetch MDR Usage Report](https://developers.telnyx.com/api-reference/mdr-usage-reports/generate-and-fetch-mdr-usage-report.md): Generate and fetch messaging usage report synchronously. This endpoint will both generate and fetch the messaging report over a specified time period. No polli…

### Telco Data Usage Reports

* [List telco data usage reports](https://developers.telnyx.com/api-reference/telco-data-usage-reports/list-telco-data-usage-reports.md): Retrieve a paginated list of telco data usage reports
* [Submit telco data usage report](https://developers.telnyx.com/api-reference/telco-data-usage-reports/submit-telco-data-usage-report.md): Submit a new telco data usage report
* [Get telco data usage report by ID](https://developers.telnyx.com/api-reference/telco-data-usage-reports/get-telco-data-usage-report-by-id.md): Retrieve a specific telco data usage report by its ID
* [Delete telco data usage report](https://developers.telnyx.com/api-reference/telco-data-usage-reports/delete-telco-data-usage-report.md): Delete a specific telco data usage report by its ID

### Speech to text Usage Reports

* [Get speech to text usage report](https://developers.telnyx.com/api-reference/speech-to-text-usage-reports/get-speech-to-text-usage-report.md): Generate and fetch speech to text usage report synchronously. This endpoint will both generate and fetch the speech to text report over a specified time period.

### CDR Usage Reports

* [List CDR usage reports](https://developers.telnyx.com/api-reference/cdr-usage-reports/list-cdr-usage-reports.md): Fetch all previous requests for cdr usage reports.
* [Create a new legacy usage V2 CDR report request](https://developers.telnyx.com/api-reference/cdr-usage-reports/create-a-new-legacy-usage-v2-cdr-report-request.md): Creates a new legacy usage V2 CDR report request with the specified filters
* [Get a CDR usage report](https://developers.telnyx.com/api-reference/cdr-usage-reports/get-a-cdr-usage-report.md): Fetch single cdr usage report by id.
* [Delete a V2 legacy usage CDR report request](https://developers.telnyx.com/api-reference/cdr-usage-reports/delete-a-v2-legacy-usage-cdr-report-request.md): Deletes a specific V2 legacy usage CDR report request by ID
* [Generates and fetches CDR Usage Reports](https://developers.telnyx.com/api-reference/cdr-usage-reports/generates-and-fetches-cdr-usage-reports.md): Generate and fetch voice usage report synchronously. This endpoint will both generate and fetch the voice report over a specified time period. No polling is ne…

### Usage Reports (BETA)

* [Get Telnyx product usage data (BETA)](https://developers.telnyx.com/api-reference/usage-reports-beta/get-telnyx-product-usage-data-beta.md): Get Telnyx usage data by product, broken out by the specified dimensions
* [Get Usage Reports query options (BETA)](https://developers.telnyx.com/api-reference/usage-reports-beta/get-usage-reports-query-options-beta.md): Get the Usage Reports options for querying usage, including the products available and their respective metrics and dimensions

### Speech to Text Batch Reports

* [Get all Speech to Text batch report requests](https://developers.telnyx.com/api-reference/speech-to-text-batch-reports/get-all-speech-to-text-batch-report-requests.md): Retrieves all Speech to Text batch report requests for the authenticated user
* [Create a new Speech to Text batch report request](https://developers.telnyx.com/api-reference/speech-to-text-batch-reports/create-a-new-speech-to-text-batch-report-request.md): Creates a new Speech to Text batch report request with the specified filters
* [Get a specific Speech to Text batch report request](https://developers.telnyx.com/api-reference/speech-to-text-batch-reports/get-a-specific-speech-to-text-batch-report-request.md): Retrieves a specific Speech to Text batch report request by ID
* [Delete a Speech to Text batch report request](https://developers.telnyx.com/api-reference/speech-to-text-batch-reports/delete-a-speech-to-text-batch-report-request.md): Deletes a specific Speech to Text batch report request by ID

### MDR Detail Reports

* [Fetch all Mdr records](https://developers.telnyx.com/api-reference/mdr-detail-reports/fetch-all-mdr-records.md): Fetch all Mdr records

### WDR Detail Reports

* [Fetches all Wdr records](https://developers.telnyx.com/api-reference/wdr-detail-reports/fetches-all-wdr-records.md): Fetch all Wdr records

### Session Analysis

* [Get metadata overview](https://developers.telnyx.com/api-reference/session-analysis/get-metadata-overview.md): Returns all available record types and supported query parameters for session analysis.
* [Get record type metadata](https://developers.telnyx.com/api-reference/session-analysis/get-record-type-metadata.md): Returns detailed metadata for a specific record type, including relationships and examples.
* [Get session analysis](https://developers.telnyx.com/api-reference/session-analysis/get-session-analysis.md): Retrieves a full session analysis tree for a given event, including costs, child events, and product linkages.

### Webhooks

* [List webhook deliveries](https://developers.telnyx.com/api-reference/webhooks/list-webhook-deliveries.md): Lists webhook\_deliveries for the authenticated user
* [Find webhook\_delivery details by ID](https://developers.telnyx.com/api-reference/webhooks/find-webhook_delivery-details-by-id.md): Provides webhook\_delivery debug data, such as timestamps, delivery status and attempts.

### Audit Logs

* [List Audit Logs](https://developers.telnyx.com/api-reference/audit-logs/list-audit-logs.md): Retrieve a list of audit log entries. Audit logs are a best-effort, eventually consistent record of significant account-related changes.

### User Tags

* [List User Tags](https://developers.telnyx.com/api-reference/user-tags/list-user-tags.md): List all user tags.

### UserAddresses

* [List all user addresses](https://developers.telnyx.com/api-reference/useraddresses/list-all-user-addresses.md): Returns a list of your user addresses.
* [Creates a user address](https://developers.telnyx.com/api-reference/useraddresses/creates-a-user-address.md): Creates a user address.
* [Retrieve a user address](https://developers.telnyx.com/api-reference/useraddresses/retrieve-a-user-address.md): Retrieves the details of an existing user address.

### Integration Secrets

* [List integration secrets](https://developers.telnyx.com/api-reference/integration-secrets/list-integration-secrets.md): Retrieve a list of all integration secrets configured by the user.
* [Create a secret](https://developers.telnyx.com/api-reference/integration-secrets/create-a-secret.md): Create a new secret with an associated identifier that can be used to securely integrate with other services.
* [Delete an integration secret](https://developers.telnyx.com/api-reference/integration-secrets/delete-an-integration-secret.md): Delete an integration secret given its ID.