--- title: "How to retrieve CDRs" slug: "how-to-retrieve-cdrs" updated: 2024-10-25T14:25:20Z published: 2024-10-25T14:25:20Z canonical: "docs.voiso.com/how-to-retrieve-cdrs" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.voiso.com/llms.txt > Use this file to discover all available pages before exploring further. # How to retrieve CDRs ## Overview Use the Call Detail Records (CDR) API to query your [interaction detail records](https://docs.voiso.com/docs/reporting-cdr) from your account. Apply various request parameters as filters to limit the number of records in the response. Please refer to the detailed API endpoint specification [here](/v1-api/apidocs/cdr). :::(Warning) (Important) You may only query CDRs for which access has been granted to you by your account privileges. Refer to [Security Access Groups](https://docs.voiso.com/docs/administration-security-access-groups). ::: ## How to retrieve values for certain filters To obtain values for certain CDR request filters, such as `queue_ids`, `agent_ids`, and so on, you can use the following APIs to get IDs and other details for these contact center objects: * [users](/v1-api/apidocs/users) * [deleted users](/v1-api/apidocs/deleted-users) * [teams](/v1-api/apidocs/teams) * [queues](/v1-api/apidocs/queues) * [wrap-up codes](/v1-api/apidocs/wrap-up-codes) Refer to the [Parameter Reference table](/v1-api/apidocs/how-to-retrieve-cdrs#parameter-reference), below, for more information. ## Request example The following is an example of a request that returns all interaction records for outbound calls from December 12, 2023 onwards. The response should include the first 1000 or fewer records on a single page: ```JSON { "method": "GET", "url": "https://cluster1.voiso.com/api/v2/cdr", "params": { "key": "a387aaf1f101fc...fe284aaf61", "page": "1", "per_page": "1000", "type": "outbound", "start_date": "2023-12-01" } } ``` ### Querying more than 10,000 records The CDR API returns up to 10,000 results per request. To obtain more than 10,000 results, you must make multiple requests, adding the `search_token` parameter to subsequent requests. If your first request returns 10,000 records, but additional records match the search criteria, the response includes the `search_token` parameter and value. For example: #### Response ```JSON { "records": [ …array of records… ], "total":176, "page":1, "search_token": "WzE2NjkwMTcyNDkwMTUsImNkcl9pdGVtI2MzNTY2ZTFiL" } ``` To continue searching the records from where you left off, enter your request again, adding the `search_token` parameter. For example: ```JSON { "method": "GET", "url": "https://cluster1.voiso.com/api/v2/cdr", "params": { "key": "a387aaf1f101fc...fe284aaf61", "page": "1", "per_page": "1000", "type": "outbound", "start_date": "2023-12-01", "search_token": "WzE2NjkwMTcyNDkwMTUsImNkcl9pdGVtI2MzNTY2ZTFiL } } ``` Repeat the search process, replacing the `search_token` value with the new value in the response until the response is `"search_token": null`. For example: ```JSON { "records":[], "total":310, "search_token":null } ``` ### Parameter reference The following parameters are supported by the CDR API. | Parameter Name | Description | Required | Type | Example | | --- | --- | --- | --- | --- | | key | The [API key of a specific user](/v1-api/apidocs/authentication#how-to-obtain-the-user_api_key). | Required | string | user_api_key | | search_token | Parameter should be used to query more than 10000 records. | Required | string | dkeouof13kjhk4HHH59 | | page | Indicates the current page number | Optional | integer (int32) | 1 | | per_page | Number of records per page | Optional | integer (int32) | 20 | | start_date | Include only records on or after this date. Must be in the 'YYYY-MM-DD' format (ISO 8601). | Optional | string | 2020-04-01 | | end_date | Include only records on or before this date. Must be in the 'YYYY-MM-DD' format (ISO 8601). | Optional | string | 2020-05-01 | | cli | The call line identity (CLI) calling number. A 'starting with' search of the ANI/From field. | Optional | string | 197 | | number | The called number. A 'starting with' search of the DNIS/To field. | Optional | string | 187 | | wildcard_cli | The call line identity (CLI) calling number. An 'includes' search of the ANI/From field. | Optional | string | 971231 | | wildcard_number | The called number. An 'includes' search of the DNIS/To field. | Optional | string | 7751 | | type | Direction and type of the interaction | Optional | type (custom schema) | - | | disposition | Retrieved call outcome | Optional | disposition_code (custom schema) | - | | queue_ids | Single or multiple queue IDs, separated by commas. These can be obtained with the `/api/v2/cdr/queues` method | Optional | string | 199, 201 | | agent_ids | Single or multiple agent IDs, separated by commas. These can be obtained with the `/api/v2/cdr/agents` method | Optional | string | 1,2,3 | | team_ids | Single or multiple agent team IDs, separated by commas. These can be obtained with the `/api/v2/cdr/teams` method | Optional | string | 3,4 | | wrapup_codes | Single or multiple wrap-up code IDs, separated by commas. These can be obtained with the `/api/v2/cdr/wrapup_codes` method | Optional | string | 0001, 1002 | | event | Standard call events | Optional | events (custom schema) | - | | end_reason | Standard call end reasons | Optional | end_reason (custom schema) | - | | campaign_ids | Single or multiple campaign IDs, separated by commas. These can be obtained with the `/api/v2/cdr/campaigns` method | Optional | string | 15, 13, 22 | | duration_from | Calls which have a duration longer than the specified value (in seconds) | Optional | integer (int32) | 1 | | duration_to | Calls which have a duration shorter than the specified value (in seconds) | Optional | integer (int32) | 10 | | dialing_time_from | Calls which have a dialing time longer than the specified value (in seconds) | Optional | integer (int32) | 1 | | dialing_time_to | Calls which have a dialing time shorter than the specified value (in seconds) | Optional | integer (int32) | 10 | | talk_time_from | Calls which have a talk time longer than the specified value (in seconds) | Optional | integer (int32) | 1 | | talk_time_to | Calls which have a talk time shorter than the specified value (in seconds) | Optional | integer (int32) | 10 | | hold_time_from | Calls which have a hold time longer than the specified value (in seconds) | Optional | integer (int32) | 1 | | hold_time_to | Calls which have a hold time shorter than the specified value (in seconds) | Optional | integer (int32) | 10 | | ivr_time_from | Calls which have a pre-queue (IVR) time longer than the specified value (in seconds) | Optional | integer (int32) | 1 | | ivr_time_to | Calls which have a pre-queue (IVR) time shorter than the specified value (in seconds) | Optional | integer (int32) | 10 | | queue_time_from | Calls which have a queue time longer than the specified value (in seconds) | Optional | integer (int32) | 1 | | queue_time_to | Calls which have a queue time shorter than the specified value (in seconds) | Optional | integer (int32) | 10 | | deleted_agent_ids | Single or multiple deleted (archived) agent IDs, separated by commas. These can be obtained with the `/api/v2/cdr/deleted_agents` method | Optional | string | 15, 16, 17 | | first_seen | Set to Required to get only new numbers that have never been dialed before | Optional | first_seen (custom schema) | - | | lead_source | Calls with a specified lead source type (available only for dialer campaigns with a specified lead source) | Optional | string | Google ADS | | start_datetime | Must be in this format: 'YYYY-MM-DD'T'HH:MM:SS'. | Optional | string | 2022-08-19T02:56:02 | | end_datetime | Must be in this format: 'YYYY-MM-DD'T'HH:MM:SS'. | Optional | string | 2022-08-19T02:56:02 | | uuid | UUID of the call. | Optional | string | a6c74840-574b-4e6e-baad-6b69bc38ccfc | | related_call_uuid | UUID of the parent call if the callback was requested from the queue. | Optional | string | 8d1371d2-e166-4677-b158-b1782ddd412d | | destination_name | The name of destination country. Valid for outbound calls only. | Optional | string | Germany - Other | With these parameters, you can make a GET request: ```JSON { "method": "GET", "url": "https://cluster1.voiso.com.voiso.com/api/v2/cdr", "params": { "key": "a387aaf1f101fc...fe284aaf61", "search_token": "dkeouof13kjhk4HHH59", "page": "1", "per_page": "20", "start_date": "2020-04-01", "end_date": "2020-05-01", "cli": "197", "number": "187", "wildcard_cli": "971231", "wildcard_number": "7751", "queue_ids": "199, 201", "agent_ids": "1,2,3", "team_ids": "3,4", "wrapup_codes": "0001, 1002", "campaign_ids": "15, 13, 22", "duration_from": "1", "duration_to": "10", "dialing_time_from": "1", "dialing_time_to": "10", "talk_time_from": "1", "talk_time_to": "10", "hold_time_from": "1", "hold_time_to": "10", "ivr_time_from": "1", "ivr_time_to": "10", "queue_time_from": "1", "queue_time_to": "10", "deleted_agent_ids": "15, 16, 17", "lead_source": "Google ADS", "start_datetime": "2022-08-19T02:56:02", "end_datetime": "2022-08-19T02:56:02", "uuid": "a6c74840-574b-4e6e-baad-6b69bc38ccfc", "related_call_uuid": "8d1371d2-e166-4677-b158-b1782ddd412d", "destination_name": "Germany - Other" } } ``` ## Response The following table describes the elements of the response. | Element | Description | Type | Notes | | --- | --- | --- | --- | | page | Indicates the current page number. | number | |, | total | Indicates the total number of pages in the response. | number | | | records | An array of interaction records from the Call Detail Records. | array | Refer to the **Records** table below. | | search_token | A token that is returned if the response contains more than 10,000 records. | string | Use the token in the next API request to skip the records that have already been returned. Refer to [Querying more than 10,000 records](/v1-api/apidocs/how-to-retrieve-cdrs#querying-more-than-10000-records) above. | ### Records The parameters returned for each record are determined by the interaction type, including voice, SMS, and digital interactions (refer to the Notes column). | Element | Description | Type | Notes | | --- | --- | --- | --- | | agent | The name of the user (agent or supervisor) who first handled the interaction. | string | | | from | The ANI of a voice interaction, the Sender ID of an SMS, or the name of a social media account for digital interactions. | string | | | disposition | The end-of-call status. | string | Refer to [Disposition codes](https://docs.voiso.com/docs/disposition-codes) for details. | | duration | The length of the interaction in hours, minutes, and seconds. | string | Format: hh:mm:ss | | queue | The inbound queue that distributed the call. | string | Inbound interactions only. | | to | The DNIS of a voice interaction, the name of the receiver of an SMS, or the name of a social media account for digital interactions. | string | | | timestamp | The date and time that the interaction ended. | string | The timestamp format is ISO 8601: yyyy-mm-ddThh:mm:ss.sss-hh:mm, where -/+hh:mm is the time zone offset from UTC. | | uuid | The unique identification code assigned to the interaction. | string | | | wrapup_code | The Wrap-up code assigned by the agent at the end of the interaction. | string | Refer to [Wrap-up codes](https://docs.voiso.com/docs/administration-wrap-up-codes) for details.| | type | The type of interaction. | string | Valid values include: inbound, outbound, dialer, click-to-call, hlr_ookup, outbound SMS, whatsapp, chat, instagram, facebook, telegram, viber, queue_callback, and scheduled_callback. | | agent_id | The identification number assigned by the system when the user was created. | number | These can be obtained with the `/api/v2/cdr/agents` method. | | cpc | The cost per call or cost to send a message. | number | In U.S. dollars. | | sid | The Sender ID for SMS interactions. | string | | | text | The body of the SMS. | string | | | related_call | The UUID of the interaction related to the SMS. | string | | | template | The name of the template used for the digital interaction or SMS. | string | | | num_segments | The number of segments required to contain the complete text of an SMS if the text of the message contains more than 160 characters. | number | Each segment is up to 160 characters in length. | | destination_name | The name associated with the recipient's phone number. | string | | | sla | Service Level Agreement parameters that indicate the time to complete each metric. | array | Refer to the **SLA** table below. | ### SLA For digital (chat-based) interactions, the following service level agreement array parameters are included in the `sla` parameter: | Element | Description | Type | Notes | | --- | --- | --- | --- | | time_to_first_response | The duration before an interaction assigned to an agent reaches the maximum allowed time for a first response. | string | Format: hh:mm:ss | | time_to_resolution | The maximum time that an agent has to archive an interaction. | string | Format: hh:mm:ss | | time_to_reply | The duration before an interaction assigned to an agent reaches the maximum allowed time for a reply to each text message from a contact. | string | Format: hh:mm:ss | ### Sample response: ```JSON { "records": [ { "agent": "Mike A", "from": "15557571011", "disposition": "answered", "duration": "00:01:19", "queue": null, "to": "31208112500", "timestamp": "2024-07-31T12:43:09.000-03:00", "uuid": "5d73e973-4103-48ac-84ad-4861155f86db", "wrapup_code": "0101", "type": "outbound", "agent_id": 56215, "cpc": 0.3972 }, // ... more records ... { "agent": "Chandra Agarwal", "from": "155535189249", "disposition": "answered", "duration": "00:00:30", "queue": null, "to": "155555554236", "timestamp": "2024-07-31T11:14:30.000-03:00", "uuid": "c61c6ebb-d216-4caa-927a-461c8c8cc705", "wrapup_code": "1007", "type": "click_to_call", "agent_id": 52715, "cpc": 0.0032 }, // ... more records ... { "agent": null, "from": "Guest", "disposition": "archived", "duration": "00:00:00", "to": "Olek's test", "timestamp": "2024-07-24T06:15:40.407-03:00", "uuid": "7a221595-6dcd-483a-b37f-65e12317756d", "wrapup_code": null, "type": "chat", "agent_id": null, "cpc": 0.0, "sla": { "time_to_first_response": "00:01:45", "time_to_resolution": "48:16:27", "time_to_reply": "00:00:23" }, "queue": null } ], "total": 2632, "page": 1, "search_token": "WzE2ODU1Mzg3MTg5ODUsIySjcl9pdGVtIzkzMjUyOGEyLTdhYYZtNGY3Zi04OWIwLWFhY2M4ZDc2OTk5YiJd" } ``` ## Related - [Users](/users.md) - [Deleted users](/deleted-users.md) - [Teams](/teams.md) - [Queues](/queues-1.md) - [Wrap-up codes](/wrap-up-codes-1.md)