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

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

Property nameTypePIIDescription

timestampstring

Not PII

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

call_sidSID<CA>

Not PII

The unique SID identifier of the Call.

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

account_sidSID<AC>

Not PII

The unique SID identifier of the Account.

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

edgeenum<string>

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>

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

carrier_edgeobject

Not PII

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

sip_edgeobject

Not PII

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

sdk_edgeobject

Not PII

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

client_edgeobject

Not PII

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

Edge Metrics and properties

Metric samples from these edges contain the following properties:

Property	Description
`codec`	RTP profile number of the detected codec
`codec_name`	Name of the detected codec
`cumulative`	Cumulative jitter (max/avg), packets lost, and packet count for the stream received at this edge
`interval`	`sdk_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.
`metadata`	Twilio media region of the selected edge, Twilio and endpoint IP media IP addresses

Read multiple Call Metric resources

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 Type	Default Edge	Additional Edge
Carrier	`carrier_edge`	N/A
SIP	`sip_edge`	N/A
Client	`sdk_edge`	`client_edge`
Trunking Originating	`carrier_edge`	`sip_edge`
Trunking Terminating	`sip_edge`	`carrier_edge`

Path parameters

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

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

PageSizeintegerOptional

Not PII

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

Minimum: 1Maximum: 1000

PageintegerOptional

Not PII

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

Minimum: 0

PageTokenstringOptional

Not PII

The page token. This is provided by the API.

Read multiple Call Metrics for a Call

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_18// Download the helper library from https://www.twilio.com/docs/node/install
_18const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_18
_18// Find your Account SID and Auth Token at twilio.com/console
_18// and set the environment variables. See http://twil.io/secure
_18const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18const authToken = process.env.TWILIO_AUTH_TOKEN;
_18const client = twilio(accountSid, authToken);
_18
_18async function listMetric() {
_18  const metrics = await client.insights.v1
_18    .calls("CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
_18    .metrics.list({ limit: 20 });
_18
_18  metrics.forEach((m) => console.log(m.timestamp));
_18}
_18
_18listMetric();

Output


_51{
_51  "meta": {
_51    "page": 10,
_51    "page_size": 5,
_51    "first_page_url": "https://insights.twilio.com/v1/Voice/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Metrics?Direction=both&Edge=sdk_edge&PageSize=5&Page=0",
_51    "previous_page_url": "https://insights.twilio.com/v1/Voice/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Metrics?Direction=both&Edge=sdk_edge&PageSize=5&Page=9&PageToken=DP10",
_51    "next_page_url": null,
_51    "key": "metrics",
_51    "url": "https://insights.twilio.com/v1/Voice/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Metrics?Direction=both&Edge=sdk_edge&PageSize=5&Page=10"
_51  },
_51  "metrics": [
_51    {
_51      "timestamp": "2019-10-07T22:32:06Z",
_51      "call_sid": "CA7569efe0253644fa4a88aa97beca3310",
_51      "account_sid": "AC998c10b68cbfda9f67277f7d8f4439c9",
_51      "edge": "sdk_edge",
_51      "direction": "both",
_51      "sdk_edge": {
_51        "interval": {
_51          "packets_received": 50,
_51          "packets_lost": 0,
_51          "audio_in": {
_51            "value": 81
_51          },
_51          "audio_out": {
_51            "value": 5237
_51          },
_51          "jitter": {
_51            "value": 9
_51          },
_51          "mos": {
_51            "value": 4.39
_51          },
_51          "rtt": {
_51            "value": 81
_51          }
_51        },
_51        "cumulative": {
_51          "bytes_received": 547788,
_51          "bytes_sent": 329425,
_51          "packets_received": 3900,
_51          "packets_lost": 0,
_51          "packets_sent": 3934
_51        }
_51      },
_51      "client_edge": null,
_51      "carrier_edge": null,
_51      "sip_edge": null
_51    }
_51  ]
_51}

Read multiple Call Metrics for a Call filtered by Media Edge

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_21// Download the helper library from https://www.twilio.com/docs/node/install
_21const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_21
_21// Find your Account SID and Auth Token at twilio.com/console
_21// and set the environment variables. See http://twil.io/secure
_21const accountSid = process.env.TWILIO_ACCOUNT_SID;
_21const authToken = process.env.TWILIO_AUTH_TOKEN;
_21const client = twilio(accountSid, authToken);
_21
_21async function listMetric() {
_21  const metrics = await client.insights.v1
_21    .calls("CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
_21    .metrics.list({
_21      edge: "sdk_edge",
_21      limit: 20,
_21    });
_21
_21  metrics.forEach((m) => console.log(m.timestamp));
_21}
_21
_21listMetric();

Output


_51{
_51  "meta": {
_51    "page": 0,
_51    "page_size": 50,
_51    "first_page_url": "https://insights.twilio.com/v1/Voice/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Metrics?PageSize=50&Page=0",
_51    "previous_page_url": null,
_51    "next_page_url": null,
_51    "key": "metrics",
_51    "url": "https://insights.twilio.com/v1/Voice/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Metrics?PageSize=50&Page=0"
_51  },
_51  "metrics": [
_51    {
_51      "timestamp": "2019-10-07T22:32:06Z",
_51      "call_sid": "CA7569efe0253644fa4a88aa97beca3310",
_51      "account_sid": "AC998c10b68cbfda9f67277f7d8f4439c9",
_51      "edge": "sdk_edge",
_51      "direction": "both",
_51      "sdk_edge": {
_51        "interval": {
_51          "packets_received": 50,
_51          "packets_lost": 0,
_51          "audio_in": {
_51            "value": 81
_51          },
_51          "audio_out": {
_51            "value": 5237
_51          },
_51          "jitter": {
_51            "value": 9
_51          },
_51          "mos": {
_51            "value": 4.39
_51          },
_51          "rtt": {
_51            "value": 81
_51          }
_51        },
_51        "cumulative": {
_51          "bytes_received": 547788,
_51          "bytes_sent": 329425,
_51          "packets_received": 3900,
_51          "packets_lost": 0,
_51          "packets_sent": 3934
_51        }
_51      },
_51      "client_edge": null,
_51      "carrier_edge": null,
_51      "sip_edge": null
_51    }
_51  ]
_51}