Reports API

The Reports API enables you to request a report of activity for your Vonage account.

Depending on your query pattern, you can choose from one of the two versions of the Reports API: asynchronous and synchronous. The asynchronous version is optimized for infrequent and large data queries (from several records to tens of millions). The synchronous version is optimized for frequent and periodic retrievals of small batches of data records (from one record to tens of thousand per query).

Only synchronous version supports retrival of data records by message/record ID.

Vonage recommends that you limit asynchronous queries to a maximum of 7 million records, by setting the start and end dates accordingly. On average, the asynchronous Reports API takes 5 - 10 minutes to generate 1 million records.

Reports API is a paid product. Full pricing is available at https://www.vonage.com/communications-apis/pricing/.

We recommend the unlimited option if you are going to retrieve more than 1M records per month.

Download OpenAPI Specification

Available Operations

Load records synchronously

Fetch usage data synchronously

gethttps://api.nexmo.com/v2/reports/records

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Query Parameters

account_id

string

Min8

Max8

The account for which the list of reports will be queried. Mandatory for Video API Reports.

product

string

exampleSMS

The product to return records for. NB: CONVERSATIONS has been deprecated - please use CONVERSATION-EVENT instead.

Must be one of:SMSVOICE-CALLVOICE-FAILEDVOICE-TTSIN-APP-VOICEWEBSOCKET-CALLVERIFY-APIVERIFY-V2NUMBER-INSIGHTNUMBER-INSIGHT-V2MESSAGESASRCONVERSATION-MESSAGECONVERSATION-EVENTREPORTS-USAGEMEETINGSNETWORK-API-EVENTAMDSMS-TRAFFIC-CONTROLVIDEO-API

direction

string

exampleoutbound

Direction of the communication, either inbound (received by our services), or outbound (originated from our services). Required for products SMS and MESSAGES. Optional for VOICE-CALL,VOICE-FAILED, ASR. Invalid for REPORTS-USAGE, VOICE-TTS, IN-APP-VOICE, WEBSOCKET-CALL, CONVERSATION-EVENT (deprecated CONVERSATIONS), CONVERSATION-MESSAGE, NUMBER-INSIGHT, VERIFY-API, VERIFY-V2, NUMBER-INSIGHT-V2, NETWORK-API-EVENT, AMD, VIDEO-API, SMS-TRAFFIC-CONTROL.

Must be one of:inboundoutbound

string

The UUID of the message or call to be searched for. You can specify a comma-separated list of UUIDs. If UUIDs are not found they are listed in the response in the ids_not_found field.

If you specify id, you must not specify status, date_start or date_end.

include_subaccounts

boolean

Whether to include subaccounts in the report.

meeting_id

string

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

Filter by Meeting ID for Video API reports.

date_start

string(date-time)

ISO-8601 extended time zone offset or ISO-8601 UTC zone offset formatted date (format yyyy-mm-ddThh:mm:ss[.sss]±hh:mm or yyyy-mm-ddThh:mm:ss[.sss]Z) for when reports should begin.

It filters on the time the API call was received by Vonage and corresponds to the field date_received (date_start for Voice) in the report file. It is inclusive, i.e. the provided value is less than or equal to the value in the field date_received (date_start for Voice) in the CDR.

If you provide this, you must provide date_end and must not provide id.

date_end

string(date-time)

ISO-8601 extended time zone offset or ISO-8601 UTC zone offset formatted date (format yyyy-mm-ddThh:mm:ss[.sss]±hh:mm or yyyy-mm-ddThh:mm:ss[.sss]Z) for when report should end.

It is exclusive, i.e. the provided value is strictly greater than the value in the field date_received in the CDR.

If you provide this, you must provide date_start and must not provide id.

session_id

string

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

Session ID to filter by for Video API reports.

include_message

boolean

Include the message contents in the records. Only applicable for use with products SMS and MESSAGES, where it is optional.

Must be one of:truefalse

show_concatenated

boolean

Indicates whether the SMS was split up into multiple parts (due to its length).

Must be one of:truefalse

status

string

Defaultnone

The SMS status to search for. Optional where product is SMS.

Must be one of:deliveredexpiredfailedrejectedacceptedbufferedunknowndeleted

Responses
Content Type
application/json

One Of

_links

object

self

object

href

string

example

https://api.nexmo.com/v2/reports/records?product=SMS&direction=outbound&date_start=2020-03-05T13%3A00%3A00Z&date_end=2020-03-05T14%0A00%3A00Z&account_id=abcdef01

request_id

