Account Report Resource

Overview

(new)

Public Beta

Voice Insights Reports API is currently offered as a Public Beta, exclusively available to Voice Insights Advanced Features customers. Information contained in this document is subject to change. Public Beta products aren't covered by a Twilio Service Level Agreement. Learn more in the Twilio Beta Product Support Help Center article.

An Account Report provides an overview of aggregated voice metrics and reports at the account level.

Account Report Properties

Encoding type:application/json

Schema

Property nameTypeRequiredPIIDescriptionChild properties

accountSidSID<AC>

Optional

Not PII

The unique SID identifier of the Account.

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

reportIdstring

Optional

Not PII

Report ID.

Example: voiceinsights_report_XXXXXXXXXXXXXXXXXXXXXXXXXX

statusenum<string>

Optional

Not PII

The status of the account level report.

Possible values:

createdrunningcompleted

requestMetaobject

Optional

Not PII

Time range and filters applied to the generated report.

Show requestMeta properties

reportobject

Optional

Not PII

Aggregated account-level metrics captured in the report.

Show report properties

urlstring<uri>

Optional

Not PII

The URL of this resource.

Filter object

Key	Accepted values
`call_state`	`completed`, `fail`, `busy`, `noanswer`, `canceled`
`call_direction`	`inbound`, `outbound`
`call_type`	`carrier`, `sip`, `trunking`, `client`, `whatsapp`
`twilio_regions`	One or more Twilio regions, for example `us1`, `ie1`, `sg1`
`caller_country_code`	ISO alpha-2 country codes for originating callers, for example `US`, `GB`, `IN`
`callee_country_code`	ISO alpha-2 country codes for destinations, for example `US`, `GB`, `IN`
`silent`	`"true"` or `"false` indicating whether the call was tagged as silent

Create a new Account Report

POST /v2/Voice/Reports

(information)

Info

A Voice Insights Report will be available for 5 days after it is created.

Request Body parameters

Encoding type:application/json

Schema

Property nameTypeRequiredPIIDescriptionChild properties

timeRangeobject

Optional

Not PII

Optional start and end date time for the report window. Defaults to the most recent 7 days when omitted.

Show timeRange properties

filtersarray[object]

Optional

Not PII

Optional filters applied to the report (for example call direction or carrier).

Show filters properties

Create a Account Level Report

The recent 7 days report can be created without any parameters.

Create a default Account Level Report

1curl -X POST "https://insights.twilio.com/v2/Voice/Reports" \
2  -H "Content-Type: application/json; charset=utf-8" \
3  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN"

Output

1{
2  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3  "report_id": "voiceinsights_report_XXXXXXXXXXXXXXXXXXXXXXXXXX",
4  "request_meta": {
5    "end_time": "2025-10-01T21:45:46Z",
6    "filters": [],
7    "start_time": "2025-09-24T21:45:46Z"
8  },
9  "status": "created",
10  "url": "https://insights.twilio.com/v2/Voice/Reports/voiceinsights_report_XXXXXXXXXXXXXXXXXXXXXXXXXX"
11}

Create an Account Level Report with Date Range

You can create an account level report with a specific date range by providing the time_range parameter.

Create an Account Level Report with Date Range

1curl -X POST "https://insights.twilio.com/v2/Voice/Reports" \
2  -H "Content-Type: application/json; charset=utf-8" \
3  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
4  -d $'{
5  "time_range": {
6    "start_datetime": "2025-09-24T00:00:00Z",
7    "end_datetime": "2025-10-01T00:00:00Z"
8  }
9}'

Output

1{
2  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3  "report_id": "voiceinsights_report_XXXXXXXXXXXXXXXXXXXXXXXXXX",
4  "request_meta": {
5    "end_time": "2025-10-01T00:00:00Z",
6    "filters": [],
7    "start_time": "2025-09-24T00:00:00Z"
8  },
9  "status": "created",
10  "url": "https://insights.twilio.com/v2/Voice/Reports/voiceinsights_report_XXXXXXXXXXXXXXXXXXXXXXXXXX"
11}

Create an Account Level Report with Filters

You can create an account level report with filters by providing the filters parameter.

Create an Account Level Report with Filters

1curl -X POST "https://insights.twilio.com/v2/Voice/Reports" \
2  -H "Content-Type: application/json; charset=utf-8" \
3  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
4  -d $'{
5  "time_range": {
6    "start_datetime": "2025-09-24T00:00:00Z",
7    "end_datetime": "2025-10-01T00:00:00Z"
8  },
9  "filters": [
10    {
11      "key": "call_type",
12      "values": ["carrier", "client"]
13    },
14    {
15      "key": "caller_country_code",
16      "values": ["US"]
17    }
18  ]
19}'

Output

1{
2  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3  "report_id": "voiceinsights_report_XXXXXXXXXXXXXXXXXXXXXXXXXX",
4  "request_meta": {
5    "end_time": "2025-10-01T00:00:00Z",
6    "filters": [
7      {
8        "key": "caller_country_code",
9        "values": [
10          "US"
11        ]
12      },
13      {
14        "key": "call_type",
15        "values": [
16          "carrier",
17          "client"
18        ]
19      }
20    ],
21    "start_time": "2025-09-24T00:00:00Z"
22  },
23  "status": "created",
24  "url": "https://insights.twilio.com/v2/Voice/Reports/voiceinsights_report_XXXXXXXXXXXXXXXXXXXXXXXXXX"
25}

