Skip to contentSkip to navigationSkip to topbar
Twilio Docs
On this page

Call Metric Resource

A Call Metric is an object representing

  • a set of quantitative measurements and
  • meta data

related to the quality of a voice call.

Using the Call Metrics Resource, you can read a list of Call Metrics for a specified voice call.

(warning)

Warning

Voice Insights Advanced Features must be active to use this API Resource.

(information)

Info

Metrics are typically available via the API within 90 seconds of call completion.

Call Metric properties

call-metric-properties page anchor

The following table details the properties of a single Call Metric sample instance.

Property nameTypeRequiredDescriptionChild properties
timestampstring

Optional

Not PII

Timestamp of metric sample. Samples are taken every 10 seconds and contain the metrics for the previous 10 seconds.

callSidSID<CA>

Optional

Not PII

The unique SID identifier of the Call.

Pattern: ^CA[0-9a-fA-F]{32}$Min length: 34Max length: 34
accountSidSID<AC>

Optional

Not PII

The unique SID identifier of the Account.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
edgeenum<string>

Optional

Not PII

The Twilio media edge this Metric was captured on. One of unknown_edge, carrier_edge, sip_edge, sdk_edge or client_edge.

Possible values:
unknown_edgecarrier_edgesip_edgesdk_edgeclient_edge
directionenum<string>

Optional

Not PII

The Direction of the media stream from the perspective of the Twilio media edge. One of unknown, inbound, outbound or both.

Possible values:
unknowninboundoutboundboth
carrierEdgeobject

Optional

Not PII

Contains metrics and properties for the Twilio media gateway of a PSTN call.

sipEdgeobject

Optional

Not PII

Contains metrics and properties for the Twilio media gateway of a SIP Interface or Trunking call.

sdkEdgeobject

Optional

Not PII

Contains metrics and properties for the SDK sensor library for Client calls.

clientEdgeobject

Optional

Not PII

Contains metrics and properties for the Twilio media gateway of a Client call.

Edge Metrics and properties

edge-metrics-and-properties page anchor

Metric samples from these edges contain the following properties:

PropertyDescription
codecRTP profile number of the detected codec
codec_nameName of the detected codec
cumulativeCumulative jitter (max/avg), packets lost, and packet count for the stream received at this edge
intervalsdk_edge: audio in/out, jitter, packet loss, rtt, and packet loss percentage for the sampling interval. _All other edge_s: packets received, packets lost, and packet loss percentage.
metadataTwilio media region of the selected edge, Twilio and endpoint IP media IP addresses

Read multiple Call Metric resources

read-multiple-call-metric-resources page anchor

GET https://insights.twilio.com/v1/Voice/{CallSid}/Metrics

Use this action to retrieve a list of Call Metrics for the specified voice call.

You can use the optional edge parameter to filter the list by media edge. See Understanding Twilio Media Edges for more information.

If no edge parameter is provided, the resulting list will depend on the call type:

Call TypeDefault EdgeAdditional Edge
Carriercarrier_edgeN/A
SIPsip_edgeN/A
Clientsdk_edgeclient_edge
Trunking Originatingcarrier_edgesip_edge
Trunking Terminatingsip_edgecarrier_edge

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
callSidSID<CA>
required
Not PII

The unique SID identifier of the Call.

Pattern: ^CA[0-9a-fA-F]{32}$Min length: 34Max length: 34

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
edgeenum<string>

Optional

Not PII

The Edge of this Metric. One of unknown_edge, carrier_edge, sip_edge, sdk_edge or client_edge.

Possible values:
unknown_edgecarrier_edgesip_edgesdk_edgeclient_edge
directionenum<string>

Optional

Not PII

The Direction of this Metric. One of unknown, inbound, outbound or both.

Possible values:
unknowninboundoutboundboth
pageSizeinteger<int64>

Optional

Not PII

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000
pageinteger

Optional

Not PII

The page index. This value is simply for client state.

Minimum: 0
pageTokenstring

Optional

Not PII

The page token. This is provided by the API.