string

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

UUID of the request.

request_status

string

exampleSUCCESS

Status of the request.

Must be one of:PENDINGPROCESSINGSUCCESSABORTEDFAILEDTRUNCATED

received_at

string(date-time)

example2019-06-28T15:30:00+0000

Time at which the report request was received by the service.

price

string

example0.042

Price of the request (deprecated).

currency

string

Always an empty string (deprecated).

account_id

string

exampleabcdef01

The account ID (API key) you wish to search for. This can differ from the API key in the authorization header because some accounts can request reports for other accounts, e.g. a primary account owner wants to create a report for one of its subaccounts.

ids_not_found

string

example7b10a0c2-1a05-11eb-bad9-38f9d331649,7b1091b8-1a05-11eb-bad9-38f9d331493

If you request multiple records using a comma-separated list of UUIDs, then the UUIDs of any records not found are listed in this field.

records

array

Records in JSON format

product

exampleREPORTS-USAGE

acc

string

exampleabcdef01

Account authenticated when making Reports API call. Not necessarily the same as account_id for which reports data is requested.

For example, In case of authenticating with master account API Key to request data for it's subaccount, the field will hold master account id/API Key, but report itself will show data related to it's subaccount id (subaccount API Key will be reflected in account_id).

product_type

string

examplereports

Report's API product.

Must be one of:reports

date_received

string(date-time)

example2019-06-28T15:30:00+0000

Date when report was requested by Customer by calling Reports API.

date_started

string(date-time)

example2019-06-28T15:30:00+0000

Date when Reports API started processing the request.

date_finished

string(date-time)

example2019-06-28T15:30:00+0000

Date when Reports API finished processing the request.

account_id

string

exampleabcdef01

The account ID (API key) for which the report data is generated (the account_id parameter used in the request).

master_account_id

string

exampleabcdef01

Master account ID of requested account (account_id field in the report). If Master account is not available, the field will be equal to account_id.

request_params

string

example

{product: 'MESSAGES', account_id: '12334sdf', include_message: 'true', include_subaccounts: 'true', direction: 'outbound', date_start: 'Mon Feb 19 00:00:00 GMT 2024', date_end: 'Tue Feb 20 00:00:00 GMT 2024', callback_url: 'test1@example.com'}

Parameters/filters used by the Customer while requesting the report - all possible request parameters are specified at https://developer.vonage.com/en/api/reports#get-records.

items_written

string

example134

Number of CDRs/records returned in the report

price

string

example0.042

The price for the CDR in the report (individual record in the report).

currency

string

exampleEUR

Currency of the price of the report.

total_price

string

example0.042

Total price of the report.

string

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The unique id of the record in the report

Example Response

{
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v2/reports/records?product=SMS&direction=outbound&date_start=2020-03-05T13%3A00%3A00Z&date_end=2020-03-05T14%0A00%3A00Z&account_id=abcdef01"
      }
   },
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "request_status": "SUCCESS",
   "received_at": "2019-06-28T15:30:00+0000",
   "price": "0.042",
   "currency": "",
   "account_id": "abcdef01",
   "ids_not_found": "7b10a0c2-1a05-11eb-bad9-38f9d331649,7b1091b8-1a05-11eb-bad9-38f9d331493",
   "records": [
      {
         "product": "REPORTS-USAGE",
         "acc": "abcdef01",
         "product_type": "reports",
         "date_received": "2019-06-28T15:30:00+0000",
         "date_started": "2019-06-28T15:30:00+0000",
         "date_finished": "2019-06-28T15:30:00+0000",
         "account_id": "abcdef01",
         "master_account_id": "abcdef01",
         "request_params": "{product: 'MESSAGES', account_id: '12334sdf', include_message: 'true', include_subaccounts: 'true', direction: 'outbound', date_start: 'Mon Feb 19 00:00:00 GMT 2024', date_end: 'Tue Feb 20 00:00:00 GMT 2024', callback_url: 'test1@example.com'}",
         "items_written": "134",
         "price": "0.042",
         "currency": "EUR",
         "total_price": "0.042",
         "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
      }
   ]
}

List reports

This operation is deprecated. Please use the Load records synchronously or Load records asynchronously operations with the REPORTS-USAGE product.

List reports created by the specified account based on filtered provided.

Note that there is a data retention period of 4 days, so reports older than 4 days will not be listed.

gethttps://api.nexmo.com/v2/reports

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Query Parameters

account_id

string

Min8

Max8

The account for which the list of reports will be queried.

status

string

