REST API: Calls

A Call instance resource represents a connection between a telephone and Twilio. This may be inbound, when a person calls your application, or outbound, when your application initiates the call, either via the REST API (see Making Calls) or during a call via the TwiML <Dial> verb. The Calls list resource represents the set of phone calls made to and from an account.

Call Instance Resource

Resource URI

/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}

Resource Properties

A Call instance resource is represented by the following properties:

Property Description
Sid A 34 character string that uniquely identifies this resource.
ParentCallSid A 34 character string that uniquely identifies the call that created this leg.
DateCreated The date that this resource was created, given as GMT in RFC 2822 format.
DateUpdated The date that this resource was last updated, given as GMT in RFC 2822 format.
AccountSid The unique id of the Account responsible for creating this call.
To The phone number that received this call. e.g., +16175551212 (E.164 format)
From The phone number that made this call. e.g., +16175551212 (E.164 format)
PhoneNumberSid If the call was inbound, this is the Sid of the IncomingPhoneNumber that received the call. If the call was outbound, it is the Sid of the OutgoingCallerId from which the call was placed.
Status A string representing the status of the call. May be queued, ringing, in-progress, completed, failed, busy or no-answer.
StartTime The start time of the call, given as GMT in RFC 2822 format. Empty if the call has not yet been dialed.
EndTime The end time of the call, given as GMT in RFC 2822 format. Empty if the call did not complete successfully.
Duration The length of the call in seconds. This value is empty for busy, failed, unanswered or ongoing calls.
Price The charge for this call in USD. Populated after the call is completed. May not be immediately available.
Direction A string describing the direction of the call. inbound for inbound calls, outbound-api for calls initiated via the REST API or outbound-dial for calls initiated by a <Dial> verb.
AnsweredBy If this call was initiated with answering machine detection, either human or machine. Empty otherwise.
ForwardedFrom If this call was an incoming call forwarded from another number, the forwarding phone number (depends on carrier supporting forwarding). Empty otherwise.
CallerName If this call was an incoming call from a phone number with Caller ID Lookup enabled, the caller's name. Empty otherwise.
Uri The URI for this resource, relative to https://api.twilio.com

HTTP GET

Returns the single Call resource identified by {CallSid}.

Example
Try it now

  • GET /2010-04-01/Accounts/AC5ef87.../Calls/CA42ed11f93dc08b952027ffbc406d0868 

    <TwilioResponse>
    <Call>
        <Sid>CAe1644a7eed5088b159577c5802d8be38</Sid>
        <DateCreated>Tue, 10 Aug 2010 08:02:17 +0000</DateCreated>
        <DateUpdated>Tue, 10 Aug 2010 08:02:47 +0000</DateUpdated>
        <ParentCallSid/>
        <AccountSid>AC5ef872f6da5a21de157d80997a64bd33</AccountSid>
        <To>+14153855708</To>
        <From>+14158141819</From>
        <PhoneNumberSid></PhoneNumberSid>
        <Status>completed</Status>
        <StartTime>Tue, 10 Aug 2010 08:02:31 +0000</StartTime>
        <EndTime>Tue, 10 Aug 2010 08:02:47 +0000</EndTime>
        <Duration>16</Duration>
        <Price>-0.03000</Price>
        <Direction>outbound-api</Direction>
        <AnsweredBy/>
        <ApiVersion>2008-08-01</ApiVersion>
        <ForwardedFrom/>
        <CallerName/>
        <Uri>/2010-04-01/Accounts/AC5ef872f6da5a21de157d80997a64bd33/Calls/CAe1644a7eed5088b159577c5802d8be38</Uri>
        <SubresourceUris>
            <Notifications>/2010-04-01/Accounts/AC5ef872f6da5a21de157d80997a64bd33/Calls/CAe1644a7eed5088b159577c5802d8be38/Notifications</Notifications>
            <Recordings>/2010-04-01/Accounts/AC5ef872f6da5a21de157d80997a64bd33/Calls/CAe1644a7eed5088b159577c5802d8be38/Recordings</Recordings>
        </SubresourceUris>
    </Call>
</TwilioResponse>

HTTP POST

Initiates a call redirect or terminates a call. See Modifying Live Calls for details.

HTTP PUT

Not supported

HTTP DELETE

Not supported

Call Instance Subresources

Each Call instance resource supports a few subresources for your convenience.

Recordings List Subresource

/2010-04-01/Accounts/{YourAccountSid}/Calls/{CallSid}/Recordings

Represents a list of recordings generated during the call identified by {CallSid}. See the Recordings section for resource properties and response formats.

Notifications List Subresource

/2010-04-01/Accounts/{YourAccountSid}/Calls/{CallSid}/Notifications

Represents a list of notifications generated during the call identified by {CallSid}. See the Notifications section for resource properties and response formats.

