FreePublished on GitHub

telnyx-account-reports-python

Generate and retrieve usage reports for billing, analytics, and reconciliation. This skill provides Python SDK examples.

The English summary is being prepared. Showing the original description.

team-telnyx/ai

See how to install

Files included (1)

SKILL.md28.4 KB

SKILL.md (original)

Review the instructions the agent will receive before you install.

Telnyx Account Reports - Python

Installation

pip install telnyx

Setup

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
    public_key=os.environ.get("TELNYX_PUBLIC_KEY"),  # Required for client.webhooks.unwrap() (webhook verification)
)

All examples below assume client is already initialized as shown above.

Error Handling

All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:

import telnyx

try:
    result = client.messages.send(to="+13125550001", from_="+13125550002", text="Hello")
except telnyx.APIConnectionError:
    print("Network error — check connectivity and retry")
    raise
except telnyx.RateLimitError:
    # 429: rate limited — wait, then retry the request (bounded exponential backoff)
    import time
    time.sleep(1)  # Check Retry-After header for actual delay
    # ...retry the call here (give up after a few attempts); otherwise re-raise:
    raise
except telnyx.APIStatusError as e:
    print(f"API error {e.status_code}: {e.message}")
    if e.status_code == 422:
        print("Validation error — check required fields and formats")
    raise  # A failed request must never look like success to the caller

Common error codes: 401 invalid API key, 403 insufficient permissions, 404 resource not found, 422 validation error (check field formats), 429 rate limited (retry with exponential backoff).

Important Notes

Pagination: List methods return an auto-paginating iterator. Use for item in page_result: to iterate through all pages automatically.

List call events

Filters call events by given filter parameters. Events are ordered by occurred_at. If filter for leg_id or application_session_id is not present, it only filters events from the last 24 hours.

GET /call_events

page = client.call_events.list()
page = page.data[0]
print(page.call_leg_id)

Returns: call_leg_id (string), call_session_id (string), event_timestamp (string), metadata (object), name (string), record_type (enum: call_event), type (enum: command, webhook)

Create a ledger billing group report

Create a ledger billing group report, which aggregates ledger activity by billing group.

POST /ledger_billing_group_reports

Optional: month (integer), year (integer)

ledger_billing_group_report = client.ledger_billing_group_reports.create(
    month=10,
    year=2019,
)
print(ledger_billing_group_report.data)

Returns: created_at (date-time), id (uuid), organization_id (uuid), record_type (enum: ledger_billing_group_report), report_url (uri), status (enum: pending, complete, failed, deleted), updated_at (date-time)

Get a ledger billing group report

Retrieve the details and status of a previously created ledger billing group report.

GET /ledger_billing_group_reports/{id}

ledger_billing_group_report = client.ledger_billing_group_reports.retrieve(
    "f5586561-8ff0-4291-a0ac-84fe544797bd",
)
print(ledger_billing_group_report.data)

Get all MDR detailed report requests

Retrieves all MDR detailed report requests for the authenticated user

GET /legacy/reporting/batch_detail_records/messaging

messagings = client.legacy.reporting.batch_detail_records.messaging.list()
print(messagings.data)

Returns: connections (array[integer]), created_at (date-time), directions (array[string]), end_date (date-time), filters (array[object]), id (uuid), profiles (array[string]), record_type (string), record_types (array[string]), report_name (string), report_url (string), start_date (date-time), status (enum: PENDING, COMPLETE, FAILED, EXPIRED), updated_at (date-time)

Create a new MDR detailed report request

Creates a new MDR detailed report request with the specified filters

POST /legacy/reporting/batch_detail_records/messaging — Required: start_time, end_time

Optional: connections (array[integer]), directions (array[integer]), filters (array[object]), include_message_body (boolean), managed_accounts (array[string]), profiles (array[string]), record_types (array[integer]), report_name (string), select_all_managed_accounts (boolean), timezone (string)

from datetime import datetime

messaging = client.legacy.reporting.batch_detail_records.messaging.create(
    end_time=datetime.fromisoformat("2024-02-12T23:59:59"),
    start_time=datetime.fromisoformat("2024-02-01T00:00:00"),
)
print(messaging.data)

Get a specific MDR detailed report request

Retrieves a specific MDR detailed report request by ID

