Telnyx Account Reports - Ruby

Installation

gem install telnyx

Setup

require "telnyx"

client = Telnyx::Client.new(
  api_key: ENV["TELNYX_API_KEY"], # This is the default and can be omitted
)

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:

begin
  result = client.messages.send_(to: "+13125550001", from: "+13125550002", text: "Hello")
rescue Telnyx::Errors::APIConnectionError
  puts "Network error — check connectivity and retry"
rescue Telnyx::Errors::RateLimitError
  # 429: rate limited — wait and retry with exponential backoff
  sleep(1) # Check Retry-After header for actual delay
rescue Telnyx::Errors::APIStatusError => e
  puts "API error #{e.status}: #{e.message}"
  if e.status == 422
    puts "Validation error — check required fields and formats"
  end
end

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: Use .auto_paging_each for automatic iteration: page.auto_paging_each { |item| puts item.id }.

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

puts(page)

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

POST /ledger_billing_group_reports

Optional: month (integer), year (integer)

ledger_billing_group_report = client.ledger_billing_group_reports.create

puts(ledger_billing_group_report)

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

GET /ledger_billing_group_reports/{id}

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

puts(ledger_billing_group_report)

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

puts(messagings)

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)

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

puts(messaging)

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)

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

puts(messaging)

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)

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

puts(messaging)

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)

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

puts(voices)

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)

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

puts(voice)

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)

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

puts(response)

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

puts(voice)

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)

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

puts(voice)

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)

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

puts(page)

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)

puts(messaging)

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)

Get an MDR usage report

Fetch single MDR usage report by id.

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

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

puts(messaging)

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)

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

puts(messaging)

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)

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

puts(number_lookups)

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

Submit a new telco data usage report

POST /legacy/reporting/usage_reports/number_lookup

number_lookup = client.legacy.reporting.usage_reports.number_lookup.create

puts(number_lookup)

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)

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

puts(number_lookup)

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)

Delete telco data usage report

Delete a specific telco data usage report by its ID

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

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

puts(result)

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

puts(page)

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

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

puts(voice)

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)

Get a CDR usage report

Fetch single cdr usage report by id.

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

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

puts(voice)

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)

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

puts(voice)

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)

List CSV downloads

GET /phone_numbers/csv_downloads

page = client.phone_numbers.csv_downloads.list

puts(page)

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

Create a CSV download

POST /phone_numbers/csv_downloads

csv_download = client.phone_numbers.csv_downloads.create

puts(csv_download)

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

Retrieve a CSV download

GET /phone_numbers/csv_downloads/{id}

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

puts(csv_download)

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
)

puts(response)

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

puts(page)

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

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

puts(mdr_usage_report)

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)

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)

puts(response)

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)

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

puts(mdr_usage_report)

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)

Delete MDR Usage Report

Delete messaging usage report by id

DELETE /reports/mdr_usage_reports/{id}

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

puts(mdr_usage_report)

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)

Fetch all Mdr records

GET /reports/mdrs

response = client.reports.list_mdrs

puts(response)

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

Fetch all Wdr records

GET /reports/wdrs

page = client.reports.list_wdrs

puts(page)

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

puts(metadata)

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

puts(response)

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("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", record_type: "record_type")

puts(session_analysis)

Returns: completed_at (date-time), cost (object), created_at (date-time), meta (object), root (object), session_id (string), status (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")

puts(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

puts(response)

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

puts(detail_records_reports)

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

puts(detail_records_report)

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)

Get a Wireless Detail Record (WDR) Report

Returns one specific WDR report

GET /wireless/detail_records_reports/{id}

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

puts(detail_records_report)

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)

Delete a Wireless Detail Record (WDR) Report

Deletes one specific WDR report.

DELETE /wireless/detail_records_reports/{id}

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

puts(detail_records_report)

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)