Before you Begin

This guide helps you get started with the Reports API. For detailed information, review the Overview and API Reference.

In this topic

Choose your approach

The Reports API provides two methods to retrieve your activity records, each optimized for different query patterns and data volumes.

Synchronous (Real-time)

The synchronous approach is best for frequent queries retrieving up to tens of thousands of records. When you make a synchronous request, records are returned immediately in the API response, making it ideal for real-time dashboards and monitoring systems. This method also supports querying by specific message or record ID, which is useful when you need to look up individual transactions. While efficient for smaller datasets, we recommend limiting synchronous queries to thousands of records per request to maintain optimal performance.

Example use case: Retrieve today's SMS delivery status for a specific campaign.

Asynchronous (Background processing)

For larger data requirements, the asynchronous approach is designed for infrequent queries that need to retrieve millions of records. Rather than returning data immediately, this method generates a downloadable ZIP file containing CSV data while processing happens in the background. The generation process typically takes 5-10 minutes per 1 million records. You can either provide a callback URL to receive a notification when processing completes, or periodically poll for the report status. To ensure optimal performance, Vonage recommends limiting asynchronous queries to a maximum of 7 million records by setting appropriate start and end dates.

Example use case: Generate a monthly report of all voice calls.

Making your first request

Synchronous request example

Retrieve SMS records for a specific date range:

curl -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \ "https://api.nexmo.com/v2/reports/records?account_id=YOUR_ACCOUNT_ID&product=SMS&direction=outbound&date_start=2026-01-01T00:00:00Z&date_end=2026-01-06T23:59:59Z"

Asynchronous request example

Generate a report for all messages sent in December:

curl -X POST "https://api.nexmo.com/v2/reports" \ -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "product": "MESSAGES", "account_id": "YOUR_ACCOUNT_ID", "direction": "outbound", "date_start": "2025-12-01T00:00:00Z", "date_end": "2025-12-31T23:59:59Z", "callback_url": "https://your-domain.com/reports/callback" }'

Authentication

All Reports API requests require HTTP Basic Authentication using your API key and secret:

-u "$VONAGE_API_KEY:$VONAGE_API_SECRET"

Replace $VONAGE_API_KEY and $VONAGE_API_SECRET with your credentials from the Vonage Dashboard.

Common parameters

These parameters are used across most Reports API calls:

Parameter Required Description Example
account_id Your Vonage API key (account ID) abcd1234
product The Vonage product to query SMS, MESSAGES, VOICE-CALL
date_start 🔸 Start of date range (ISO-8601 format) 2026-01-01T00:00:00Z
date_end 🔸 End of date range (ISO-8601 format) 2026-01-06T23:59:59Z
direction 🔸 Message/call direction inbound or outbound
id 🔸 Specific message or record ID (sync only) Cannot be used with date range

Legend: = Always required | 🔸 = Optional or product-specific

Date format requirements

Dates must be in ISO-8601 format:

  • UTC format: 2026-01-01T00:00:00Z
  • With timezone offset: 2026-01-01T08:00:00+0800

Important: When using GET requests with + in dates, URL-encode the dates:

curl -G --data-urlencode date_start="2026-01-01T08:00:00+0000" \ --data-urlencode date_end="2026-01-01T14:00:00+0000" \ -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \ "https://api.nexmo.com/v2/reports/records?account_id=abcd1234&product=SMS&direction=outbound"

Querying by ID vs date range

  • By ID: Retrieve a specific record (synchronous only)
  • By date range: Retrieve all records within a time period
  • Cannot use both: Choose either id OR date_start/date_end, not both

Product-specific parameters

Different products support different parameters. This section details the required and optional parameters for each product. For the complete parameter specifications and response formats, see the API Reference.

SMS

Required parameters:

  • product - Set to SMS
  • account_id - Your Vonage API key
  • direction - Must be either inbound or outbound

