Inbound 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 Inbound Phone Number Report aggregates Voice Insights metrics for calls received by a specific phone number handle.

Inbound Phone Number Report Properties

Encoding type:application/json

Schema

Property nameTypeRequiredPIIDescriptionChild properties

handlestring

Optional

PII MTL: 30 days

Inbound phone number handle represented in the report.

totalCallsinteger

Optional

Not PII

Total number of inbound calls observed during the report period.

callAnswerScorenumber<float>

Optional

Not PII

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

callStatePercentageobject

Optional

Not PII

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

Show callStatePercentage properties

silentCallsPercentagenumber<float>

Optional

Not PII

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

Create an Inbound Phone Number Report

POST /v2/Voice/Reports/PhoneNumbers/Inbound

(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

sizeinteger

Optional

Not PII

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

Default: 1000Minimum: 1Maximum: 6000

Create an Inbound Phone Number 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/PhoneNumbers/Inbound" \
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/Inbound/voiceinsights_report_XXXXXXXXXXXXXXXXXXXXXXXXXX"
11}

Create an Inbound Phone Number Report with Date Range

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

Create an Inbound Phone Number Report with Date Range

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

Fetch an Inbound Phone Number Report

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

Path parameters

Property nameTypeRequiredPIIDescriptionChild properties

reportIdstring

required

Not PII

A unique request id

Query parameters

Property nameTypeRequiredPIIDescriptionChild properties

pageSizeinteger

Optional

Not PII

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

Default: 50Minimum: 1Maximum: 1000

pageTokenstring

Optional

Not PII

The page token. This is provided by the API.

pageinteger

Optional

Not PII

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

Minimum: 0

Fetch an Inbound Phone Number Report

1curl -X GET "https://insights.twilio.com/v2/Voice/Reports/PhoneNumbers/Inbound/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/Inbound/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/Inbound/voiceinsights_report_XXXXXXXXXXXXXXXXXXXXXXXXXX?PageSize=50&Page=0"
10  },
11  "reports": [
12    {
13      "call_answer_score": 0,
14      "call_state_percentage": {
15        "busy": 100,
16        "canceled": 0,
17        "completed": 0,
18        "fail": 0,
19        "noanswer": 0
20      },
21      "handle": "+15555555555",
22      "silent_calls_percentage": 0,
23      "total_calls": 3
24    }
25  ]
26}