A comma-separated list of report status values. Reports with any of the statuses specified are returned. The values in the comma-seperated list specified for status can be any of PENDING, PROCESSING, SUCCESS, ABORTED, FAILED, TRUNCATED.

date_from

string(date-time)

ISO-8601 extended time zone offset or ISO-8601 UTC zone offset formatted date from which the list of reports will be queried. Format yyyy-mm-ddThh:mm:ss[.sss]±hh:mm or yyyy-mm-ddThh:mm:ss[.sss]Z.

date_to

string(date-time)

ISO-8601 extended time zone offset or ISO-8601 UTC zone offset formatted date until which the list of reports will be queried. Format yyyy-mm-ddThh:mm:ss[.sss]±hh:mm or yyyy-mm-ddThh:mm:ss[.sss]Z.

Responses
Content Type
application/json

items_count

string

The number of reports in the list.

self_link

string(uri)

examplehttps://api.nexmo.com/v2/reports/

URI of this search.

reports

array

The list of reports.

Any Of

request_id

string

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

UUID of the request.

request_status

string

exampleSUCCESS

Status of the request.

Must be one of:PENDINGPROCESSINGSUCCESSABORTEDFAILEDTRUNCATED

product

string

example

[
  "SMS",
  "REPORTS-USAGE"
]

Which product you wish to generate a report for. NB: CONVERSATIONS has been deprecated - please use CONVERSATION-EVENT instead.

account_id

string

exampleabcdef01

The account ID (API key) for which the report data is generated (the account_id parameter used in the request).

date_start

string(date-time)

example2017-12-01T00:00:00+00:00

ISO-8601 extended time zone offset or ISO-8601 UTC zone offset formatted date (format yyyy-mm-ddThh:mm:ss[.sss]±hh:mm or yyyy-mm-ddThh:mm:ss[.sss]Z) for when reports should begin. It filters on the time the API call was received by Vonage and corresponds to the field date_received (date_start for Voice) in the report file. It is inclusive, i.e. the provided value is less than or equal to the value in the field date_received (date_start for Voice) in the CDR.
If unspecified, defaults to seven days ago.

date_end

string(date-time)

example2018-01-01T00:00:00+00:00

ISO-8601 extended time zone offset or ISO-8601 UTC zone offset formatted date (format yyyy-mm-ddThh:mm:ss[.sss]±hh:mm or yyyy-mm-ddThh:mm:ss[.sss]Z) for when report should end. It is exclusive, i.e. the provided value is strictly greater than the value in the field date_received in the CDR.
If unspecified, defaults to the current time.

include_subaccounts

string

Defaultfalse

examplefalse

Whether to include subaccounts or not.

callback_url

string(uri)

examplehttps://requestb.in/12345

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time

string(date-time)

example2019-06-28T15:30:00+0000

Time at which the report request was received by the service.

start_time

string(date-time)

example2019-06-28T15:30:00+0000

Time at which the report processing of the report has started.

_links

object

self

object

href

string(uri)

examplehttps://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

URI of this document.

download_report

object

href

string(uri)

examplehttps://api.nexmo.com/v3/media/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

URL pointing to the generated report.

items_count

string

example10

The number of rows in the resulting file (when report has been completed).

acc

string

exampleabcdef01

Account authenticated when making Reports API call. Not necessarily the same as account_id for which reports data is requested.

product_type

string

examplereports

Report's API product.

Must be one of:reports

date_received

string(date-time)

example2019-06-28T15:30:00+0000

Date when report was requested by Customer by calling Reports API.

date_started

string(date-time)

example2019-06-28T15:30:00+0000

Date when Reports API started processing the request.

date_finished

string(date-time)

example2019-06-28T15:30:00+0000

Date when Reports API finished processing the request.

master_account_id

string

exampleabcdef01

Master account ID of requested account (account_id field in the report). If Master account is not available, the field will be equal to account_id.

request_params

string

example

{product: 'MESSAGES', account_id: '12334sdf', include_message: 'true', include_subaccounts: 'true', direction: 'outbound', date_start: 'Mon Feb 19 00:00:00 GMT 2024', date_end: 'Tue Feb 20 00:00:00 GMT 2024', callback_url: 'test1@example.com'}

Parameters/filters used by the Customer while requesting the report - all possible request parameters are specified at https://developer.vonage.com/en/api/reports#get-records.

items_written

string

example134

Number of CDRs/records returned in the report

price

string

example0.042

The price for the CDR in the report (individual record in the report).

currency

string

exampleEUR

Currency of the price of the report.