Additional parameters:

  • date_start / date_end - Date range for filtering records
  • id - Specific record ID (cannot be used with date range)
  • status - Filter by delivery status (e.g., delivered, failed, expired)
  • from - Sender number
  • to - Recipient number
  • country - Filter by country code
  • network - Filter by network MCC-MNC
  • client_ref - Your client reference
  • account_ref - Account reference
  • include_message - Include message body in response (true/false)

Example:

curl -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \ "https://api.nexmo.com/v2/reports/records?account_id=abcd1234&product=SMS&direction=outbound&status=delivered&date_start=2026-01-01T00:00:00Z&date_end=2026-01-06T23:59:59Z"

SMS-TRAFFIC-CONTROL

Required parameters:

  • product - Set to SMS-TRAFFIC-CONTROL
  • account_id - Your Vonage API key

Additional parameters:

  • date_start / date_end - Date range for filtering records
  • id - Specific record id (cannot be used with date range)

MESSAGES

Required parameters:

  • product - Set to MESSAGES
  • account_id - Your Vonage API key
  • direction - Must be either inbound or outbound

Additional parameters:

  • date_start / date_end - Date range for filtering records
  • id - Specific record ID (cannot be used with date range)
  • status - Filter by delivery status (e.g., submitted, delivered, read, rejected)
  • from - Sender identifier
  • to - Recipient identifier
  • provider - Filter by channel (e.g., whatsapp, sms, mms, viber_service_msg, messenger, instagram, rcs)
  • include_message - Include message body in response (true/false)

VOICE-CALL

Required parameters:

  • product - Set to VOICE-CALL
  • account_id - Your Vonage API key

Additional parameters:

  • direction - Call direction (inbound or outbound)
  • date_start / date_end - Date range for filtering records
  • id - Specific record ID (cannot be used with date range)
  • status - Call status (e.g., ANSWERED, MACHINE, ERROR)
  • from - Caller number
  • to - Called number
  • country - Filter by country code
  • network - Filter by network MCC-MNC
  • call_id - Specific call identifier

IN-APP-VOICE

Required parameters:

  • product - Set to IN-APP-VOICE
  • account_id - Your Vonage API key

Additional parameters:

  • date_start / date_end - Date range for filtering records
  • id - Specific record ID (cannot be used with date range)
  • status - Call termination status
  • conversation_id - Conversation ID
  • leg_id - Specific leg of a call

VOICE-TTS

Required parameters:

  • product - Set to VOICE-TTS
  • account_id - Your Vonage API key

Additional parameters:

  • date_start / date_end - Date range for filtering records
  • id - Specific record id (cannot be used with date range)

VOICE-FAILED

Required parameters:

  • product - Set to VOICE-FAILED
  • account_id - Your Vonage API key

Additional parameters:

  • direction - Call direction (inbound or outbound)
  • date_start / date_end - Date range for filtering records
  • from - Caller number
  • to - Called number
  • id - Specific record ID (cannot be used with date range)
  • country - Country code filter

WEBSOCKET-CALL

Required parameters:

  • product - Set to WEBSOCKET-CALL
  • account_id - Your Vonage API key

Additional parameters:

  • date_start / date_end - Date range for filtering records
  • id - Specific record id (cannot be used with date range)

ASR

Required parameters:

  • product - Set to ASR
  • account_id - Your Vonage API key

Additional parameters:

  • direction - Call direction (inbound or outbound)
  • date_start / date_end - Date range for filtering records
  • from - Caller ID
  • to - Number called
  • id - Specific record ID (cannot be used with date range)

AMD

Required parameters:

  • product - Set to AMD
  • account_id - Your Vonage API key

Additional parameters:

  • date_start / date_end - Date range for filtering records
  • id - Specific record id (cannot be used with date range)

VERIFY-API

Required parameters:

  • product - Set to VERIFY-API
  • account_id - Your Vonage API key

Additional parameters:

  • date_start / date_end - Date range for filtering records
  • id - Specific record ID (cannot be used with date range)
  • to - Phone number that was verified
  • network - Filter by network MCC-MNC

VERIFY-V2

Required parameters:

  • product - Set to VERIFY-V2
  • account_id - Your Vonage API key

