Sign in

v1

latestOpenAPI 3.0.0The MIT License (MIT)2026-07-14614962.2 KB

Load records synchronously

Fetch usage data synchronously

get/v2/reports/records

Query parameters

account_idstring required

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

product'SMS' | 'VOICE-CALL' | 'VOICE-FAILED' | 'IN-APP-VOICE' | 'WEBSOCKET-CALL' | 'VERIFY-API' | 'NUMBER-INSIGHT' | 'MESSAGES' | 'ASR' | 'CONVERSATIONS' | 'REPORTS-USAGE' required

The product to return records for

direction'inbound' | 'outbound'

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. Invalid for IN-APP-VOICE, CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

idstring

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.

date_startstring date

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_endstring date

Must be no more than 24 hours later than date_start

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.

include_messagetrue | false

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

show_concatenatedtrue | false

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

status'delivered' | 'expired' | 'failed' | 'rejected' | 'accepted' | 'buffered' | 'unknown' | 'deleted'

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

Response

OK

OR
OR
OR
OR
OR
OR
OR
OR
OR
OR

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"
    }
  },
  "account_id": "abcdef01",
  "currency": "EUR",
  "ids_not_found": "7b10a0c2-1a05-11eb-bad9-38f9d331649,7b1091b8-1a05-11eb-bad9-38f9d331493",
  "received_at": "2019-06-28T15:30:00+0000",
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "direction": "outbound",
  "items_count": 1,
  "product": "SMS",
  "records": [
    {
      "account_id": "abcdef01",
      "country": "FR",
      "country_name": "France",
      "currency": "EUR",
      "date_finalized": "2019-06-28T15:30:00+0000",
      "date_received": "2019-06-28T15:30:00+0000",
      "direction": "outbound",
      "error_code": "0",
      "error_code_description": "Delivered",
      "from": "441234567890",
      "message_id": "0000000A",
      "network": "23415",
      "network_name": "Vodafone Limited",
      "status": "delivered",
      "to": "441234567890",
      "message_body": "This is a text message"
    }
  ]
}