Retrieve call logs

Learn to retrieve call logs with Twilio Programmable Voice by sending a GET request to the Calls.json endpoint or fetching a specific call resource by SID. You can use this guide to monitor calls, view call metrics, inspect call history, and troubleshoot call issues.

See Related reference documentation to learn more about the Call resource used in this guide.

(information)

Info

You can see all incoming and outgoing calls, as well as message activity, by viewing a specific phone number in Twilio Console. In Twilio Console, go to Products & services > Numbers & senders, and select a phone number. In the legacy Console, open a phone number and choose the Calls Log or Messages Log tab.

Complete the prerequisites

Complete the Twilio prerequisites

Create a Twilio account.
In the Twilio Console, create a compliance profile, then buy a voice-enabled phone number.
In the legacy Console, buy a voice-enabled phone number. Only Messaging-enabled phone numbers need a compliance profile.

Complete the language prerequisites

Select your programming language and complete the prerequisites:

PythonNode.jsPHPC# or .NETJavaRuby

Install Python 3.3 or later.
Install Flask and the Twilio Python Helper Library. Using pip, run the following command:
pip install flask twilio
Install and set up ngrok.

Install Node.js 20 or later.
Install Express with body-parser, and the Twilio Node.js helper library:
npm install twilio express
Install and set up ngrok.

Install PHP 7.2 or later.
Install the Composer dependency manager globally.
Install the Twilio PHP Helper Library:
composer require twilio/sdk
Install and set up ngrok.

Install Ruby 2.6 or later.
Install Sinatra and the Twilio Ruby Helper Library:
gem install sinatra rackup puma twilio-ruby
Install and set up ngrok.

Get credentials and set as environment variables

Extract your credentials from your Twilio account then save these credentials as environment variables.

Twilio ConsoleLegacy Console

Go to the Twilio Console. The Let's get building page appears.
Click API keys and Auth tokens. The API keys & auth tokens page appears with the Auth Tokens tab selected.
Scroll to your Account SID.
Click the copy button next to your Account SID.
Run the following command, replacing YOUR_ACCOUNT_SID with your Account SID.
macOS TerminalWindows command linePowerShell
export TWILIO_ACCOUNT_SID=YOUR_ACCOUNT_SID
set TWILIO_ACCOUNT_SID=YOUR_ACCOUNT_SID
$Env:TWILIO_ACCOUNT_SID="YOUR_ACCOUNT_SID"
This command creates an environment variable on your development system for your account SID.
To display the Auth Token, click the eye button in the Primary auth token box.
Highlight and copy the Auth Token.
Run the following command, replacing YOUR_AUTH_TOKEN with your Authentication Token.
macOS TerminalWindows command linePowerShell
export TWILIO_AUTH_TOKEN=YOUR_AUTH_TOKEN
set TWILIO_AUTH_TOKEN=YOUR_AUTH_TOKEN
$Env:TWILIO_AUTH_TOKEN="YOUR_AUTH_TOKEN"
This command creates an environment variable on your development system for your auth token.

Retrieve call logs

You can use Twilio's REST API to retrieve logs about the phone calls to and from your Twilio account. If you just want to check a couple logs, however, you should try looking at the voice logs in your Twilio console first.

List all calls for Twilio account

To list all phone calls for your Twilio account, just call @client.calls.list().

PythonNode.jsPHPC# or .NETJavaRuby

Python only requires the Twilio Python helper library as noted in the prerequisites.

List All Calls Example

1# Download the helper library from https://www.twilio.com/docs/python/install
2import os
3from twilio.rest import Client
4
5# Find your Account SID and Auth Token at twilio.com/console
6# and set the environment variables. See http://twil.io/secure
7account_sid = os.environ["TWILIO_ACCOUNT_SID"]
8auth_token = os.environ["TWILIO_AUTH_TOKEN"]
9client = Client(account_sid, auth_token)
10
11calls = client.calls.list(limit=20)
12
13for record in calls:
14    print(record.end)

