Find Product Usage Records via API

Information about your Telnyx usage is available through the Detail Record Search API - a flexible, easy-to-use endpoint for viewing records of your usage on the Telnyx platform.

What is a Detail Record?

A Detail Record provides a description of a single, product-specific request made through Telnyx. For example, if you send a message through the Telnyx Messaging API, a Message Detail Record (MDR) is generated, which includes information like the status, cost, and direction (“inbound” or ”outbound”) for that message. This MDR is stored in your Telnyx account and can be retrieved as part of a report in the Mission Control Portal.

What is the Detail Record Search API?

The Detail Record Search API is a tool for finding detail records based on multiple fields within those detail records. In the below messaging example, you can search for message detail records (MDRs) sent during a specific time span, for detail records associated with only “inbound” messages, or for detail records associated with messages sent from a particular number. Having multiple options to filter the records returned helps to troubleshoot potential issues and analyze your usage.

How to Retrieve Detail Records

The /detail_records API endpoint has support for multiple types of detail records associated with multiple Telnyx products. You can find a list of the supported products and their corresponding filter parameter (/filter[record_type]) values at the bottom of this page.

In this example, we want to query Message Detail Records (MDRs) to see all of the messages we’ve sent or received today.

Request:

curl --location -g --request GET \
'https://api.telnyx.com/v2/detail_records?filter[record_type]=messaging&filter[date_range]=today' \
--header 'Authorization: Bearer YOUR_API_KEY'

Response (abbreviated):

{
   "data": [
       {
           "carrier_fee": "0.0",
           "created_at": "2021-08-23T22:03:37Z",
           "mcc": "",
           "fteu": false,
           "profile_name": "My Telnyx Messaging Profile",
           "updated_at": "2021-08-23T22:03:37Z",
           "rate": "0.0000",
           "on_net": false,
           "cld": "+16155700362",
           "currency": "USD",
           "id": "593ecdfa-8b7c-43bf-b832-f34103a9d8ae",
           "direction": "inbound",
           "cli": "+13126040939",
           "cost": "0.0000",
           "mnc": "",
           "message_type": "SMS",
           "record_type": "message_detail_record",
           "tags": "",
           "sent_at": "2021-08-23T22:03:37Z",
           "country_code": "US",
           "completed_at": "2021-08-23T22:03:37Z",
           "carrier": "NEW CINGULAR WIRELESS PCS, LLC - IL",
           "user_id": "a37bdd47-f301-42ec-b2ad-5a0465bfb633",
           "delivery_status_failover_url": "",
           "profile_id": "40017980-7d67-4a2f-bf9e-f3a3762c0fa3",
           "parts": 1,
           "delivery_status_webhook_url": "https://webhook.site/2fa8fe78-ad37-44ce-9f13-1b16c76fb2b1",
           "source_country_code": "US",
           "errors": [],
           "delivery_status": "",
           "status": "delivered"
       },
       ...
   ],
   "meta": {
       "total_pages": 2,
       "total_results": 30,
       "page_number": 1,
       "page_size": 20
   }
}

Next, let's narrow down the results to only show outbound messages that were sent to a particular number, in this example +13176050941.

Request:

curl --location -g --request GET \
'https://api.telnyx.com/v2/detail_records?filter[record_type]=messaging&filter[date_range]=today&filter[direction]=outbound&filter[product]=long_code&filter[cld]=+13176050941' \
--header 'Authorization: Bearer YOUR_API_KEY'

Response (abbreviated):

{
   "data": [
       {
           "carrier_fee": "0.002",
           "created_at": "2021-08-23T22:03:19Z",
           "mcc": "",
           "fteu": false,
           "profile_name": "My Telnyx Messaging Profile",
           "updated_at": "2021-08-23T22:03:20Z",
           "rate": "0.00450",
           "on_net": false,
           "cld": "+13126070938",
           "currency": "USD",
           "id": "60317b75-0a11-42b1-a1df-8327ef3b6e81",
           "direction": "outbound",
           "cli": "+16125700364",
           "cost": "0.0045",
           "mnc": "",
           "message_type": "SMS",
           "record_type": "message_detail_record",
           "tags": "",
           "sent_at": "2021-08-23T22:03:20Z",
           "country_code": "US",
           "completed_at": "2021-08-23T22:03:20Z",
           "carrier": "NEW CINGULAR WIRELESS PCS, LLC - IL",
           "user_id": "d37bdd47-f301-42ec-b2ad-5a0465bfb632",
           "delivery_status_failover_url": "",
           "profile_id": "56817980-7d67-4a2f-bf9e-f3a3762c0fa3",
           "parts": 1,
           "delivery_status_webhook_url": "https://webhook.site/2fa8fe78-ad37-44ce-9f13-1b16c76fb2b1",
           "source_country_code": "US",
           "errors": [],
           "delivery_status": "",
           "status": "delivered"
       },
       ...
   ],
   "meta": {
       "total_pages": 1,
       "total_results": 10,
       "page_number": 1,
       "page_size": 20
   }
}

While this example illustrates a messaging use-case, the same patterns can be used to view records for any of the products listed below, using any of the attributes listed in the full API reference to refine your results.

Tips & Tricks for searching with the Detail Record Search API

The options for use with the /filter[date_range] parameter can be found in the Date Literals section of our API overview.

You can filter based on almost any field within the schema of the record type you’re looking for by using /filter[name_of_field]=. For specifying more complex query types than “equal to”, you'll find info on complex filters in our API overview.

What types of records can I find with the Detail Record Search API?

Productrecord_type
Messagingmessaging
Conferenceconference, conference-participant
WhatsAppwhatsapp , whatsapp-conversation
Answering Machine Detectionamd
Verify APIverify
IoT SIM Cardwireless
Media Storagemedia_storage

More products and capabilities will be added to the API soon - sign up for a Telnyx account to be the first to hear about new updates!

Was this page helpful?