total_price

string

example0.042

Total price of the report.

string

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The unique id of the record in the report

Example Response

{
   "items_count": "string",
   "self_link": "https://api.nexmo.com/v2/reports/",
   "reports": [
      {
         "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
         "request_status": "SUCCESS",
         "product": "REPORTS-USAGE",
         "account_id": "abcdef01",
         "date_start": "2017-12-01T00:00:00+00:00",
         "date_end": "2018-01-01T00:00:00+00:00",
         "include_subaccounts": "false",
         "callback_url": "https://requestb.in/12345",
         "receive_time": "2019-06-28T15:30:00+0000",
         "start_time": "2019-06-28T15:30:00+0000",
         "_links": {
            "self": {
               "href": "https://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
            },
            "download_report": {
               "href": "https://api.nexmo.com/v3/media/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
            }
         },
         "items_count": "10",
         "acc": "abcdef01",
         "product_type": "reports",
         "date_received": "2019-06-28T15:30:00+0000",
         "date_started": "2019-06-28T15:30:00+0000",
         "date_finished": "2019-06-28T15:30:00+0000",
         "master_account_id": "abcdef01",
         "request_params": "{product: 'MESSAGES', account_id: '12334sdf', include_message: 'true', include_subaccounts: 'true', direction: 'outbound', date_start: 'Mon Feb 19 00:00:00 GMT 2024', date_end: 'Tue Feb 20 00:00:00 GMT 2024', callback_url: 'test1@example.com'}",
         "items_written": "134",
         "price": "0.042",
         "currency": "EUR",
         "total_price": "0.042",
         "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
      }
   ]
}

Create an asynchronous report

Request a report on your account activity

posthttps://api.nexmo.com/v2/reports

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Request Body
Content Type
application/json

One Of

product

string

Required

example

[
  "SMS",
  "REPORTS-USAGE"
]

Which product you wish to generate a report for. NB: CONVERSATIONS has been deprecated - please use CONVERSATION-EVENT instead.

account_id

string

Required

exampleabcdef01

The account ID (API key) for which the report data is generated (the account_id parameter used in the request).

date_start

string(date-time)

example2017-12-01T00:00:00+00:00

date_end

string(date-time)

example2018-01-01T00:00:00+00:00

ISO-8601 extended time zone offset or ISO-8601 UTC zone offset formatted date (format yyyy-mm-ddThh:mm:ss[.sss]±hh:mm or yyyy-mm-ddThh:mm:ss[.sss]Z) for when report should end. It is exclusive, i.e. the provided value is strictly greater than the value in the field date_received in the CDR.
If unspecified, defaults to the current time.

include_subaccounts

string

Defaultfalse

examplefalse

Whether to include subaccounts or not.

callback_url

string(uri)

examplehttps://requestb.in/12345

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

acc

string

exampleabcdef01

Account authenticated when making Reports API call. Not necessarily the same as account_id for which reports data is requested.

product_type

string

examplereports

Report's API product.

Must be one of:reports

date_received

string(date-time)

example2019-06-28T15:30:00+0000

Date when report was requested by Customer by calling Reports API.

date_started

string(date-time)

example2019-06-28T15:30:00+0000

Date when Reports API started processing the request.

date_finished

string(date-time)

example2019-06-28T15:30:00+0000

Date when Reports API finished processing the request.

master_account_id

string

exampleabcdef01

Master account ID of requested account (account_id field in the report). If Master account is not available, the field will be equal to account_id.

request_params

string

example

{product: 'MESSAGES', account_id: '12334sdf', include_message: 'true', include_subaccounts: 'true', direction: 'outbound', date_start: 'Mon Feb 19 00:00:00 GMT 2024', date_end: 'Tue Feb 20 00:00:00 GMT 2024', callback_url: 'test1@example.com'}

Parameters/filters used by the Customer while requesting the report - all possible request parameters are specified at https://developer.vonage.com/en/api/reports#get-records.

items_written

string

example134

Number of CDRs/records returned in the report

price

string

example0.042

The price for the CDR in the report (individual record in the report).

currency

string

exampleEUR

Currency of the price of the report.

total_price

string

example0.042

Total price of the report.

string

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The unique id of the record in the report

Example Request»Reports Usage

