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). Root index: https://developers.telnyx.com/llms.txt · Lightweight index for this subsection: 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

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. 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:

{
    "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 countryNote: 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).

{
  "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.

{
  "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 CarrierNote: 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):

{
  "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):

{
  "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

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:

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:

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 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:

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

{
 "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:

{
 "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:

{
 "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:

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

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

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

Exporting for Analysis

Use expand=none to get just the tree structure without full records
Flatten the tree programmatically for spreadsheet import
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

Source: 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 data. You can request specific chart types, date ranges, groupings, and breakdowns — all from a single text input.

Getting started

Log in to the Mission Control Portal.
Navigate to Reporting > On-Demand Reports.
Type a query describing the report you need and submit it.

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: Returns the payment auto recharge preferences.
Update auto recharge preferences: Update payment auto recharge preferences.

Notifications

List notification channels: List notification channels.
Create a notification channel: Create a notification channel.
Get a notification channel: Get a notification channel.
Update a notification channel: Update a notification channel.
Delete a notification channel: Delete a notification channel.
List all Notifications Events Conditions: Returns a list of your notifications events conditions.
List all Notifications Events: Returns a list of your notifications events.
List all Notifications Profiles: Returns a list of your notifications profiles.
Create a notification profile: Create a notification profile.
Get a notification profile: Get a notification profile.
Update a notification profile: Update a notification profile.
Delete a notification profile: Delete a notification profile.
List notification settings: List notification settings.
Add a Notification Setting: Add a notification setting.
Get a notification setting: Get a notification setting.
Delete a notification setting: Delete a notification setting.

Addresses

List all addresses: Returns a list of your addresses.
Creates an address: Creates an address.
Retrieve an address: Retrieves the details of an existing address.
Deletes an address: 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.
Validate an address: Validates an address for emergency services.

Billing

Get user balance details

Authentication Providers

List all SSO authentication providers: Returns a list of your SSO authentication providers.
Creates an authentication provider: Creates an authentication provider.
Retrieve an authentication provider: Retrieves the details of an existing authentication provider.
Update an authentication provider: Updates settings of an existing authentication provider.
Deletes an authentication provider: Deletes an existing authentication provider.

IP Addresses

IP Ranges

Managed Accounts

Lists accounts managed by the current user.: 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.: 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: Retrieves the details of a single managed account.
Update a managed account: Update a single managed account.
Disables a managed account: 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: 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.: 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.: Display information about allocatable global outbound channels for the current user. Only usable by account managers.

Organization Users

List organization users: Returns a list of the users in your organization.
Get organization user: Returns a user in your organization.
Delete organization user: Deletes a user in your organization.
Get organization users groups report: 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

Detail Records

Search detail records: Search for any detail record across the Telnyx Platform

MDR Detailed Reports

Get all MDR detailed report requests: Retrieves all MDR detailed report requests for the authenticated user
Create a new MDR detailed report request: Creates a new MDR detailed report request with the specified filters
Get a specific MDR detailed report request: Retrieves a specific MDR detailed report request by ID
Delete a MDR detailed report request: Deletes a specific MDR detailed report request by ID

CDR Reports

Get all CDR report requests: Retrieves all CDR report requests for the authenticated user
Create a new CDR report request: Creates a new CDR report request with the specified filters
Get a specific CDR report request: Retrieves a specific CDR report request by ID
Delete a CDR report request: Deletes a specific CDR report request by ID
Get available CDR report fields: Retrieves all available fields that can be used in CDR reports

MDR Usage Reports

List MDR usage reports: Fetch all previous requests for MDR usage reports.
Create a new legacy usage V2 MDR report request: Creates a new legacy usage V2 MDR report request with the specified filters
Get an MDR usage report: Fetch single MDR usage report by id.
Delete a V2 legacy usage MDR report request: Deletes a specific V2 legacy usage MDR report request by ID
Fetch all Messaging usage reports: Fetch all messaging usage reports. Usage reports are aggregated messaging data for specified time period and breakdown
Create MDR Usage Report: Submit request for new new messaging usage report. This endpoint will pull and aggregate messaging data in specified time period.
Retrieve messaging report: Fetch a single messaging usage report by id
Delete MDR Usage Report: Delete messaging usage report by id
Generate and fetch MDR Usage Report: 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: Retrieve a paginated list of telco data usage reports
Submit telco data usage report: Submit a new telco data usage report
Get telco data usage report by ID: Retrieve a specific telco data usage report by its ID
Delete telco data usage report: Delete a specific telco data usage report by its ID

Speech to text Usage Reports

Get speech to text usage report: 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: Fetch all previous requests for cdr usage reports.
Create a new legacy usage V2 CDR report request: Creates a new legacy usage V2 CDR report request with the specified filters
Get a CDR usage report: Fetch single cdr usage report by id.
Delete a V2 legacy usage CDR report request: Deletes a specific V2 legacy usage CDR report request by ID
Generates and fetches CDR Usage Reports: 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): Get Telnyx usage data by product, broken out by the specified dimensions
Get Usage Reports query options (BETA): 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: Retrieves all Speech to Text batch report requests for the authenticated user
Create a new Speech to Text batch report request: Creates a new Speech to Text batch report request with the specified filters
Get a specific Speech to Text batch report request: Retrieves a specific Speech to Text batch report request by ID
Delete a Speech to Text batch report request: Deletes a specific Speech to Text batch report request by ID

MDR Detail Reports

Fetch all Mdr records: Fetch all Mdr records

WDR Detail Reports

Fetches all Wdr records: Fetch all Wdr records

Session Analysis

Get metadata overview: Returns all available record types and supported query parameters for session analysis.
Get record type metadata: Returns detailed metadata for a specific record type, including relationships and examples.
Get session analysis: Retrieves a full session analysis tree for a given event, including costs, child events, and product linkages.

Webhooks

List webhook deliveries: Lists webhook_deliveries for the authenticated user
Find webhook_delivery details by ID: Provides webhook_delivery debug data, such as timestamps, delivery status and attempts.

Audit Logs

List Audit Logs: 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: List all user tags.

UserAddresses

List all user addresses: Returns a list of your user addresses.
Creates a user address: Creates a user address.
Retrieve a user address: Retrieves the details of an existing user address.

Integration Secrets

List integration secrets: Retrieve a list of all integration secrets configured by the user.
Create a secret: Create a new secret with an associated identifier that can be used to securely integrate with other services.
Delete an integration secret: Delete an integration secret given its ID.

​Telnyx Other APIs: Account & Billing — Full Documentation

​Usage reports

​Usage Reports

​Overview

​Query Requirements

​Products

​Dates

​Format

​Dimensions & Metrics Options Per Product

Request:

Response:

​Product Examples

​SIP Trunking

​Example 1: Simple SIP Report

Request:

Response:

​Example 2: Short Duration Calls

Request:

Response:

​Messaging

​Example 1: Simple Messaging Report

Request:

Response (abbreviated):

​Example 2: Alphanumeric by MNC/MCC

Request:

Response (abbreviated):

​Session analysis

​Session Analysis

​Session Analysis API Usage Guide

​What is Session Analysis?

​When to Use It

​Core Concepts

​Record Types

​Sessions

​Relationships

​Cost Rollup

​Endpoints

​1. List All Record Types

​2. Get Record Type Details

​3. Get Session Analysis

​Response Structure

​Top-Level Fields

​Event Node Structure

​Relationship Object

​Example: AI Voice Assistant Session

​Understanding the AI Cost Structure

​Common Use Cases

​Debugging High-Cost AI Sessions

​Finding Related Events

​Exporting for Analysis

​Best Practices

​Performance

​Querying

​Error Handling

​Record Types Reference

​AI & Voice Intelligence

​Voice & Telephony

​Media & Storage

​Conferencing

​Messaging

​Video

​Other Products

​On-Demand Reports

​On-Demand Reports

​Overview

​Getting started

​Example queries

​What you can do

​Current limitations

​API Reference (Account & Billing)

​AutoRechargePreferences

​Notifications

​Addresses

​Billing

​Authentication Providers

​IP Addresses

​IP Ranges

​Managed Accounts

​Organization Users

​Billing Groups

Telnyx Other APIs: Account & Billing — Full Documentation

Usage reports

Usage Reports

Overview

Query Requirements

Products

Dates

Format

Dimensions & Metrics Options Per Product

Product Examples

SIP Trunking

Example 1: Simple SIP Report

Example 2: Short Duration Calls

Messaging

Example 1: Simple Messaging Report

Example 2: Alphanumeric by MNC/MCC

Session analysis

Session Analysis

Session Analysis API Usage Guide

What is Session Analysis?

When to Use It

Core Concepts

Record Types

Sessions

Relationships

Cost Rollup

Endpoints

1. List All Record Types

2. Get Record Type Details

3. Get Session Analysis

Response Structure

Top-Level Fields

Event Node Structure

Relationship Object

Example: AI Voice Assistant Session

Understanding the AI Cost Structure

Common Use Cases

Debugging High-Cost AI Sessions

Finding Related Events

Exporting for Analysis

Best Practices

Performance

Querying

Error Handling

Record Types Reference

AI & Voice Intelligence

Voice & Telephony

Media & Storage

Conferencing

Messaging

Video

Other Products

On-Demand Reports

On-Demand Reports

Overview

Getting started

Example queries

What you can do

Current limitations

API Reference (Account & Billing)

AutoRechargePreferences

Notifications

Addresses

Billing

Authentication Providers

IP Addresses

IP Ranges

Managed Accounts

Organization Users

Billing Groups

Detail Records

MDR Detailed Reports

CDR Reports

MDR Usage Reports

Telco Data Usage Reports

Speech to text Usage Reports

CDR Usage Reports

Usage Reports (BETA)

Speech to Text Batch Reports

MDR Detail Reports