To get details of calls in bulk (including Status, Price, etc.), you will need to make a HTTP GET request to

GET

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls

  • Replace <your_api_key> and <your_api_token> with the API key and token created by you.
  • Replace <your_sid> with your “Account sid”
  • Replace <subdomain> with the region of your account
    1. <subdomain> of Singapore cluster is @api.exotel.com
    2. <subdomain> of Mumbai cluster is @api.in.exotel.com

<your_api_key> , <your_api_token> and <your_sid> are available in the API settings page of your Exotel Dashboard

Description of request query parameters (filters):

Parameter Name Description
Sid

string; an alpha-numeric unique identifier of the call

One or multiple Call SIDs which are comma separated. Recommended limit of SIDs which should be passed together is 20 and maximum allowed limit is 100. If DateCreated is not set, it will only check for last 31 days by default. While querying Sid(s) older than 31 days, DateCreated filter needs to be provided.

 

Example:
/Calls?Sid=48d690c837bb0c755a1228dcb6911416,d7d9cefd9773dd746d8f1e029cdb1417
/Calls?Sid=48d690c837bb0c755a1228dcb6911416&DateCreated=gte:2019-01-01 00:00:00;lte:2019-01-31 23:59:59

DateCreated Date and time at which the Call resource was created in the Exotel system. Supported operators (gte and lte), for more info refer to filter operators section below. You can query call records only up to 6 months old and provide maximum date range of 1 month.

Default if not set: Last 31 days

Example:
/Calls?DateCreated=gte:2019-01-01 00:00:00;lte:2019-01-31 23:59:59
To Your customer's phone number. One or multiple To numbers can be provided (in E.164 format) which are comma separated. (max limit: 5)

Example:
/Calls?To=<number-1>
/Calls?To=<number-1>,<number-2>"
From The phone number that will be called first. One or multiple From numbers can be provided (in E.164 format) which are comma separated. (max limit: 5)

Example:
/Calls?From=<number-1>
/Calls?From=<number-1>,<number-2>,...
Status

Overall call status, which could be one of:

  • queued - The call is ready and waiting in line before going out
  • ringing - The call is currently in-flight
  • in-progress - The call was answered and is currently in progress
  • completed - The call was answered and has ended normally
  • failed - The call could not be completed as dialled, most likely because the phone number was non-existent
  • busy - The caller received a busy signal
  • no-answer - The call ended without being answered

Example:
/Calls?Status=completed
/Calls?Status=failed,no-answer,busy,canceled

Duration Call duration in seconds. Supported operators (gte, eq and lte), for more info refer to filter operators section below.

Example:
/Calls?Duration=gte:10s;lte:45s
/Calls?Duration=eq:30s
Price If present, this will be the amount (as per your billing currency) you have been charged for the call. Supported operators (gte, eq and lte), for more info refer to filter operators section below.

Example:
/Calls?Price=gte:0.10;lte:1.0
/Calls?Price=eq:0.300030
Direction
  • inbound
  • outbound-dial - Outbound calls from Exotel dashboard
  • outbound-api - All other Outbound calls (API, campaign etc.)

Example:
/Calls?Direction=inbound
/Calls?Direction=outbound-dial,inbound

PhoneNumber This represents the Virtual Number (ExoPhone) used for the call. One or multiple PhoneNumber(s) can be provided (in E.164 format) which are comma separated. (max limit: 5)

Example:
/Calls?PhoneNumber=<vn-1>
/Calls?PhoneNumber=<vn-1>,<vn-2>,...
PageSize This represents number of records visible in one page of the API response. Default: 50, Max: 100
SortBy This indicates in what order the Call records are sorted in the API response. By default records are sorted by DateCreated in descending order. However, you can override the same in following way for ascending order:

Example:
/Calls?SortBy=DateCreated:asc
Before Auto generated unique string returned in the PrevPageUri (under Metadata) to be used as query param when at least one record is returned in that page. The value of this field is a cursor which identifies a call record uniquely.
After Auto generated unique string returned in the NextPageUri (under Metadata) to be used as query param when at least one record is present in that page. The value of this field is a cursor which identifies a call record uniquely.

Filter Operators (Please note these operators are only applicable to certain query parameters as mentioned above)

Operator

Description

Examples

eq:

Equals

Return results where duration is exactly ten seconds:

Duration=eq:10s

Same can also be written as Duration=10s

gte:

Greater than or equal to

Return results where Duration is ten seconds or more:

Duration=gte:10s

lte:

Less than or equal to

Return results where Duration is ten seconds or less:

Duration=lte:10s

,

OR operator

OR operator (,) is used to select multiple values if any one of them matches

;

AND operator

AND operator (;) is used to select multiple values if all of them matches. Url encode ; to %3B while making the API request.

 

curl https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls
 
var request = require('request');

var options = {
    url: 'https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls'
};

function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
}

request(options, callback);
<?php
include('vendor/rmccue/requests/library/Requests.php');
Requests::register_autoloader();
$headers = array();
$response = Requests::get('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls', $headers);
import requests

requests.get('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls')
require 'net/http'
require 'uri'

uri = URI.parse("https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls")
response = Net::HTTP.get_response(uri)

# response.code
# response.body

HTTP Response:

  • On success, the HTTP response status code will be 200
  • the HTTP response body will contain an JSON/XML similar to the one below
{
    "Metadata": {
        "Total": 1027,
        "PageSize": 1,
        "FirstPageUri": "/v1/Accounts/<your_sid>/Calls.json?PageSize=2&DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&SortBy=DateCreated:desc",
        "PrevPageUri": "/v1/Accounts/<your_sid>/Calls.json?PageSize=2&DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&SortBy=DateCreated:desc&Before=MTU3Nzk4NjAwNixhZmQ4MGJhNzI1MzA5YmU2MjM0MTA2YjY5ZGVmMTQxMg==",
        "NextPageUri": "/v1/Accounts/<your_sid>/Calls.json?PageSize=2&DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&SortBy=DateCreated:desc&After=MTU3Nzk4NDQwNywwNmQ4ZmI0MDdlZWY5N2YxZmI0OTllNjZjOTI5MTQxMg=="
    },
    "Calls": [
        {
            "Sid": "b6cfaf5f5cef3ca0fc937749ef960e25",
            "ParentCallSid": "",
            "DateCreated": "2016-11-29 15:58:45",
            "DateUpdated": "2016-11-29 16:00:09",
            "AccountSid": "Exotel",
            "To": "0XXXXX20000",
            "From": "0XXXXX30240",
            "PhoneNumberSid": "0XXXXXX4890",
            "Status": "completed",
            "StartTime": "2016-11-29 15:59:10",
            "EndTime": "2016-11-29 15:59:27",
            "Duration": "17",
            "Price": "1.500",
            "Direction": "outbound-api",
            "AnsweredBy": "human",
            "ForwardedFrom": "",
            "CallerName": "",
            "Uri": "/v1/Accounts/<your_sid>/Calls/b6cfaf5f5cef3ca0fc937749ef960e25",
            "RecordingUrl": "https://s3-ap-southeast-1.amazonaws.com/exotelrecordings/<your_sid>/b6cfaf5f5cef3ca0fc937749ef960e25.mp3"
        }
    ]
}
<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
    <Metadata>
        <Total>1027</Total>
        <PageSize>1</PageSize>
        <FirstPageUri>/v1/Accounts/Exotel/Calls?PageSize=2&amp;DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&amp;SortBy=DateCreated:desc</FirstPageUri>
        <PrevPageUri>/v1/Accounts/Exotel/Calls?PageSize=2&amp;DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&amp;SortBy=DateCreated:desc&amp;Before=MTU3Nzk4NjAwNixhZmQ4MGJhNzI1MzA5YmU2MjM0MTA2YjY5ZGVmMTQxMg==</PrevPageUri>
        <NextPageUri>/v1/Accounts/Exotel/Calls?PageSize=2&amp;DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&amp;SortBy=DateCreated:desc&amp;After=MTU3Nzk4NDQwNywwNmQ4ZmI0MDdlZWY5N2YxZmI0OTllNjZjOTI5MTQxMg==</NextPageUri>
    </Metadata>
 <Call>
  <Sid>b6cfaf5f5cef3ca0fc937749ef960e25</Sid>
  <ParentCallSid></ParentCallSid>
  <DateCreated>2017-02-17 14:16:03</DateCreated>
  <DateUpdated>2017-02-17 14:17:32</DateUpdated>
  <AccountSid>Exotel</AccountSid>
  <To>0XXXXX20000</To>
  <From>0XXXXX30240</From>
  <PhoneNumberSid>0XXXXXX4890</PhoneNumberSid>
  <Status>completed</Status>
  <StartTime>2017-02-17 14:16:03</StartTime>
  <EndTime>2017-02-17 14:16:20</EndTime>
  <Duration>17</Duration>
  <Price>0.750</Price>
  <Direction>inbound</Direction>
  <AnsweredBy>human</AnsweredBy>
  <ForwardedFrom></ForwardedFrom>
  <CallerName></CallerName>
  <Uri>/v1/Accounts/<your_sid>/Calls/b6cfaf5f5cef3ca0fc937749ef960e25</Uri>
  <RecordingUrl>https://s3-ap-southeast-1.amazonaws.com/exotelrecordings/<your_sid>/b6cfaf5f5cef3ca0fc937749ef960e25.mp3</RecordingUrl>
 </Call>