{
   "product": "REPORTS-USAGE",
   "account_id": "abcdef01",
   "date_start": "2017-12-01T00:00:00+00:00",
   "date_end": "2018-01-01T00:00:00+00:00",
   "include_subaccounts": "false",
   "callback_url": "https://requestb.in/12345",
   "acc": "abcdef01",
   "product_type": "reports",
   "date_received": "2019-06-28T15:30:00+0000",
   "date_started": "2019-06-28T15:30:00+0000",
   "date_finished": "2019-06-28T15:30:00+0000",
   "master_account_id": "abcdef01",
   "request_params": "{product: 'MESSAGES', account_id: '12334sdf', include_message: 'true', include_subaccounts: 'true', direction: 'outbound', date_start: 'Mon Feb 19 00:00:00 GMT 2024', date_end: 'Tue Feb 20 00:00:00 GMT 2024', callback_url: 'test1@example.com'}",
   "items_written": "134",
   "price": "0.042",
   "currency": "EUR",
   "total_price": "0.042",
   "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

{
   "product": "REPORTS-USAGE",
   "account_id": "abcdef01",
   "date_start": "2017-12-01T00:00:00+00:00",
   "date_end": "2018-01-01T00:00:00+00:00",
   "include_subaccounts": "false",
   "callback_url": "https://requestb.in/12345",
   "acc": "abcdef01",
   "product_type": "reports",
   "date_received": "2019-06-28T15:30:00+0000",
   "date_started": "2019-06-28T15:30:00+0000",
   "date_finished": "2019-06-28T15:30:00+0000",
   "master_account_id": "abcdef01",
   "request_params": "{product: 'MESSAGES', account_id: '12334sdf', include_message: 'true', include_subaccounts: 'true', direction: 'outbound', date_start: 'Mon Feb 19 00:00:00 GMT 2024', date_end: 'Tue Feb 20 00:00:00 GMT 2024', callback_url: 'test1@example.com'}",
   "items_written": "134",
   "price": "0.042",
   "currency": "EUR",
   "total_price": "0.042",
   "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

Responses
Content Type
application/json

One Of

request_id

string

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

UUID of the request.

request_status

string

examplePENDING

Status of the request.

Must be one of:PENDINGPROCESSINGSUCCESSABORTEDFAILEDTRUNCATED

product

string

Required

exampleSMS

Which product you wish to generate a report for. NB: CONVERSATIONS has been deprecated - please use CONVERSATION-EVENT instead.

account_id

string

Required

exampleabcdef01

date_start

string(date-time)

example2017-12-01T00:00:00+00:00

date_end

string(date-time)

example2018-01-01T00:00:00+00:00

ISO-8601 extended time zone offset or ISO-8601 UTC zone offset formatted date (format yyyy-mm-ddThh:mm:ss[.sss]±hh:mm or yyyy-mm-ddThh:mm:ss[.sss]Z) for when report should end. It is exclusive, i.e. the provided value is strictly greater than the value in the field date_received in the CDR.
If unspecified, defaults to the current time.

include_subaccounts

string

Defaultfalse

examplefalse

Whether to include subaccounts or not.

callback_url

string(uri)

examplehttps://requestb.in/12345

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time

string(date-time)

example2019-06-28T15:30:00+0000

Time at which the report request was received by the service.

start_time

string(date-time)

example2019-06-28T15:30:00+0000

Time at which the report processing of the report has started.

_links

object

self

object

href

string(uri)

examplehttps://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

URI of this document.

direction

string

Required

exampleoutbound

Must be one of:inboundoutbound

status

string

exampledelivered

Search only for sms with the corresponding status.

Must be one of:deliveredexpiredfailedrejectedacceptedbufferedunknown

client_ref

string

Min40

Max100

Search for messages with this client_ref.

account_ref

string

Min40

Max40

Search for messages with this account_ref.

include_message

string

Defaultfalse

exampletrue

Include the text of messages in the report.

show_concatenated

string

Defaultfalse

examplefalse

Indicates whether the SMS was split up into multiple parts (due to its length).

network

string

example23415

The network code of the destination phone number. Taken from a carrier lookup (or sometimes the numbering plan), and always a master network code. Usually an MCC/MNC but sometimes alpha (e.g. US-FIXED).

from

string

example441234567890

Request from this number.

string

example441234567890

Request to this number.

Example Response»SMS

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "request_status": "PENDING",
   "product": "SMS",
   "account_id": "abcdef01",
   "date_start": "2017-12-01T00:00:00+00:00",
   "date_end": "2018-01-01T00:00:00+00:00",
   "include_subaccounts": "false",
   "callback_url": "https://requestb.in/12345",
   "receive_time": "2019-06-28T15:30:00+0000",
   "start_time": "2019-06-28T15:30:00+0000",
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
      }
   },
   "direction": "outbound",
   "status": "delivered",
   "client_ref": "stringstringstringstringstringstringstri",
   "account_ref": "stringstringstringstringstringstringstri",
   "include_message": "true",
   "show_concatenated": "false",
   "network": "23415",
   "from": "441234567890",
   "to": "441234567890"
}