Beyond Express and the Twilio Node.js helper library as noted in the prerequisites, Node.js requires the body-parser middleware.

List All Calls Example

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listCall() {
11  const calls = await client.calls.list({ limit: 20 });
12
13  calls.forEach((c) => console.log(c.end));
14}
15
16listCall();

PHP only requires the Twilio PHP helper library as noted in the prerequisites.

List All Calls Example

1<?php
2
3// Update the path below to your autoload.php,
4// see https://getcomposer.org/doc/01-basic-usage.md
5require_once "/path/to/vendor/autoload.php";
6
7use Twilio\Rest\Client;
8
9// Find your Account SID and Auth Token at twilio.com/console
10// and set the environment variables. See http://twil.io/secure
11$sid = $_ENV["TWILIO_ACCOUNT_SID"];
12$token = $_ENV["TWILIO_AUTH_TOKEN"];
13$twilio = new Client($sid, $token);
14
15$calls = $twilio->calls->read([], 20);
16
17foreach ($calls as $record) {
18    print $record->end;
19}

C# requires the .NET 6 framework and the Twilio C# helper library as noted in the prerequisites.

List All Calls Example

1// Install the C# / .NET helper library from twilio.com/docs/csharp/install
2
3using System;
4using Twilio;
5using Twilio.Rest.Api.V2010.Account;
6using System.Threading.Tasks;
7
8class Program {
9    public static async Task Main(string[] args) {
10        // Find your Account SID and Auth Token at twilio.com/console
11        // and set the environment variables. See http://twil.io/secure
12        string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");
13        string authToken = Environment.GetEnvironmentVariable("TWILIO_AUTH_TOKEN");
14
15        TwilioClient.Init(accountSid, authToken);
16
17        var calls = await CallResource.ReadAsync(limit: 20);
18
19        foreach (var record in calls) {
20            Console.WriteLine(record.End);
21        }
22    }
23}

Java requires Gradle or Maven and the Twilio Java helper library as noted in the prerequisites.

List All Calls Example

1// Install the Java helper library from twilio.com/docs/java/install
2
3import com.twilio.Twilio;
4import com.twilio.rest.api.v2010.account.Call;
5import com.twilio.base.ResourceSet;
6
7public class Example {
8    // Find your Account SID and Auth Token at twilio.com/console
9    // and set the environment variables. See http://twil.io/secure
10    public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");
11    public static final String AUTH_TOKEN = System.getenv("TWILIO_AUTH_TOKEN");
12
13    public static void main(String[] args) {
14        Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
15        ResourceSet<Call> calls = Call.reader().limit(20).read();
16
17        for (Call record : calls) {
18            System.out.println(record.getEnd());
19        }
20    }
21}

Ruby requires Sinatra and the Twilio Ruby helper library as noted in the prerequisites.

List All Calls Example

1# Download the helper library from https://www.twilio.com/docs/ruby/install
2require 'twilio-ruby'
3
4# Find your Account SID and Auth Token at twilio.com/console
5# and set the environment variables. See http://twil.io/secure
6account_sid = ENV['TWILIO_ACCOUNT_SID']
7auth_token = ENV['TWILIO_AUTH_TOKEN']
8@client = Twilio::REST::Client.new(account_sid, auth_token)
9
10calls = @client
11        .api
12        .v2010
13        .calls
14        .list(limit: 20)
15
16calls.each do |record|
17   puts record.end
18end

View the response