</TwilioResponse>

Description of parameters under 'Metadata' object mentioned in the above response:

Parameter Name Type & Value
Total Number of call records matching the given query and filters at that point of time
PageSize This indicates the number of records on that page
FirstPageUri This indicates the URI of the first page as per the request. This can be used to to retrieve call records from the beginning of the page.
PrevPageUri This indicates the URI of the previous page as per the request. This can be used to to retrieve previous set of call records.
NextPageUri This indicates the URI of the next page as per the request. This can be used to to retrieve next set of call records.


Description of parameters under 'Calls' array object mentioned in the above response:

Parameter Name Type & Value
Sid string; an alpha-numeric unique identifier of the call
DateCreated Date and time at which the user initiated the API
DateUpdated Date and time at which the status of the call was last updated in our system
AccountSid Your account SID
To Your customer's phone number in E.164 format 
From The phone number that will be called first in E.164 format
PhoneNumber This is your ExoPhone/Exotel Virtual Number in E.164 format
PhoneNumberSid This is the SID (unique ID)of the ExoPhone/Exotel Virtual Number. It can be same as the ExoPhone number or UUID based on when your number was configured.
Status

Overall call status, which could be one of:

  • queued - The call is ready and waiting in line before going out
  • ringing - The call is currently in-flight
  • in-progress - The call was answered and is currently in progress
  • completed - The call was answered and has ended normally
  • failed - The call could not be completed as dialled, most likely because the phone number was non-existent
  • busy - The caller received a busy signal
  • no-answer - The call ended without being answered
StartTime Time in format YYYY-MM-DD HH:mm:ss; Date and time when the call request was initiated to the operator
EndTime Time in format YYYY-MM-DD HH:mm:ss; Date and time when the call was completed
Duration Call duration in seconds
Price Double; If present, this will be the amount (in INR or USD) you have been charged for the call
Direction
  • inbound
  • outbound-dial - Outbound calls from Exotel dashboard
  • outbound-api - All other Outbound calls (API, campaign etc.)
AnsweredBy human
Uri Uri is the path of the CallSid
RecordingUrl Link to the call recording

If additional information such as status of both the call legs are required, you will need to make an HTTP GET request as:

GET

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls?details=true