Get status of report

Retrieve status and metadata about a requested report.

Note that there is a data retention period of 4 days, so reports older than 4 days will not be able to be retrieved.

gethttps://api.nexmo.com/v2/reports/:report_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

report_id

string

Required

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

UUID of the report request (request_id in response).

Responses
Content Type
application/json

One Of

request_id

string

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

UUID of the request.

request_status

string

exampleSUCCESS

Status of the request.

Must be one of:PENDINGPROCESSINGSUCCESSABORTEDFAILEDTRUNCATED

product

string

example

[
  "SMS",
  "REPORTS-USAGE"
]

Which product you wish to generate a report for. NB: CONVERSATIONS has been deprecated - please use CONVERSATION-EVENT instead.

account_id

string

exampleabcdef01

The account ID (API key) for which the report data is generated (the account_id parameter used in the request).

date_start

string(date-time)

example2017-12-01T00:00:00+00:00

date_end

string(date-time)

example2018-01-01T00:00:00+00:00

ISO-8601 extended time zone offset or ISO-8601 UTC zone offset formatted date (format yyyy-mm-ddThh:mm:ss[.sss]±hh:mm or yyyy-mm-ddThh:mm:ss[.sss]Z) for when report should end. It is exclusive, i.e. the provided value is strictly greater than the value in the field date_received in the CDR.
If unspecified, defaults to the current time.

include_subaccounts

string

Defaultfalse

examplefalse

Whether to include subaccounts or not.

callback_url

string(uri)

examplehttps://requestb.in/12345

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time

string(date-time)

example2019-06-28T15:30:00+0000

Time at which the report request was received by the service.

start_time

string(date-time)

example2019-06-28T15:30:00+0000

Time at which the report processing of the report has started.

_links

object

self

object

href

string(uri)

examplehttps://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

URI of this document.

download_report

object

href

string(uri)

examplehttps://api.nexmo.com/v3/media/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

URL pointing to the generated report.

items_count

string

example10

The number of rows in the resulting file (when report has been completed).

acc

string

exampleabcdef01

Account authenticated when making Reports API call. Not necessarily the same as account_id for which reports data is requested.

product_type

string

examplereports

Report's API product.

Must be one of:reports

date_received

string(date-time)

example2019-06-28T15:30:00+0000

Date when report was requested by Customer by calling Reports API.

date_started

string(date-time)

example2019-06-28T15:30:00+0000

Date when Reports API started processing the request.

date_finished

string(date-time)

example2019-06-28T15:30:00+0000

Date when Reports API finished processing the request.

master_account_id

string

exampleabcdef01

Master account ID of requested account (account_id field in the report). If Master account is not available, the field will be equal to account_id.

request_params

string

example

{product: 'MESSAGES', account_id: '12334sdf', include_message: 'true', include_subaccounts: 'true', direction: 'outbound', date_start: 'Mon Feb 19 00:00:00 GMT 2024', date_end: 'Tue Feb 20 00:00:00 GMT 2024', callback_url: 'test1@example.com'}

Parameters/filters used by the Customer while requesting the report - all possible request parameters are specified at https://developer.vonage.com/en/api/reports#get-records.

items_written

string

example134

Number of CDRs/records returned in the report

price

string

example0.042

The price for the CDR in the report (individual record in the report).

currency

string

exampleEUR

Currency of the price of the report.

total_price

string

example0.042

Total price of the report.

string

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The unique id of the record in the report

Example Response»Reports Usage

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "request_status": "SUCCESS",
   "product": "REPORTS-USAGE",
   "account_id": "abcdef01",
   "date_start": "2017-12-01T00:00:00+00:00",
   "date_end": "2018-01-01T00:00:00+00:00",
   "include_subaccounts": "false",
   "callback_url": "https://requestb.in/12345",
   "receive_time": "2019-06-28T15:30:00+0000",
   "start_time": "2019-06-28T15:30:00+0000",
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
      },
      "download_report": {
         "href": "https://api.nexmo.com/v3/media/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
      }
   },
   "items_count": "10",
   "acc": "abcdef01",
   "product_type": "reports",
   "date_received": "2019-06-28T15:30:00+0000",
   "date_started": "2019-06-28T15:30:00+0000",
   "date_finished": "2019-06-28T15:30:00+0000",
   "master_account_id": "abcdef01",
   "request_params": "{product: 'MESSAGES', account_id: '12334sdf', include_message: 'true', include_subaccounts: 'true', direction: 'outbound', date_start: 'Mon Feb 19 00:00:00 GMT 2024', date_end: 'Tue Feb 20 00:00:00 GMT 2024', callback_url: 'test1@example.com'}",
   "items_written": "134",
   "price": "0.042",
   "currency": "EUR",
   "total_price": "0.042",
   "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

