Open SidemenuDocs
Docs
Close Sidemenu

Find Product Usage Records via APIfind-product-usage-records-via-apibeta

Information about your Telnyx usage is available through the Detail Record Search API - a flexible, easy-to-use endpoint for records of conference calls, texts, and WhatsApp messages that you send using the Telnyx platform.

What is a Detail Record?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?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 above messaging example, you can search for detail records for messages 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 Recordshow-to-retrieve-detail-records

Note Type Info

At this time, you can only query for records from the last 90 days.

The /detail_records API endpoint has support for multiple types of detail records associated with multiple Telnyx products. 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.

What types of records can I find with the Detail Record Search API?what-types-of-records-can-i-find-with-the-detail-record-search-api-

Productrecord_type
Messagingmessaging
Conferenceconference, conference-participant
WhatsAppwhatsapp

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

Was this page helpful?