1{
2  "calls": [
3    {
4      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5      "answered_by": "machine_start",
6      "api_version": "2010-04-01",
7      "caller_name": "callerid1",
8      "date_created": "Fri, 18 Oct 2019 17:00:00 +0000",
9      "date_updated": "Fri, 18 Oct 2019 17:01:00 +0000",
10      "direction": "outbound-api",
11      "duration": "4",
12      "end_time": "Fri, 18 Oct 2019 17:03:00 +0000",
13      "forwarded_from": "calledvia1",
14      "from": "+13051416799",
15      "from_formatted": "(305) 141-6799",
16      "group_sid": "GPdeadbeefdeadbeefdeadbeefdeadbeef",
17      "parent_call_sid": "CAdeadbeefdeadbeefdeadbeefdeadbeef",
18      "phone_number_sid": "PNdeadbeefdeadbeefdeadbeefdeadbeef",
19      "price": "-0.200",
20      "price_unit": "USD",
21      "sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
22      "start_time": "Fri, 18 Oct 2019 17:02:00 +0000",
23      "status": "completed",
24      "subresource_uris": {
25        "notifications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications.json",
26        "recordings": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings.json",
27        "payments": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Payments.json",
28        "events": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Events.json",
29        "siprec": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Siprec.json",
30        "streams": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams.json",
31        "transcriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions.json",
32        "user_defined_message_subscriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessageSubscriptions.json",
33        "user_defined_messages": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessages.json"
34      },
35      "to": "+13051913581",
36      "to_formatted": "(305) 191-3581",
37      "trunk_sid": "TKdeadbeefdeadbeefdeadbeefdeadbeef",
38      "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
39      "queue_time": "1000"
40    },
41    {
42      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
43      "answered_by": "human",
44      "api_version": "2010-04-01",
45      "caller_name": "callerid2",
46      "date_created": "Fri, 18 Oct 2019 16:00:00 +0000",
47      "date_updated": "Fri, 18 Oct 2019 16:01:00 +0000",
48      "direction": "inbound",
49      "duration": "3",
50      "end_time": "Fri, 18 Oct 2019 16:03:00 +0000",
51      "forwarded_from": "calledvia2",
52      "from": "+13051416798",
53      "from_formatted": "(305) 141-6798",
54      "group_sid": "GPdeadbeefdeadbeefdeadbeefdeadbeee",
55      "parent_call_sid": "CAdeadbeefdeadbeefdeadbeefdeadbeee",
56      "phone_number_sid": "PNdeadbeefdeadbeefdeadbeefdeadbeee",
57      "price": "-0.100",
58      "price_unit": "JPY",
59      "sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0",
60      "start_time": "Fri, 18 Oct 2019 16:02:00 +0000",
61      "status": "completed",
62      "subresource_uris": {
63        "notifications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0/Notifications.json",
64        "recordings": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0/Recordings.json",
65        "payments": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0/Payments.json",
66        "events": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0/Events.json",
67        "siprec": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0/Siprec.json",
68        "streams": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0/Streams.json",
69        "transcriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0/Transcriptions.json",
70        "user_defined_message_subscriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0/UserDefinedMessageSubscriptions.json",
71        "user_defined_messages": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0/UserDefinedMessages.json"
72      },
73      "to": "+13051913580",
74      "to_formatted": "(305) 191-3580",
75      "trunk_sid": "TKdeadbeefdeadbeefdeadbeefdeadbeef",
76      "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0.json",
77      "queue_time": "1000"
78    }
79  ],
80  "end": 1,
81  "first_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls.json?Status=completed&To=%2B123456789&From=%2B987654321&StartTime=2008-01-02&ParentCallSid=CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&EndTime=2009-01-02&PageSize=2&Page=0",
82  "next_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls.json?Status=completed&To=%2B123456789&From=%2B987654321&StartTime=2008-01-02&ParentCallSid=CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&EndTime=2009-01-02&PageSize=2&Page=1&PageToken=PACAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0",
83  "page": 0,
84  "page_size": 2,
85  "previous_page_uri": null,
86  "start": 0,
87  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls.json?Status=completed&To=%2B123456789&From=%2B987654321&StartTime=2008-01-02&ParentCallSid=CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&EndTime=2009-01-02&PageSize=2&Page=0"
88}

List all busy calls

You can also filter the list results. This example only returns phone calls to the phone number +15558675309 which had a call status of busy but you can filter on other call properties as well.

PythonNode.jsPHPC# or .NETJavaRuby

Python only requires the Twilio Python helper library as noted in the prerequisites.