Cancel the execution of a report

Cancel the execution of a pending or processing report.

deletehttps://api.nexmo.com/v2/reports/:report_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

report_id

string

Required

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

UUID of the report

Responses
Content Type
application/json

One Of

request_id

string

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

UUID of the request.

request_status

string

exampleSUCCESS

Status of the request.

Must be one of:PENDINGPROCESSINGSUCCESSABORTEDFAILEDTRUNCATED

product

string

example

[
  "SMS",
  "REPORTS-USAGE"
]

Which product you wish to generate a report for. NB: CONVERSATIONS has been deprecated - please use CONVERSATION-EVENT instead.

account_id

string

exampleabcdef01

The account ID (API key) for which the report data is generated (the account_id parameter used in the request).

date_start

string(date-time)

example2017-12-01T00:00:00+00:00

date_end

string(date-time)

example2018-01-01T00:00:00+00:00

ISO-8601 extended time zone offset or ISO-8601 UTC zone offset formatted date (format yyyy-mm-ddThh:mm:ss[.sss]±hh:mm or yyyy-mm-ddThh:mm:ss[.sss]Z) for when report should end. It is exclusive, i.e. the provided value is strictly greater than the value in the field date_received in the CDR.
If unspecified, defaults to the current time.

include_subaccounts

string

Defaultfalse

examplefalse

Whether to include subaccounts or not.

callback_url

string(uri)

examplehttps://requestb.in/12345

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time

string(date-time)

example2019-06-28T15:30:00+0000

Time at which the report request was received by the service.

start_time

string(date-time)

example2019-06-28T15:30:00+0000

Time at which the report processing of the report has started.

_links

object

self

object

href

string(uri)

examplehttps://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

URI of this document.

download_report

object

href

string(uri)

examplehttps://api.nexmo.com/v3/media/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

URL pointing to the generated report.

items_count

string

example10

The number of rows in the resulting file (when report has been completed).

acc

string

exampleabcdef01

Account authenticated when making Reports API call. Not necessarily the same as account_id for which reports data is requested.

product_type

string

examplereports

Report's API product.

Must be one of:reports

date_received

string(date-time)

example2019-06-28T15:30:00+0000

Date when report was requested by Customer by calling Reports API.

date_started

string(date-time)

example2019-06-28T15:30:00+0000

Date when Reports API started processing the request.

date_finished

string(date-time)

example2019-06-28T15:30:00+0000

Date when Reports API finished processing the request.

master_account_id

string

exampleabcdef01

Master account ID of requested account (account_id field in the report). If Master account is not available, the field will be equal to account_id.

request_params

string

example

{product: 'MESSAGES', account_id: '12334sdf', include_message: 'true', include_subaccounts: 'true', direction: 'outbound', date_start: 'Mon Feb 19 00:00:00 GMT 2024', date_end: 'Tue Feb 20 00:00:00 GMT 2024', callback_url: 'test1@example.com'}

Parameters/filters used by the Customer while requesting the report - all possible request parameters are specified at https://developer.vonage.com/en/api/reports#get-records.

items_written

string

example134

Number of CDRs/records returned in the report

price

string

example0.042

The price for the CDR in the report (individual record in the report).

currency

string

exampleEUR

Currency of the price of the report.

total_price

string

example0.042

Total price of the report.

string

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The unique id of the record in the report

