Ai telnyx-account-reports-ruby
git clone https://github.com/team-telnyx/ai
T=$(mktemp -d) && git clone --depth=1 https://github.com/team-telnyx/ai "$T" && mkdir -p ~/.claude/skills && cp -r "$T/providers/cursor/plugin/skills/telnyx-account-reports-ruby" ~/.claude/skills/team-telnyx-ai-telnyx-account-reports-ruby-4c82b6 && rm -rf "$T"
providers/cursor/plugin/skills/telnyx-account-reports-ruby/SKILL.mdTelnyx 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
for automatic iteration:.auto_paging_each
.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)