Additional parameters:

  • date_start / date_end - Date range for filtering records
  • channel - Verification channel (v2, email, silent_auth)
  • status - Request status
  • parent_request_id - Filter by parent request ID, which correlates v2 verification requests with their associated email or silent_auth events
  • country - Country Code
  • locale - Language/Locale
  • network - Mobile network code
  • to - Phone number being verified
  • id - Specific record id (cannot be used with date range)

NUMBER-INSIGHT

Required parameters:

  • product - Set to NUMBER-INSIGHT
  • account_id - Your Vonage API key

Additional parameters:

  • date_start / date_end - Date range for filtering records
  • id - Specific record ID (cannot be used with date range)
  • number - Phone number that was queried
  • network - Mobile network code

NUMBER-INSIGHT-V2

Required parameters:

  • product - Set to NUMBER-INSIGHT-V2
  • account_id - Your Vonage API key

Additional parameters:

  • date_start / date_end - Date range for filtering records
  • request_type - Type of insight request (e.g., fraud_score, sim_swap)
  • risk - Risk assessment level
  • status- Number Insight request status
  • swapped - Whether the number has been ported/swapped
  • id - Specific record id (cannot be used with date range)

CONVERSATION-EVENT

Required parameters:

  • product - Set to CONVERSATION-EVENT
  • account_id - Your Vonage API key

Additional parameters:

  • date_start / date_end - Date range for filtering records
  • conversation_id - Specific conversation ID
  • status - Event status
  • id - Specific record ID (cannot be used with date range)

CONVERSATION-MESSAGE

Required parameters:

  • product - Set to CONVERSATION-MESSAGE
  • account_id - Your Vonage API key

Additional parameters:

  • date_start / date_end - Date range for filtering records
  • conversation_id - Specific conversation ID
  • id - Specific record ID (cannot be used with date range)

VIDEO-API

Required parameters:

  • product - Set to VIDEO-API
  • account_id - Your Vonage API key

Additional parameters:

  • date_start / date_end - Date range for filtering records
  • session_id - Video session ID
  • meeting_id - Meeting identifier
  • id - Specific record ID (cannot be used with date range)

NETWORK-API-EVENT

Required parameters:

  • product - Set to NETWORK-API-EVENT
  • account_id - Your Vonage API key

Additional parameters:

  • date_start / date_end - Date range for filtering records
  • product_name - Specific Network API product
  • request_session_id - Request session identifier
  • product_path - API product path
  • correlation_id - Correlation ID
  • request_type - Type of Network API Request
  • id - Specific record ID (cannot be used with date range)

REPORTS-USAGE

Required parameters:

  • product - Set to REPORTS-USAGE
  • account_id - Your Vonage API key

Additional parameters:

  • date_start / date_end - Date range for filtering records
  • id - Specific record ID (cannot be used with date range)

Note: All products support include_subaccounts parameter when creating asynchronous reports to include data from subaccounts. For complete details on response formats and additional filtering options, see the API Reference.

Working with asynchronous reports

When you create an asynchronous report, you'll receive a request_id to track the report status:

Response example:

{
  "request_id": "ri3p58f-48598ea7-1234-5678-9012-faabd79bdc2e",
  "request_status": "PENDING",
  "direction": "outbound",
  "product": "SMS",
  "account_id": "abcd1234",
  "date_start": "2026-01-01T00:00:00+0000",
  "date_end": "2026-01-06T23:59:59+0000",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/ri3p58f-48598ea7-1234-5678-9012-faabd79bdc2e"
    }
  }
}

Check report status

Use the request_id to check if your report is ready:

curl -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \ "https://api.nexmo.com/v2/reports/ri3p58f-48598ea7-1234-5678-9012-faabd79bdc2e"

Download completed report

When the report status is SUCCESS, extract the file_id from the response and download:

curl -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \ "https://api.nexmo.com/v3/media/FILE_ID" \ -o report.zip

The downloaded ZIP file contains a CSV with your records. Files are available for 72 hours.

See also