Example Response»Reports Usage

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "request_status": "SUCCESS",
   "product": "REPORTS-USAGE",
   "account_id": "abcdef01",
   "date_start": "2017-12-01T00:00:00+00:00",
   "date_end": "2018-01-01T00:00:00+00:00",
   "include_subaccounts": "false",
   "callback_url": "https://requestb.in/12345",
   "receive_time": "2019-06-28T15:30:00+0000",
   "start_time": "2019-06-28T15:30:00+0000",
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
      },
      "download_report": {
         "href": "https://api.nexmo.com/v3/media/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
      }
   },
   "items_count": "10",
   "acc": "abcdef01",
   "product_type": "reports",
   "date_received": "2019-06-28T15:30:00+0000",
   "date_started": "2019-06-28T15:30:00+0000",
   "date_finished": "2019-06-28T15:30:00+0000",
   "master_account_id": "abcdef01",
   "request_params": "{product: 'MESSAGES', account_id: '12334sdf', include_message: 'true', include_subaccounts: 'true', direction: 'outbound', date_start: 'Mon Feb 19 00:00:00 GMT 2024', date_end: 'Tue Feb 20 00:00:00 GMT 2024', callback_url: 'test1@example.com'}",
   "items_written": "134",
   "price": "0.042",
   "currency": "EUR",
   "total_price": "0.042",
   "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

Get report data

Download a zipped archive of the rendered report. The file is available for download for 72 hours.
The zip file will be named <PRODUCT>_<REPORT_ID>.zip
The csv file in the zip archive will be named as report_<PRODUCT>_<ACCOUNT_ID>_<DATE>.csv the date will be formatted as yyyyMMdd.

gethttps://api.nexmo.com/v3/media/:file_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

file_id

string

Required

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

UUID of the file.

Responses
Content Type
application/octet-stream

Zip file containing CSV files

report

array

The report in CSV format inside the zip archive.

Any Of

product

exampleREPORTS-USAGE

acc

string

exampleabcdef01

Account authenticated when making Reports API call. Not necessarily the same as account_id for which reports data is requested.

product_type

string

examplereports

Report's API product.

Must be one of:reports

date_received

string(date-time)

example2019-06-28T15:30:00+0000

Date when report was requested by Customer by calling Reports API.

date_started

string(date-time)

example2019-06-28T15:30:00+0000

Date when Reports API started processing the request.

date_finished

string(date-time)

example2019-06-28T15:30:00+0000

Date when Reports API finished processing the request.

account_id

string

exampleabcdef01

The account ID (API key) for which the report data is generated (the account_id parameter used in the request).

master_account_id

string

exampleabcdef01

Master account ID of requested account (account_id field in the report). If Master account is not available, the field will be equal to account_id.

request_params

string

example

{product: 'MESSAGES', account_id: '12334sdf', include_message: 'true', include_subaccounts: 'true', direction: 'outbound', date_start: 'Mon Feb 19 00:00:00 GMT 2024', date_end: 'Tue Feb 20 00:00:00 GMT 2024', callback_url: 'test1@example.com'}

Parameters/filters used by the Customer while requesting the report - all possible request parameters are specified at https://developer.vonage.com/en/api/reports#get-records.

items_written

string

example134

Number of CDRs/records returned in the report

price

string

example0.042

The price for the CDR in the report (individual record in the report).

currency

string

exampleEUR

Currency of the price of the report.

total_price

string

example0.042

Total price of the report.

string

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The unique id of the record in the report

Example Response

Example preview is currently not supported for content type: application/octet-stream

Errors

The following is a non-exhaustive list of error codes that may occur while using this API.

These codes are in addition to any of our generic error codes.

Code Information

Code	Information
invalid-request-parameters	Description The provided payload is invalid Resolution Modify your request to provide a valid payload
invalid-abort-operation	Description The job is already in a terminated state such as `SUCCESS`, `TRUNCATED`, `FAILED` or `ABORTED`. Resolution None
rate-limit	Description The request was rate limited. Resolution The Reports API supports 5 requests per second when used Asynchronously, and 10 requests per second Synchronously. Slow down your request rate.

invalid-request-parameters

Description

The provided payload is invalid

Resolution

Modify your request to provide a valid payload

invalid-abort-operation

Description

The job is already in a terminated state such as SUCCESS, TRUNCATED, FAILED or ABORTED.

Resolution

None

rate-limit

Description

The request was rate limited.

Resolution

The Reports API supports 5 requests per second when used Asynchronously, and 10 requests per second Synchronously. Slow down your request rate.

Reports API

Available Operations

Load records synchronously

Authentication

Query Parameters

Responses Content Typeapplication/json

Example Response

List reports

Authentication

Query Parameters

Responses Content Typeapplication/json

Example Response

Create an asynchronous report

Authentication

Request Body Content Typeapplication/json

Example Request»Reports Usage

Responses Content Typeapplication/json

Example Response»SMS

Get status of report

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response»Reports Usage

Cancel the execution of a report

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response»Reports Usage

Get report data

Authentication

Path Parameters

Responses Content Typeapplication/octet-stream

Example Response

Errors

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/octet-stream