Fetch an Account Report Resource

GET /v2/Voice/Reports/{reportId}

Path parameters

Property nameTypeRequiredPIIDescriptionChild properties

reportIdstring

required

Not PII

A unique request id

Fetch the Account Level Report

1curl -X GET "https://insights.twilio.com/v2/Voice/Reports/voiceinsights_report_XXXXXXXXXXXXXXXXXXXXXXXXXX" \
2  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN"

Output

1{
2  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3  "report": {
4    "total_calls": 42069,
5    "call_deliverability_score": 98.52,
6    "call_answer_score": 95.22,
7    "call_direction": {
8      "outbound": 42069,
9      "inbound": 42069
10    },
11    "call_type": {
12      "carrier": 42069,
13      "sip": 42069,
14      "trunking": 42069,
15      "client": 1112,
16      "whatsapp": 1112
17    },
18    "aloc": 128.4,
19    "twilio_edge_location": {
20      "ashburn": 84,
21      "umatilla": 16
22    },
23    "caller_country_code": {
24      "US": 100,
25      "MX": 10,
26      "BR": 5,
27      "CO": 2
28    },
29    "callee_country_code": {
30      "US": 100,
31      "MX": 10,
32      "BR": 5,
33      "CO": 2
34    },
35    "average_queue_time_ms": 15.04,
36    "silent_calls_percentage": 22.02,
37    "network_issues": {
38      "sdk": {
39        "ice_failures_percentage": 1.3,
40        "high_latency_percentage": 5.5,
41        "high_packet_loss_percentage": 4.3,
42        "high_jitter_percentage": 1.2
43      },
44      "twilio_gateway": {
45        "high_latency_percentage": 5.1,
46        "high_packet_loss_percentage": 4.4,
47        "high_jitter_percentage": 1.3
48      }
49    },
50    "KYT ": {
51      "outbound_carrier_calling": {
52        "blocked_calls_by_carrier_percentage": [
53          {
54            "country": "US",
55            "values": [
56              {
57                "carrier": "att",
58                "total_calls": 54118,
59                "blocked_calls": 6531,
60                "blocked_calls_percentage": 12.07
61              },
62              {
63                "carrier": "tmobile",
64                "total_calls": 54118,
65                "blocked_calls": 6531,
66                "blocked_calls_percentage": 12.07
67              },
68              {
69                "carrier": "verizon",
70                "total_calls": 54118,
71                "blocked_calls": 6531,
72                "blocked_calls_percentage": 12.07
73              }
74            ]
75          }
76        ],
77        "short_duration_calls_percentage": 22.07,
78        "long_duration_calls_percentage": 22.07,
79        "potential_robocalls_percentage": 2.02,
80        "branded_calling": {
81          "total_branded_calls": 54118,
82          "percent_branded_calls": 47.64,
83          "answer_rate": 95.6,
84          "human_answer_rate": 88.75,
85          "engagement_rate": 86.51,
86          "by_use_case": [
87            {
88              "use_case": "Customer Support",
89              "enabled_phonenumbers": 1880,
90              "total_calls": 54118,
91              "answer_rate": 95.6,
92              "human_answer_rate": 88.75,
93              "engagement_rate": 86.51
94            }
95          ]
96        },
97        "voice_integrity": {
98          "enabled_calls": 54118,
99          "enabled_percentage": 47.64,
100          "calls_per_bundle": [
101            {
102              "bundle_sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
103              "enabled_phonenumbers": 1880,
104              "total_calls": 54118,
105              "answer_rate": 95.6,
106              "human_answer_rate": 88.75
107            }
108          ]
109        },
110        "stir_shaken": {
111          "call_count": {
112            "stsh_a": 10069,
113            "stsh_b": 10,
114            "stsh_c": 1069
115          },
116          "percentage": {
117            "stsh_a": 89.63,
118            "stsh_b": 0.01,
119            "stsh_c": 0.06
120          },
121          "answer_rate": {
122            "stsh_a": 89.63,
123            "stsh_b": 100.0,
124            "stsh_c": 0.0
125          }
126        }
127      }
128    },
129    "answering_machine_detection": {
130      "total_calls": 136069,
131      "answered_by_human_percentage": 67.59,
132      "answered_by_machine_percentage": 31.39
133    }
134  },
135  "report_id": "voiceinsights_report_XXXXXXXXXXXXXXXXXXXXXXXXXX",
136  "request_meta": {
137    "end_time": "2025-10-01T00:00:00Z",
138    "filters": [
139      {
140        "key": "call_type",
141        "values": [
142          "carrier",
143          "client"
144        ]
145      },
146      {
147        "key": "caller_country_code",
148        "values": [
149          "US"
150        ]
151      }
152    ],
153    "start_time": "2025-09-24T00:00:00Z"
154  },
155  "status": "completed",
156  "url": "https://insights.twilio.com/v2/Voice/Reports/voiceinsights_report_XXXXXXXXXXXXXXXXXXXXXXXXXX"
157}