Retrieve details of all calls

    This method lets you retrieve details of all completed calls. The maximum number of results that you can fetch with a single API call is 20.

    API Endpoint

    GET https://api.plivo.com/v1/Account/{auth_id}/Call/

    Arguments

    subaccount optional

    The ID of a subaccount, if you want to retrieve only calls made from a specific subaccount.

    call_direction optional

    The direction of the call, if you want to filter results by call direction.

    Allowed values: inbound, outbound

    from_number optional

    The number from which the calls were made, if you want to filter results by source number. You can filter the details by using the exact number or the prefix.

    to_number optional

    The destination number to which the calls were made, if you want to filter results by destination. You can filter the details by using the exact number or the prefix.

    parent_call_uuid optional

    Set this request parameter to the call UUID of an A leg to fetch all the B legs associated with it.

    bill_duration optional

    Filters calls by billed duration in seconds. The filter can be used in these five forms:

    • bill_duration: Input the exact value. For example, to retrieve calls that were exactly three minutes long, use bill_duration=180

    • bill_duration__gt: gt stands for greater than. To retrieve calls that were more than two hours long, use bill_duration__gt=7200

    • bill_duration__gte: gte stands for greater than or equal to. To retrieve calls that were two hours or more in duration, use bill_duration__gte=7200

    • bill_duration__lt: lt stands for less than. To retrieve calls that were less than seven minutes long, use bill_duration__lt=420

    • bill_duration__lte: lte stands for lesser than or equal to. To retrieve calls that were two hours or less in duration, use bill_duration__lte=7200

    end_time optional

    Filters calls by their completion time. The time format expected is YYYY-MM-DD HH:MM[:ss[.uuuuuu]]. The filter can be used in these five forms:

    • end_time: To get all calls that ended at 2021-03-21 11:47[:30], use end_time=2021-03-21 11:47[:30]

    • end_time__gt: gt stands for greater than. To get all calls that ended after 2021-03-21 11:47, use end_time__gt=2021-03-21 11:47

    • end_time__gte: gte stands for greater than or equal to. To get all calls that ended after or exactly at 2021-03-21 11:47[:30], use end_time__gte=2021-03-21 11:47[:30]

    • end_time__lt: lt stands for less than. To get all calls that ended before 2021-03-21 11:47, use end_time__lt=2021-03-21 11:47

    • end_time__lte: lte stands for less than or equal to. To get all calls that ended before or exactly at 2021-03-21 11:47[:30], use end_time__lte=2021-03-21 11:47[:30]

    Note: You can combine these filters to get calls that ended in a particular time range.

    When no end_time filter is specified, Plivo uses a default search window of the last 7 days.

    When only end_time__[gt|gte] or end_time__[lt|lte] is specified, Plivo uses a search window of 30 days from/to the specified end_time__[gt|gte] / end_time__[lt|lte].

    Timestamps need to be UTC timestamps.

    hangup_cause_code optional

    Retrieves calls that were hung up with a specific hangup cause. Refer to our list of hangup causes and sources.

    hangup_source optional

    Retrieves calls that were hung up by a specific hangup source. Refer to our list of hangup causes and sources.

    limit optional

    Limits the number of results retrieved. The maximum it can be set to is 20.

    Defaults to 20.

    offset optional

    Denotes the number of value items by which the results should be offset. For example, if the results contains 1,000 values and limit is set to 10 and offset is set to 705, then values 706 through 715 are displayed in the results. This parameter is also used for pagination of the results.

    stir_verification optional

    For outbound calls: Gives details about the attestation assigned to the call by Plivo

    For inbound calls: Gives details about the attestation received on the inbound call to your Plivo phone number.

    Allowed values:

    • Verified means the call is from a verified caller who has authorized access to the customer’s caller ID, and hence should be treated with confidence. Verified is equivalent to attestation level A.
    • Not Verified means that, for this call, either the caller is not verified, or it’s uncertain whether they have access to the caller ID used, or both. Not Verified means the call received attestation level B or C.
    • Not Applicable means STIR/SHAKEN doesn’t apply to this call, as would be the case if a call is not addressed to a US number or if it’s a cloud call (WebRTC or SIP).

    Read more about STIR/SHAKEN here.

    Returns

    Returns the call objects that match the filters specified in the request.

    Response

    HTTP Status Code: 200

    {
    "api_id": "8299d094-dc72-11e5-b56c-22000ae90795",
    "meta": {
    "limit": 20,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 4
    },
    "objects": [
    {
    "answer_time": "2020-07-26 15:45:02+05:30",
    "api_id": "06ae0f8f-dc72-11e5-b56c-22000ae90795",
    "bill_duration": 924,
    "billed_duration": 960,
    "call_direction": "outbound",
    "call_duration": 924,
    "call_uuid": "eba53b9e-8fbd-45c1-9444-696d2172fbc8",
    "end_time": "2020-07-26 15:45:14+05:30",
    "from_number": "+14158572518",
    "initiation_time": "2020-07-26 15:44:49+05:30",
    "parent_call_uuid": null,
    "stir_verification": "Verified",
    "resource_uri": "/v1/Account/MAXXXXXXXXXXXXXXXXXX/Call/eba53b9e-8fbd-45c1-9444-696d2172fbc8/",
    "to_number": "14153268174",
    "total_amount": "0.13600",
    "total_rate": "0.00850"
    },
    {
    "answer_time": "2020-07-26 16:45:02+05:30",
    "api_id": "06ae0f8f-dc72-11e5-b56c-22000ae90795",
    "bill_duration": 924,
    "billed_duration": 960,
    "call_direction": "outbound",
    "call_duration": 924,
    "call_uuid": "eba53b9e-8fbd-45c1-9444-696d2172fbc8",
    "end_time": "2020-07-26 16:45:14+05:30",
    "from_number": "+14158572518",
    "initiation_time": "2020-07-26 16:44:49+05:30",
    "parent_call_uuid": null,
    "stir_verification": "Not Verified",
    "resource_uri": "/v1/Account/MAXXXXXXXXXXXXXXXXXX/Call/eba53b9e-8fbd-45c1-9444-696d2172fbc8/",
    "to_number": "14153268174",
    "total_amount": "0.13600",
    "total_rate": "0.00850"
    }
    ]
    }
    

    Example Request

    1
    2
    3
    4
    5
    6
    7
    8
    
    import plivo
    
    client = plivo.RestClient('<auth_id>','<auth_token>')
    
    response = client.calls.list(
        limit=5,
        offset=0, )
    print(response)
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    
    #
    # Example for Call List
    #
    require 'rubygems'
    require 'plivo'
    
    include Plivo
    include Plivo::Exceptions
    
    api = RestClient.new("<auth_id>","<auth_token>")
    
    begin
      response = api.calls.list(
        limit: 5,
        offset: 0
      )
      puts response
    rescue PlivoRESTError => e
      puts 'Exception: ' + e.message
    end
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    
    // Example for Call list
    
    var plivo = require('plivo');
    
    (function main() {
        'use strict';
        
       // If auth id and auth token are not specified, Plivo will fetch them from the environment variables.
        var client = new plivo.Client("<auth_id>","<auth_token>");
        client.calls.list(
            {
                limit: 5,
                offset: 0,
            },
        ).then(function (response) {
            console.log(response);
        }, function (err) {
            console.error(err);
        });
    })();
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    
    <?php
    /**
     * Example for Call list
     */
    require 'vendor/autoload.php';
    use Plivo\RestClient;
    use Plivo\Exceptions\PlivoRestException;
    $client = new RestClient("<auth_id>","<auth_token>");
    
    try {
        $response = $client->calls->list(
            [
            	'limit' => 5,
            	'offset' => 2
            ]
        );
        print_r($response);
    }
    catch (PlivoRestException $ex) {
        print_r($ex);
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    
    package com.plivo.api.samples.call;
    
    import java.io.IOException;
    import com.plivo.api.Plivo;
    import com.plivo.api.exceptions.PlivoRestException;
    import com.plivo.api.models.call.Call;
    import com.plivo.api.models.base.ListResponse;
    
    /**
    * Example for Call list
    */
    class CallList {
        public static void main(String [] args) {
            Plivo.init("<auth_id>","<auth_token>");
            try {
                ListResponse<Call> response = Call.lister()
                    .limit(5)
                    .offset(0)
                    .list();
    
                System.out.println(response);
            } catch (PlivoRestException | IOException e) {
                e.printStackTrace();
            }
        }
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    
    /**
     * Example for Call List
     */
    using System;
    using System.Collections.Generic;
    using Plivo;
    using Plivo.Exception;
    
    namespace PlivoExamples
    {
        internal class Program
        {
            public static void Main(string[] args)
            {
                var api = new PlivoApi("<auth_id>","<auth_token>");
                try
                {
                    var response = api.Call.List(
                        limit:5,
                        offset:0
                    );
                    Console.WriteLine(response);
                }
                catch (PlivoRestException e)
                {
                    Console.WriteLine("Exception: " + e.Message);
                }
            }
        }
    }
    
    1
    2
    
    curl -i --user AUTH_ID:AUTH_TOKEN \
      https://api.plivo.com/v1/Account/{auth_id}/Call/
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    
    // Example for Call list
    package main
    
    import "fmt"
    import "github.com/plivo/plivo-go"
     
    func main() {
    	client, err := plivo.NewClient("<auth_id>","<auth_token>", &plivo.ClientOptions{})
    	if err != nil {
    		panic(err)
    	}
    	response, err := client.Calls.List(
    		plivo.CallListParams{
    			Limit: 5,
    			Offset: 0,
    		},
    	)
    	if err != nil {
    		panic(err)
    	}
    	fmt.Printf("Response: %#v\n", response)
    }