HTTP Response:

  • On success, the HTTP response status code will be 200
  • the HTTP body will contain an XML similar to the one below
{
    "Metadata": {
        "Total": 1027,
        "PageSize": 1,
        "FirstPageUri": "/v1/Accounts/<your_sid>/Calls.json?PageSize=2&DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&SortBy=DateCreated:desc&details=true",
        "PrevPageUri": "/v1/Accounts/<your_sid>/Calls.json?PageSize=2&DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&SortBy=DateCreated:desc&details=true&amp;Before=MTU3Nzk4NjAwNixhZmQ4MGJhNzI1MzA5YmU2MjM0MTA2YjY5ZGVmMTQxMg==",
        "NextPageUri": "/v1/Accounts/<your_sid>/Calls.json?PageSize=2&DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&SortBy=DateCreated:desc&details=true&After=MTU3Nzk4NDQwNywwNmQ4ZmI0MDdlZWY5N2YxZmI0OTllNjZjOTI5MTQxMg=="
    },
    "Calls": [
        {
            "Sid": "b6cfaf5f5cef3ca0fc937749ef960e25",
            "ParentCallSid": "",
            "DateCreated": "2016-11-29 15:58:45",
            "DateUpdated": "2016-11-29 16:00:09",
            "AccountSid": "Exotel",
            "To": "0XXXXX20000",
            "From": "0XXXXX30240",
            "PhoneNumberSid": "0XXXXXX4890",
            "Status": "completed",
            "StartTime": "2016-11-29 15:59:10",
            "EndTime": "2016-11-29 15:59:57",
            "Duration": "47",
            "Price": "1.500",
            "Direction": "outbound-api",
            "AnsweredBy": "human",
            "ForwardedFrom": "",
            "CallerName": "",
            "Uri": "/v1/Accounts/<your_sid>/Calls/b6cfaf5f5cef3ca0fc937749ef960e25",
            "RecordingUrl": "https://s3-ap-southeast-1.amazonaws.com/exotelrecordings/<your_sid>/b6cfaf5f5cef3ca0fc937749ef960e25.mp3",
            "Details": {
                "ConversationDuration": 33,
                "Legs": [
                    {
                        "Leg": {
                            "Id": 1,
                            "OnCallDuration": 43
                        }
                    },
                    {
                        "Leg": {
                            "Id": 2,
                            "OnCallDuration": 33
                        }
                    }
                ],
                "Leg1Status": "completed",
                "Leg2Status": "no-answer"
            }
        }
    ]
}
<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
    <Metadata>
        <Total>1027</Total>
        <PageSize>1</PageSize>
        <FirstPageUri>/v1/Accounts/Exotel/Calls?PageSize=100&amp;SortBy=DateCreated:desc&amp;Status=completed&amp;details=true&amp;NumbersMetadata=true</FirstPageUri>
        <PrevPageUri>/v1/Accounts/Exotel/Calls?PageSize=100&amp;SortBy=DateCreated:desc&amp;Status=completed&amp;details=true&amp;NumbersMetadata=true&amp;Before=MTU3ODUwMjgwMyxiNTM2MzgzNzZlZWMyYTUxNjVmZGVlZmU2OWQyMTQxOA==</PrevPageUri>
        <NextPageUri>/v1/Accounts/Exotel/Calls?PageSize=100&amp;SortBy=DateCreated:desc&amp;Status=completed&amp;details=true&amp;NumbersMetadata=true&amp;After=MTU3ODQ4NTE2OSwwNjYwMDJiOWE2MmZiN2IxMmE0YjljODAzNTZmMTQxOA==</NextPageUri>
    </Metadata>
    <Call>
        <Sid>b6cfaf5f5cef3ca0fc937749ef96d245</Sid>
        <ParentCallSid></ParentCallSid>
        <DateCreated>2016-11-29 15:58:45</DateCreated>
        <DateUpdated>2016-11-29 16:00:09</DateUpdated>
        <AccountSid>Exotel</AccountSid>
        <To>0XXXXX30240</To>
        <From>0XXXXX85175</From>
        <PhoneNumberSid>0XXXXXX4890</PhoneNumberSid>
        <Status>completed</Status>
        <StartTime>2016-11-29 15:59:10</StartTime>
        <EndTime>2016-11-29 15:59:27</EndTime>
        <Duration>17</Duration>
        <Price>1.500</Price>
        <Direction>outbound-api</Direction>
        <AnsweredBy>human</AnsweredBy>
        <ForwardedFrom></ForwardedFrom>
        <CallerName></CallerName>
        <Uri>/v1/Accounts/Exotel/Calls/b6cfaf5f5cef3ca0fc937749ef96d245</Uri>
        <RecordingUrl>https://s3-ap-southeast-1.amazonaws.com/exotelrecordings/Exotel/b6cfaf5f5cef3ca0fc937749ef96d245.mp3</RecordingUrl>
        <Details>
            <ConversationDuration>8</ConversationDuration>
            <Leg1Status>completed</Leg1Status>
            <Leg2Status>completed</Leg2Status>
            <Legs>
                <Leg>
                    <Id>1</Id>
                    <OnCallDuration>21</OnCallDuration>
                </Leg>
                <Leg>
                    <Id>2</Id>
                    <OnCallDuration>8</OnCallDuration>
                </Leg>
            </Legs>
        </Details>
    </Call>