GET /legacy/reporting/batch_detail_records/messaging/{id}

messaging = client.legacy.reporting.batch_detail_records.messaging.retrieve(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(messaging.data)

Delete a MDR detailed report request

Deletes a specific MDR detailed report request by ID

DELETE /legacy/reporting/batch_detail_records/messaging/{id}

messaging = client.legacy.reporting.batch_detail_records.messaging.delete(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(messaging.data)

Get all CDR report requests

Retrieves all CDR report requests for the authenticated user

GET /legacy/reporting/batch_detail_records/voice

voices = client.legacy.reporting.batch_detail_records.voice.list()
print(voices.data)

Returns: call_types (array[integer]), connections (array[integer]), created_at (string), end_time (string), filters (array[object]), id (string), managed_accounts (array[string]), record_type (string), record_types (array[integer]), report_name (string), report_url (string), retry (int32), source (string), start_time (string), status (int32), timezone (string), updated_at (string)

Create a new CDR report request

Creates a new CDR report request with the specified filters

POST /legacy/reporting/batch_detail_records/voice — Required: start_time, end_time

Optional: call_types (array[integer]), connections (array[integer]), fields (array[string]), filters (array[object]), include_all_metadata (boolean), managed_accounts (array[string]), record_types (array[integer]), report_name (string), select_all_managed_accounts (boolean), source (string), timezone (string)

from datetime import datetime

voice = client.legacy.reporting.batch_detail_records.voice.create(
    end_time=datetime.fromisoformat("2024-02-12T23:59:59"),
    start_time=datetime.fromisoformat("2024-02-01T00:00:00"),
)
print(voice.data)

Get available CDR report fields

Retrieves all available fields that can be used in CDR reports

GET /legacy/reporting/batch_detail_records/voice/fields

response = client.legacy.reporting.batch_detail_records.voice.retrieve_fields()
print(response.billing)

Returns: Billing (array[string]), Interaction Data (array[string]), Number Information (array[string]), Telephony Data (array[string])

Get a specific CDR report request

Retrieves a specific CDR report request by ID

GET /legacy/reporting/batch_detail_records/voice/{id}

voice = client.legacy.reporting.batch_detail_records.voice.retrieve(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(voice.data)

Delete a CDR report request

Deletes a specific CDR report request by ID

DELETE /legacy/reporting/batch_detail_records/voice/{id}

voice = client.legacy.reporting.batch_detail_records.voice.delete(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(voice.data)

List MDR usage reports

Fetch all previous requests for MDR usage reports.

GET /legacy/reporting/usage_reports/messaging

page = client.legacy.reporting.usage_reports.messaging.list()
page = page.data[0]
print(page.id)

Returns: aggregation_type (int32), connections (array[string]), created_at (date-time), end_time (date-time), id (uuid), profiles (array[string]), record_type (string), report_url (string), result (object), start_time (date-time), status (int32), updated_at (date-time)

Create a new legacy usage V2 MDR report request

Creates a new legacy usage V2 MDR report request with the specified filters

POST /legacy/reporting/usage_reports/messaging

messaging = client.legacy.reporting.usage_reports.messaging.create(
    aggregation_type=0,
)
print(messaging.data)

Get an MDR usage report

Returns a single MDR (Message Detail Record) usage report by its identifier, including its parameters and current status.

GET /legacy/reporting/usage_reports/messaging/{id}

messaging = client.legacy.reporting.usage_reports.messaging.retrieve(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(messaging.data)

Delete a V2 legacy usage MDR report request

Deletes a specific V2 legacy usage MDR report request by ID

DELETE /legacy/reporting/usage_reports/messaging/{id}

messaging = client.legacy.reporting.usage_reports.messaging.delete(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(messaging.data)

List telco data usage reports

Retrieve a paginated list of telco data usage reports

GET /legacy/reporting/usage_reports/number_lookup

number_lookups = client.legacy.reporting.usage_reports.number_lookup.list()
print(number_lookups.data)

Returns: aggregation_type (string), created_at (date-time), end_date (date), id (uuid), managed_accounts (array[string]), record_type (string), report_url (string), result (array[object]), start_date (date), status (string), updated_at (date-time)

Submit telco data usage report

Submits a new telco data (number lookup) usage report request. The report is generated asynchronously; retrieve it by its identifier once ready.

POST /legacy/reporting/usage_reports/number_lookup

number_lookup = client.legacy.reporting.usage_reports.number_lookup.create()
print(number_lookup.data)

Get telco data usage report by ID

Retrieve a specific telco data usage report by its ID

GET /legacy/reporting/usage_reports/number_lookup/{id}

number_lookup = client.legacy.reporting.usage_reports.number_lookup.retrieve("550e8400-e29b-41d4-a716-446655440000",
)
print(number_lookup.data)

Delete telco data usage report

Delete a specific telco data usage report by its ID

DELETE /legacy/reporting/usage_reports/number_lookup/{id}

client.legacy.reporting.usage_reports.number_lookup.delete("550e8400-e29b-41d4-a716-446655440000",
)

List CDR usage reports

Fetch all previous requests for cdr usage reports.

GET /legacy/reporting/usage_reports/voice

page = client.legacy.reporting.usage_reports.voice.list()
page = page.data[0]
print(page.id)

Returns: aggregation_type (int32), connections (array[string]), created_at (date-time), end_time (date-time), id (uuid), product_breakdown (int32), record_type (string), report_url (string), result (object), start_time (date-time), status (int32), updated_at (date-time)

Create a new legacy usage V2 CDR report request

Creates a new legacy usage V2 CDR report request with the specified filters

POST /legacy/reporting/usage_reports/voice

from datetime import datetime

voice = client.legacy.reporting.usage_reports.voice.create(
    end_time=datetime.fromisoformat("2024-02-01T00:00:00"),
    start_time=datetime.fromisoformat("2024-02-01T00:00:00"),
)
print(voice.data)

Get a CDR usage report

Returns a single CDR (Call Detail Record) usage report by its identifier, including its parameters and current status.

GET /legacy/reporting/usage_reports/voice/{id}

voice = client.legacy.reporting.usage_reports.voice.retrieve(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(voice.data)

Delete a V2 legacy usage CDR report request

Deletes a specific V2 legacy usage CDR report request by ID

DELETE /legacy/reporting/usage_reports/voice/{id}

voice = client.legacy.reporting.usage_reports.voice.delete(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(voice.data)

List CSV downloads

Returns CSV export jobs created for account phone numbers, including each export's current status and pagination metadata.

GET /phone_numbers/csv_downloads

page = client.phone_numbers.csv_downloads.list()
page = page.data[0]
print(page.id)

Returns: id (string), record_type (string), status (enum: pending, complete, failed, expired), url (string)

Create a CSV download

Starts generation of a CSV export for phone numbers matching the supplied filters. The csv_format parameter selects the output format, and the response contains the resulting download record.

POST /phone_numbers/csv_downloads

csv_download = client.phone_numbers.csv_downloads.create()
print(csv_download.data)

Returns: id (string), record_type (string), status (enum: pending, complete, failed, expired), url (string)

Retrieve a CSV download

Returns the current status and download details for the CSV export identified by id.

GET /phone_numbers/csv_downloads/{id}

csv_download = client.phone_numbers.csv_downloads.retrieve("550e8400-e29b-41d4-a716-446655440000",
)
print(csv_download.data)

Returns: id (string), record_type (string), status (enum: pending, complete, failed, expired), url (string)

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 necessary but the response may take up to a couple of minutes.

GET /reports/cdr_usage_reports/sync

response = client.reports.cdr_usage_reports.fetch_sync(
    aggregation_type="NO_AGGREGATION",
    product_breakdown="NO_BREAKDOWN",
)
print(response.data)

Returns: aggregation_type (enum: NO_AGGREGATION, CONNECTION, TAG, BILLING_GROUP), connections (array[integer]), created_at (date-time), end_time (date-time), id (uuid), product_breakdown (enum: NO_BREAKDOWN, DID_VS_TOLL_FREE, COUNTRY, DID_VS_TOLL_FREE_PER_COUNTRY), record_type (string), report_url (string), result (object), start_time (date-time), status (enum: PENDING, COMPLETE, FAILED, EXPIRED), updated_at (date-time)

Fetch all Messaging usage reports

Fetch all messaging usage reports. Usage reports are aggregated messaging data for specified time period and breakdown

GET /reports/mdr_usage_reports

page = client.reports.mdr_usage_reports.list()
page = page.data[0]
print(page.id)

Returns: aggregation_type (enum: NO_AGGREGATION, PROFILE, TAGS), connections (array[integer]), created_at (date-time), end_date (date-time), id (uuid), profiles (string), record_type (string), report_url (string), result (array[object]), start_date (date-time), status (enum: PENDING, COMPLETE, FAILED, EXPIRED), updated_at (date-time)

Create MDR Usage Report

Submit request for new new messaging usage report. This endpoint will pull and aggregate messaging data in specified time period.

POST /reports/mdr_usage_reports

from datetime import datetime

mdr_usage_report = client.reports.mdr_usage_reports.create(
    aggregation_type="NO_AGGREGATION",
    end_date=datetime.fromisoformat("2020-07-01T00:00:00-06:00"),
    start_date=datetime.fromisoformat("2020-07-01T00:00:00-06:00"),
)
print(mdr_usage_report.data)

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 polling is necessary but the response may take up to a couple of minutes.

GET /reports/mdr_usage_reports/sync

response = client.reports.mdr_usage_reports.fetch_sync(
    aggregation_type="PROFILE",
)
print(response.data)

Retrieve messaging report

Fetch a single messaging usage report by id

GET /reports/mdr_usage_reports/{id}

mdr_usage_report = client.reports.mdr_usage_reports.retrieve(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(mdr_usage_report.data)

Delete MDR Usage Report

Permanently deletes the specified messaging usage report by its identifier.

DELETE /reports/mdr_usage_reports/{id}

mdr_usage_report = client.reports.mdr_usage_reports.delete(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(mdr_usage_report.data)

Fetch all Mdr records

Returns message detail records (MDRs) matching the provided criteria, such as date range, direction, status, and message type.

GET /reports/mdrs

response = client.reports.list_mdrs()
print(response.data)

Returns: cld (string), cli (string), cost (string), created_at (date-time), currency (enum: AUD, CAD, EUR, GBP, USD), direction (string), id (string), message_type (enum: SMS, MMS), parts (number), profile_name (string), rate (string), record_type (string), status (enum: GW_TIMEOUT, DELIVERED, DLR_UNCONFIRMED, DLR_TIMEOUT, RECEIVED, GW_REJECT, FAILED)

Fetches all Wdr records

Returns wireless detail records (WDRs) matching the provided criteria, such as date range, SIM card, IMSI, or phone number, with pagination and sorting.

GET /reports/wdrs

page = client.reports.list_wdrs()
page = page.data[0]
print(page.id)

Returns: cost (object), created_at (date-time), downlink_data (object), duration_seconds (number), id (string), imsi (string), mcc (string), mnc (string), phone_number (string), rate (object), record_type (string), sim_card_id (string), sim_group_id (string), sim_group_name (string), uplink_data (object)

Get metadata overview

Returns all available record types and supported query parameters for session analysis.

GET /session_analysis/metadata

metadata = client.session_analysis.metadata.retrieve()
print(metadata.meta)

Returns: meta (object), query_parameters (object), record_types (array[object])

Get record type metadata

Returns detailed metadata for a specific record type, including relationships and examples.

GET /session_analysis/metadata/{record_type}

response = client.session_analysis.metadata.retrieve_record_type(
    "record_type",
)
print(response.aliases)

Returns: aliases (array[string]), child_relationships (array[object]), event (string), examples (object), meta (object), parent_relationships (array[object]), product (string), record_type (string)

Get session analysis

Retrieves a full session analysis tree for a given event, including costs, child events, and product linkages.

GET /session_analysis/{record_type}/{event_id}

session_analysis = client.session_analysis.retrieve(
    event_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    record_type="record_type",
)
print(session_analysis.session_id)

Returns: cost (object), meta (object), root (object), session_id (string)

Get Telnyx product usage data (BETA)

Get Telnyx usage data by product, broken out by the specified dimensions

GET /usage_reports

page = client.usage_reports.list(
    dimensions=["string"],
    metrics=["string"],
    product="wireless",
)
page = page.data[0]
print(page)

Returns: data (array[object]), meta (object)

Get Usage Reports query options (BETA)

Get the Usage Reports options for querying usage, including the products available and their respective metrics and dimensions

GET /usage_reports/options

response = client.usage_reports.get_options()
print(response.data)

Returns: product (string), product_dimensions (array[string]), product_metrics (array[string]), record_types (array[object])

Get all Wireless Detail Records (WDRs) Reports

Returns the WDR Reports that match the given parameters.

GET /wireless/detail_records_reports

detail_records_reports = client.wireless.detail_records_reports.list()
print(detail_records_reports.data)

Returns: created_at (string), end_time (string), id (uuid), record_type (string), report_url (string), start_time (string), status (enum: pending, complete, failed, deleted), updated_at (string)

Create a Wireless Detail Records (WDRs) Report

Asynchronously create a report containing Wireless Detail Records (WDRs) for the SIM cards that consumed wireless data in the given time period.

POST /wireless/detail_records_reports

Optional: end_time (string), start_time (string)

detail_records_report = client.wireless.detail_records_reports.create()
print(detail_records_report.data)

Get a Wireless Detail Record (WDR) Report

Returns a single Wireless Detail Record (WDR) report by its identifier, including its parameters and current status.

GET /wireless/detail_records_reports/{id}

detail_records_report = client.wireless.detail_records_reports.retrieve(
    "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
)
print(detail_records_report.data)

Delete a Wireless Detail Record (WDR) Report

Permanently deletes the specified Wireless Detail Record (WDR) report.

DELETE /wireless/detail_records_reports/{id}

detail_records_report = client.wireless.detail_records_reports.delete(
    "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
)
print(detail_records_report.data)

Reviews

No reviews yet. Tell others what you thought.

Comments

No login needed. Share how it worked for you, ask a question, or note where it did not run.

No comments yet. Be the first to write one.

More skills from this repository

push-notification-tester

Free

Test VoIP push notifications for Telnyx WebRTC iOS (APNs) and Android (FCM) apps. Use when debugging push notification delivery, validating certificate/credential setup, or testing that a device receives VoIP pushes correctly.

The English summary is being prepared. Showing the original description.

team-telnyx/ai222Updated Oct 21, 2026

telnyx-10dlc-curl

Free

10DLC brand and campaign registration for US A2P messaging compliance. Assign phone numbers to campaigns.

The English summary is being prepared. Showing the original description.

team-telnyx/ai222Updated Oct 21, 2026

telnyx-10dlc-go

Free

10DLC brand and campaign registration for US A2P messaging compliance. Assign phone numbers to campaigns.

The English summary is being prepared. Showing the original description.

team-telnyx/ai222Updated Oct 21, 2026

telnyx-10dlc-java

Free

10DLC brand and campaign registration for US A2P messaging compliance. Assign phone numbers to campaigns.

The English summary is being prepared. Showing the original description.

team-telnyx/ai222Updated Oct 21, 2026

telnyx-10dlc-javascript

Free

10DLC brand and campaign registration for US A2P messaging compliance. Assign phone numbers to campaigns.

The English summary is being prepared. Showing the original description.

team-telnyx/ai222Updated Oct 21, 2026

telnyx-10dlc-python

Free

10DLC brand and campaign registration for US A2P messaging compliance. Assign phone numbers to campaigns.

The English summary is being prepared. Showing the original description.

team-telnyx/ai222Updated Oct 21, 2026

See all skills by team-telnyx

Report a problem with this skill

Install

Install with a command

npx skills add https://github.com/team-telnyx/ai --skill telnyx-account-reports-python

Paste it into your terminal and run it (requires Node.js). You can choose which agents to install it for, such as Claude Code or Codex.

Ask your agent

Please install the following Agent Skill.
https://github.com/team-telnyx/ai/tree/main/skills/telnyx-account-reports-python

First review SKILL.md and the bundled files and confirm there is nothing suspicious (such as sending data externally or reading credentials). Then place it in ~/.claude/skills/telnyx-account-reports-python/ for Claude Code, or ~/.agents/skills/telnyx-account-reports-python/ for Codex.

Send this text to Claude Code or Codex as is. It checks the contents before installing.

View source on GitHub

Repository: team-telnyx/ai
Stars: 222
Forks: 24
Category: Development
License: MIT
Original language: English
Last updated: Oct 21, 2026

A skill is a set of instructions and scripts for an agent. cccskills does not guarantee that skills are safe. Review the contents before you install.