Detail Record Search

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.

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 .

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.

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'

Note

After pasting the above content, Kindly check and remove any new line added

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

Note

After pasting the above content, Kindly check and remove any new line added

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'

Note

After pasting the above content, Kindly check and remove any new line added

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

Note

After pasting the above content, Kindly check and remove any new line added

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 Debugging API reference to refine your results.

ai-voice-assistant, amd, call-control, conference, conference-participant, embedding, fax, inference, inference-speech-to-text, media_storage, media-streaming, messaging, noise-suppression, recording, sip-trunking, siprec-client, stt, tts, verify, webrtc, wireless

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!