Calls List Resource

Resource URI

/2010-04-01/Accounts/{AccountSid}/Calls

HTTP GET

Returns a list of phone calls made to and from the account identified by {AccountSid}. The list includes paging information and is sorted by DateUpdated with most-recent calls first.

List Filters

The following GET query string parameters allow you to limit the list returned. Note, parameters are case-sensitive:

Parameter Description
To Only show calls to this phone number.
From Only show calls from this phone number.
Status Only show calls currently in this status. May be queued, ringing, in-progress, completed, failed, busy, or no-answer.
StartTime Only show calls that started on this date, given as YYYY-MM-DD. Also supports inequalities, such as StartTime<=YYYY-MM-DD for calls that started at or before midnight on a date, and StartTime>=YYYY-MM-DD for calls that started at or after midnight on a date.
ParentCallSid Only show calls spawned by the call with this Sid.
Example 1

Just grab the whole list.

Try it now

  • GET /2010-04-01/Accounts/AC5ef877a5fe4238be081ea6f3c44186f3/Calls 

    <TwilioResponse>
    <Calls page="0" numpages="3" pagesize="50" total="147" start="0" end="49" uri="/2010-04-01/Accounts/AC5ef877a5fe4238be081ea6f3c44186f3/Calls" firstpageuri="/2010-04-01/Accounts/AC5ef877a5fe4238be081ea6f3c44186f3/Calls?Page=0&amp;PageSize=50" previouspageuri="" nextpageuri="/2010-04-01/Accounts/AC5ef877a5fe4238be081ea6f3c44186f3/Calls?Page=1&amp;PageSize=50" lastpageuri="/2010-04-01/Accounts/AC5ef877a5fe4238be081ea6f3c44186f3/Calls?Page=2&amp;PageSize=50">
        <Call>
            <Sid>CA92d4405c9237c4ea04b56cbda88e128c</Sid>
            <DateCreated>Fri, 13 Aug 2010 01:16:22 +0000</DateCreated>
            <DateUpdated>Fri, 13 Aug 2010 01:16:22 +0000</DateUpdated>
            <ParentCallSid/>
            <AccountSid>AC5ef877a5fe4238be081ea6f3c44186f3</AccountSid>
            <To>+15304551166</To>
            <From>+15105555555</From>
            <PhoneNumberSid>PNe2d8e63b37f46f2adb16f228afdb9058</PhoneNumberSid>
            <Status>queued</Status>
            <StartTime>Thu, 12 Aug 2010 01:37:05 +0000</StartTime>
            <EndTime>Thu, 12 Aug 2010 01:37:40 +0000</EndTime>
            <Duration/>
            <Price/>
            <Direction>outbound-api</Direction>
            <AnsweredBy/>
            <ApiVersion>2010-04-01</ApiVersion>
            <ForwardedFrom/>
            <CallerName/>
            <Uri>/2010-04-01/Accounts/AC5ef877a5fe4238be081ea6f3c44186f3/Calls/CA92d4405c9237c4ea04b56cbda88e128c</Uri>
            <SubresourceUris>
                <Notifications>/2010-04-01/Accounts/AC5ef877a5fe4238be081ea6f3c44186f3/Calls/CA92d4405c9237c4ea04b56cbda88e128c/Notifications</Notifications>
                <Recordings>/2010-04-01/Accounts/AC5ef877a5fe4238be081ea6f3c44186f3/Calls/CA92d4405c9237c4ea04b56cbda88e128c/Recordings</Recordings>
            </SubresourceUris>
        </Call>
        ...
    </Calls>
<TwilioResponse>
Example 2

Only show completed calls started on Jul 06th, 2009.

GET /2010-04-01/Accounts/AC5ef87.../Calls?Status=completed&StartTime=2009-07-06

Example 3

Only show completed calls started on or after midnight Jul 06th, 2009.

GET /2010-04-01/Accounts/AC5ef87.../Calls?Status=completed&StartTime>=2009-07-06

Example 4

Only show completed calls started between midnight Jul 04th, 2009 and midnight Jul 06th, 2009.

GET /2010-04-01/Accounts/AC5ef87.../Calls?Status=in-progress&StartTime>=2009-07-04&StartTime<=2009-07-06

Example 5

Did you know you can append a '.csv' extension to any resource URI to get a Comma Separated Values representation? This is especially useful for call logs. Try this:

GET /2010-04-01/Accounts/AC5ef87.../Calls.csv

Read the Tips & Tricks Section for more information about alternate representations, including CSV.

Example 6

Only show busy calls that were made with the specified 'To' number (in E.164 format).

GET /2010-04-01/Accounts/AC5ef87.../Calls?Status=busy&To=+15558675309

HTTP POST

Initiates a new phone call. See Making Calls for details.

HTTP PUT

Not supported

HTTP DELETE

Not supported