Skip to content Skip to navigation Skip to topbar

Page tools

On this page

Looking for more inspiration?Visit the

Outbound Phone Number 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 Outbound Phone Number Report aggregates Voice Insights metrics for calls placed from a specific phone number handle.

Outbound Phone Number Report Properties

Encoding type:application/json

Schema

Property nameTypeRequiredPIIDescriptionChild properties

handlestring

Optional

PII MTL: 30 days

Outbound phone number handle represented in the report.

totalCallsinteger

Optional

Total number of outbound calls made during the report period.

callAnswerScorenumber<float>

Optional

Score (0-100) representing how often outbound calls were answered.

callsByDeviceTypeobject

Optional

Number of outbound calls placed per device type (voip, mobile, landline, unknown).

Example: {"voip":150,"mobile":300,"landline":100,"unknown":50}

Show callsByDeviceType properties

answerRateDeviceTypeobject

Optional

Answer rate per device type (voip, mobile, landline, unknown).

Example: {"voip":75,"mobile":80,"landline":70,"unknown":60}

Show answerRateDeviceType properties

callStatePercentageobject

Optional

Percentage of outbound calls by call state (completed, fail, busy, no-answer, canceled).

Show callStatePercentage properties

blockedCallsByCarrierarray[object]

Optional

Associated metrics for completed outbound calls which are blocked by respective downstream carriers. Currently only the US carriers such as ATT, T-Mobile and Verizon provide this information.

Show blockedCallsByCarrier properties

silentCallsPercentagenumber<float>

Optional

Percentage of calls with silence tags over total calls. A silent tag is indicative of a connectivity issue or muted audio.

shortDurationCallsPercentagenumber<float>

Optional

Percentage of completed outbound calls under 10 seconds; More than 15% is typically low trust measured.

longDurationCallsPercentagenumber<float>

Optional

Percentage of outbound calls lasting 60 seconds or longer.

potentialRobocallsPercentagenumber<float>

Optional

Percentage of completed outbound calls to unassigned or unallocated phone numbers.

answeringMachineDetectionobject

Optional

Associated answering machine detection enabled calls.

Show answeringMachineDetection properties

Create an Outbound Phone Number Report

POST /v2/Voice/Reports/PhoneNumbers/Outbound

(information)

Info

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

Request body Parameter

Encoding type:application/json

Schema

Property nameTypeRequiredPIIDescriptionChild properties

timeRangeobject

Optional

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

Show timeRange properties

sizeinteger

Optional

Maximum number of phone number handles to return in the report.

Default: 1000Minimum: 1Maximum: 6000

Create an Outbound Phone Number Report

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

Create a default Outbound Phone Number Report

1curl -X POST "https://insights.twilio.com/v2/Voice/Reports/PhoneNumbers/Outbound" \
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-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/PhoneNumbers/Outbound/voiceinsights_report_XXXXXXXXXXXXXXXXXXXXXXXXXX"
11}

Create an Outbound Phone Number Report with Date Range

Generate an outbound report for a specific period by providing the time_range parameter.

Create an Outbound Phone Number Report with Date Range

1curl -X POST "https://insights.twilio.com/v2/Voice/Reports/PhoneNumbers/Outbound" \
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/PhoneNumbers/Outbound/voiceinsights_report_XXXXXXXXXXXXXXXXXXXXXXXXXX"
11}

Fetch an Outbound Phone Number Report

GET /v2/Voice/Reports/PhoneNumbers/Outbound/{reportId}

Path parameters

Property nameTypeRequiredPIIDescriptionChild properties

reportIdstring

required

A unique request id

Query parameters

Property nameTypeRequiredPIIDescriptionChild properties

pageSizeinteger

Optional

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

Default: 50Minimum: 1Maximum: 1000

pageTokenstring

Optional

The page token. This is provided by the API.

pageinteger

Optional

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

Minimum: 0

Fetch an Outbound Phone Number Report

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

Output

1{
2  "meta": {
3    "first_page_url": "https://insights.twilio.com/v2/Voice/Reports/PhoneNumbers/Outbound/voiceinsights_report_XXXXXXXXXXXXXXXXXXXXXXXXXX?PageSize=50&Page=0",
4    "key": "reports",
5    "next_page_url": null,
6    "page": 0,
7    "page_size": 50,
8    "previous_page_url": null,
9    "url": "https://insights.twilio.com/v2/Voice/Reports/PhoneNumbers/Outbound/voiceinsights_report_XXXXXXXXXXXXXXXXXXXXXXXXXX?PageSize=50&Page=0"
10  },
11  "reports": [
12    {
13      "handle": "+15555555555",
14      "total_calls": 23611,
15      "call_answer_score": 88.73,
16      "calls_by_device_type": {
17        "voip": 84,
18        "mobile": 21056,
19        "landline": 1535,
20        "unknown": 936
21      },
22      "answer_rate_device_type": {
23        "voip": 80.95,
24        "mobile": 94.6,
25        "landline": 60.46,
26        "unknown": 3.53
27      },
28      "call_state_percentage": {
29        "completed": 88.73,
30        "noanswer": 2.19,
31        "fail": 5.1,
32        "busy": 0.92,
33        "canceled": 3.07
34      },
35      "blocked_calls_by_carrier": [
36        {
37          "country": "US",
38          "carriers": [
39            {
40              "carrier": "att",
41              "total_calls": 6599,
42              "blocked_calls": 24,
43              "blocked_calls_percentage": 0.36
44            },
45            {
46              "carrier": "tmobile",
47              "total_calls": 4626,
48              "blocked_calls": 17,
49              "blocked_calls_percentage": 0.37
50            },
51            {
52              "carrier": "verizon",
53              "total_calls": 9166,
54              "blocked_calls": 29,
55              "blocked_calls_percentage": 0.32
56            }
57          ]
58        }
59      ],
60      "silent_calls_percentage": 1.05,
61      "short_duration_calls_percentage": 26.36,
62      "long_duration_calls_percentage": 8.5,
63      "potential_robocalls_percentage": 0.43,
64      "answering_machine_detection": {
65        "total_calls": 0,
66        "answered_by_human_percentage": 0.0,
67        "answered_by_machine_percentage": 0.0
68      }
69    }
70  ]
71}