Read multiple Call Metrics for a CallLink to code sample: Read multiple Call Metrics for a Call
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function listMetric() {

11
  const metrics = await client.insights.v1

12
    .calls("CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .metrics.list({ limit: 20 });

14


15
  metrics.forEach((m) => console.log(m.timestamp));

16
}

17


18
listMetric();

Response

1
{

2
  "meta": {

3
    "page": 10,

4
    "page_size": 5,

5
    "first_page_url": "https://insights.twilio.com/v1/Voice/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Metrics?Direction=both&Edge=sdk_edge&PageSize=5&Page=0",

6
    "previous_page_url": "https://insights.twilio.com/v1/Voice/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Metrics?Direction=both&Edge=sdk_edge&PageSize=5&Page=9&PageToken=PT10",

7
    "next_page_url": null,

8
    "key": "metrics",

9
    "url": "https://insights.twilio.com/v1/Voice/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Metrics?Direction=both&Edge=sdk_edge&PageSize=5&Page=10"

10
  },

11
  "metrics": [

12
    {

13
      "timestamp": "2019-10-07T22:32:06Z",

14
      "call_sid": "CA7569efe0253644fa4a88aa97beca3310",

15
      "account_sid": "AC998c10b68cbfda9f67277f7d8f4439c9",

16
      "edge": "sdk_edge",

17
      "direction": "both",

18
      "sdk_edge": {

19
        "interval": {

20
          "packets_received": 50,

21
          "packets_lost": 0,

22
          "audio_in": {

23
            "value": 81

24
          },

25
          "audio_out": {

26
            "value": 5237

27
          },

28
          "jitter": {

29
            "value": 9

30
          },

31
          "mos": {

32
            "value": 4.39

33
          },

34
          "rtt": {

35
            "value": 81

36
          }

37
        },

38
        "cumulative": {

39
          "bytes_received": 547788,

40
          "bytes_sent": 329425,

41
          "packets_received": 3900,

42
          "packets_lost": 0,

43
          "packets_sent": 3934

44
        }

45
      },

46
      "client_edge": null,

47
      "carrier_edge": null,

48
      "sip_edge": null

49
    }

50
  ]

51
}
Read multiple Call Metrics for a Call filtered by Media EdgeLink to code sample: Read multiple Call Metrics for a Call filtered by Media Edge
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function listMetric() {

11
  const metrics = await client.insights.v1

12
    .calls("CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .metrics.list({

14
      edge: "sdk_edge",

15
      limit: 20,

16
    });

17


18
  metrics.forEach((m) => console.log(m.timestamp));

19
}

20


21
listMetric();

Response

1
{

2
  "meta": {

3
    "page": 0,

4
    "page_size": 50,

5
    "first_page_url": "https://insights.twilio.com/v1/Voice/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Metrics?PageSize=50&Page=0",

6
    "previous_page_url": null,

7
    "next_page_url": null,

8
    "key": "metrics",

9
    "url": "https://insights.twilio.com/v1/Voice/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Metrics?PageSize=50&Page=0"

10
  },

11
  "metrics": [

12
    {

13
      "timestamp": "2019-10-07T22:32:06Z",

14
      "call_sid": "CA7569efe0253644fa4a88aa97beca3310",

15
      "account_sid": "AC998c10b68cbfda9f67277f7d8f4439c9",

16
      "edge": "sdk_edge",

17
      "direction": "both",

18
      "sdk_edge": {

19
        "interval": {

20
          "packets_received": 50,

21
          "packets_lost": 0,

22
          "audio_in": {

23
            "value": 81

24
          },

25
          "audio_out": {

26
            "value": 5237

27
          },

28
          "jitter": {

29
            "value": 9

30
          },

31
          "mos": {

32
            "value": 4.39

33
          },

34
          "rtt": {

35
            "value": 81

36
          }

37
        },

38
        "cumulative": {

39
          "bytes_received": 547788,

40
          "bytes_sent": 329425,

41
          "packets_received": 3900,

42
          "packets_lost": 0,

43
          "packets_sent": 3934

44
        }

45
      },

46
      "client_edge": null,

47
      "carrier_edge": null,

48
      "sip_edge": null

49
    }

50
  ]

51
}