OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add team-telnyx/ai --skill telnyx-account-reports-javascript
Generate and retrieve usage reports for billing, analytics, and reconciliation. This skill provides JavaScript SDK examples.
npx skills add team-telnyx/ai --skill telnyx-account-reports-javascript
All examples below assume client is already initialized as shown above.
All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:
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).
for await (const item of result) { ... } to iterate through all pages automatically.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
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)
POST /ledger_billing_group_reports
Optional: month (integer), year (integer)
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 /ledger_billing_group_reports/{id}
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)
Retrieves all MDR detailed report requests for the authenticated user
GET /legacy/reporting/batch_detail_records/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)
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)
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)
Retrieves a specific MDR detailed report request by ID
GET /legacy/reporting/batch_detail_records/messaging/{id}
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)
Deletes a specific MDR detailed report request by ID
DELETE /legacy/reporting/batch_detail_records/messaging/{id}
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)
Retrieves all CDR report requests for the authenticated user
GET /legacy/reporting/batch_detail_records/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)
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)
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)
Retrieves all available fields that can be used in CDR reports
GET /legacy/reporting/batch_detail_records/voice/fields
Returns: Billing (array[string]), Interaction Data (array[string]), Number Information (array[string]), Telephony Data (array[string])
Retrieves a specific CDR report request by ID
GET /legacy/reporting/batch_detail_records/voice/{id}
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)
Deletes a specific CDR report request by ID
DELETE /legacy/reporting/batch_detail_records/voice/{id}
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)
Fetch all previous requests for MDR usage reports.
GET /legacy/reporting/usage_reports/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)
Creates a new legacy usage V2 MDR report request with the specified filters
POST /legacy/reporting/usage_reports/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)
Fetch single MDR usage report by id.
GET /legacy/reporting/usage_reports/messaging/{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)
Deletes a specific V2 legacy usage MDR report request by ID
DELETE /legacy/reporting/usage_reports/messaging/{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)
Retrieve a paginated list of telco data usage reports
GET /legacy/reporting/usage_reports/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)
Submit a new telco data usage report
POST /legacy/reporting/usage_reports/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)
Retrieve a specific telco data usage report by its ID
GET /legacy/reporting/usage_reports/number_lookup/{id}
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 a specific telco data usage report by its ID
DELETE /legacy/reporting/usage_reports/number_lookup/{id}
Fetch all previous requests for cdr usage reports.
GET /legacy/reporting/usage_reports/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)
Creates a new legacy usage V2 CDR report request with the specified filters
POST /legacy/reporting/usage_reports/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)
Fetch single cdr usage report by id.
GET /legacy/reporting/usage_reports/voice/{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)
Deletes a specific V2 legacy usage CDR report request by ID
DELETE /legacy/reporting/usage_reports/voice/{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)
GET /phone_numbers/csv_downloads
Returns: id (string), record_type (string), status (enum: pending, complete, failed, expired), url (string)
POST /phone_numbers/csv_downloads
Returns: id (string), record_type (string), status (enum: pending, complete, failed, expired), url (string)
GET /phone_numbers/csv_downloads/{id}
Returns: id (string), record_type (string), status (enum: pending, complete, failed, expired), url (string)
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
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. Usage reports are aggregated messaging data for specified time period and breakdown
GET /reports/mdr_usage_reports
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)
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
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 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
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 a single messaging usage report by id
GET /reports/mdr_usage_reports/{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)
Delete messaging usage report by id
DELETE /reports/mdr_usage_reports/{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)
GET /reports/mdrs
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)
Fetch all Wdr records
GET /reports/wdrs
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)
Returns all available record types and supported query parameters for session analysis.
GET /session_analysis/metadata
Returns: meta (object), query_parameters (object), record_types (array[object])
Returns detailed metadata for a specific record type, including relationships and examples.
GET /session_analysis/metadata/{record_type}
Returns: aliases (array[string]), child_relationships (array[object]), event (string), examples (object), meta (object), parent_relationships (array[object]), product (string), record_type (string)
Retrieves a full session analysis tree for a given event, including costs, child events, and product linkages.
GET /session_analysis/{record_type}/{event_id}
Returns: cost (object), meta (object), root (object), session_id (string)
Get Telnyx usage data by product, broken out by the specified dimensions
GET /usage_reports
Returns: data (array[object]), meta (object)
Get the Usage Reports options for querying usage, including the products available and their respective metrics and dimensions
GET /usage_reports/options
Returns: product (string), product_dimensions (array[string]), product_metrics (array[string]), record_types (array[object])
Returns the WDR Reports that match the given parameters.
GET /wireless/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)
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)
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)
Returns one specific WDR report
GET /wireless/detail_records_reports/{id}
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)
Deletes one specific WDR report.
DELETE /wireless/detail_records_reports/{id}
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)
try {
const result = await client.messages.send({ to: '+13125550001', from: '+13125550002', text: 'Hello' });
} catch (err) {
if (err instanceof Telnyx.APIConnectionError) {
console.error('Network error — check connectivity and retry');
} else if (err instanceof Telnyx.RateLimitError) {
// 429: rate limited — wait and retry with exponential backoff
const retryAfter = err.headers?.['retry-after'] || 1;
await new Promise(r => setTimeout(r, retryAfter * 1000));
} else if (err instanceof Telnyx.APIError) {
console.error(`API error ${err.status}: ${err.message}`);
if (err.status === 422) {
console.error('Validation error — check required fields and formats');
}
}
}// Automatically fetches more pages as needed.
for await (const callEventListResponse of client.callEvents.list()) {
console.log(callEventListResponse.call_leg_id);
}const ledgerBillingGroupReport = await client.ledgerBillingGroupReports.create({
month: 10,
year: 2019,
});
console.log(ledgerBillingGroupReport.data);const ledgerBillingGroupReport = await client.ledgerBillingGroupReports.retrieve(
'f5586561-8ff0-4291-a0ac-84fe544797bd',
);
console.log(ledgerBillingGroupReport.data);const messagings = await client.legacy.reporting.batchDetailRecords.messaging.list();
console.log(messagings.data);const messaging = await client.legacy.reporting.batchDetailRecords.messaging.create({
end_time: '2024-02-12T23:59:59Z',
start_time: '2024-02-01T00:00:00Z',
});
console.log(messaging.data);const messaging = await client.legacy.reporting.batchDetailRecords.messaging.retrieve(
'182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);
console.log(messaging.data);const messaging = await client.legacy.reporting.batchDetailRecords.messaging.delete(
'182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);
console.log(messaging.data);const voices = await client.legacy.reporting.batchDetailRecords.voice.list();
console.log(voices.data);const voice = await client.legacy.reporting.batchDetailRecords.voice.create({
end_time: '2024-02-12T23:59:59Z',
start_time: '2024-02-01T00:00:00Z',
});
console.log(voice.data);const response = await client.legacy.reporting.batchDetailRecords.voice.retrieveFields();
console.log(response.Billing);const voice = await client.legacy.reporting.batchDetailRecords.voice.retrieve(
'182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);
console.log(voice.data);const voice = await client.legacy.reporting.batchDetailRecords.voice.delete(
'182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);
console.log(voice.data);// Automatically fetches more pages as needed.
for await (const mdrUsageReportResponseLegacy of client.legacy.reporting.usageReports.messaging.list()) {
console.log(mdrUsageReportResponseLegacy.id);
}const messaging = await client.legacy.reporting.usageReports.messaging.create({
aggregation_type: 0,
});
console.log(messaging.data);const messaging = await client.legacy.reporting.usageReports.messaging.retrieve(
'182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);
console.log(messaging.data);const messaging = await client.legacy.reporting.usageReports.messaging.delete(
'182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);
console.log(messaging.data);const numberLookups = await client.legacy.reporting.usageReports.numberLookup.list();
console.log(numberLookups.data);const numberLookup = await client.legacy.reporting.usageReports.numberLookup.create();
console.log(numberLookup.data);const numberLookup = await client.legacy.reporting.usageReports.numberLookup.retrieve('550e8400-e29b-41d4-a716-446655440000');
console.log(numberLookup.data);await client.legacy.reporting.usageReports.numberLookup.delete('550e8400-e29b-41d4-a716-446655440000');// Automatically fetches more pages as needed.
for await (const cdrUsageReportResponseLegacy of client.legacy.reporting.usageReports.voice.list()) {
console.log(cdrUsageReportResponseLegacy.id);
}const voice = await client.legacy.reporting.usageReports.voice.create({
end_time: '2024-02-01T00:00:00Z',
start_time: '2024-02-01T00:00:00Z',
});
console.log(voice.data);const voice = await client.legacy.reporting.usageReports.voice.retrieve(
'182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);
console.log(voice.data);const voice = await client.legacy.reporting.usageReports.voice.delete(
'182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);
console.log(voice.data);// Automatically fetches more pages as needed.
for await (const csvDownload of client.phoneNumbers.csvDownloads.list()) {
console.log(csvDownload.id);
}const csvDownload = await client.phoneNumbers.csvDownloads.create();
console.log(csvDownload.data);const csvDownload = await client.phoneNumbers.csvDownloads.retrieve('550e8400-e29b-41d4-a716-446655440000');
console.log(csvDownload.data);const response = await client.reports.cdrUsageReports.fetchSync({
aggregation_type: 'NO_AGGREGATION',
product_breakdown: 'NO_BREAKDOWN',
});
console.log(response.data);// Automatically fetches more pages as needed.
for await (const mdrUsageReport of client.reports.mdrUsageReports.list()) {
console.log(mdrUsageReport.id);
}const mdrUsageReport = await client.reports.mdrUsageReports.create({
aggregation_type: 'NO_AGGREGATION',
end_date: '2020-07-01T00:00:00-06:00',
start_date: '2020-07-01T00:00:00-06:00',
});
console.log(mdrUsageReport.data);const response = await client.reports.mdrUsageReports.fetchSync({ aggregation_type: 'PROFILE' });
console.log(response.data);const mdrUsageReport = await client.reports.mdrUsageReports.retrieve(
'182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);
console.log(mdrUsageReport.data);const mdrUsageReport = await client.reports.mdrUsageReports.delete(
'182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);
console.log(mdrUsageReport.data);const response = await client.reports.listMdrs();
console.log(response.data);// Automatically fetches more pages as needed.
for await (const reportListWdrsResponse of client.reports.listWdrs()) {
console.log(reportListWdrsResponse.id);
}const metadata = await client.sessionAnalysis.metadata.retrieve();
console.log(metadata.meta);const response = await client.sessionAnalysis.metadata.retrieveRecordType('record_type');
console.log(response.aliases);const sessionAnalysis = await client.sessionAnalysis.retrieve(
'182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
{ record_type: 'record_type' },
);
console.log(sessionAnalysis.session_id);// Automatically fetches more pages as needed.
for await (const usageReportListResponse of client.usageReports.list({
dimensions: ['string'],
metrics: ['string'],
product: 'wireless',
})) {
console.log(usageReportListResponse);
}const response = await client.usageReports.getOptions();
console.log(response.data);const detailRecordsReports = await client.wireless.detailRecordsReports.list();
console.log(detailRecordsReports.data);const detailRecordsReport = await client.wireless.detailRecordsReports.create();
console.log(detailRecordsReport.data);const detailRecordsReport = await client.wireless.detailRecordsReports.retrieve(
'6a09cdc3-8948-47f0-aa62-74ac943d6c58',
);
console.log(detailRecordsReport.data);const detailRecordsReport = await client.wireless.detailRecordsReports.delete(
'6a09cdc3-8948-47f0-aa62-74ac943d6c58',
);
console.log(detailRecordsReport.data);