</TwilioResponse>

Description of parameters under "Details" mentioned in the above response:

Parameter Name Value
ConversationDuration The duration for the From and To phone numbers on call in seconds
Leg1Status

Status of the first leg of the call. Can be one of

  • queued - The call is ready and waiting in line before going out
  • ringing - The call is currently in-flight
  • in-progress - The call was answered and is currently in progress
  • completed - The call was answered and has ended normally
  • busy - The caller received a busy signal
  • failed - The call could not be completed as dialled, most likely because the phone number was non-existent
  • no-answer - The call ended without being answered
  • canceled - The call was canceled while queued or ringing
Leg2Status

Status of the second leg of the call. Can be one of

  • completed - The call was answered and has ended normally
  • busy - The caller received a busy signal
  • no-answer - The call ended without being answered
  • failed - The call could not be completed as dialed, most likely because the phone number was non-existent
  • canceled - The call was canceled while queued or ringing
  • null (empty) - The call did not have a second leg
Legs

Status of individual legs of the call. Contains the following information (per leg) in an array:

  • Id - Indicates the leg. Can be 1 or 2.
  • OnCallDuration - Indicates the duration that this leg was on a call.

The following are few examples in which API can be requested depending on the use-case:

Calls filtered by DateCreated range with Leg-wise details and Page Size = 100

GET

https://<subdomain>/v1/Accounts/<your_sid>/Calls.json?DateCreated=gte:2019-12-03+00:00:00%3Blte:2019-12-04+00:00:00&details=true&PageSize=100

Get all Incoming calls received by an agent (To number) for a given date range

GET

https://<subdomain>/v1/Accounts/<your_sid>/Calls.json?DateCreated=gte:2019-12-03+00:00:00%3Blte:2019-12-04+00:00:00&To=%2B91xxxxxxxxxx

Calls with Duration greater than 10 seconds and less than 60 seconds

GET

https://<subdomain>/v1/Accounts/<your_sid>/Calls.json?DateCreated=gte:2019-12-03+00:00:00%3Blte:2019-12-04+00:00:00&Duration=gte:11s%3Blte:59s

Calls which are failed and having ExoPhone (Virtual Phone Number) as +91xxxxxxxxxx

GET

https://<subdomain>/v1/Accounts/<your_sid>/Calls.json?DateCreated=gte:2019-12-03+00:00:00%3Blte:2019-12-04+00:00:00&Status=failed&PhoneNumber=%2B91xxxxxxxxxx