Nexmo Reports API
Browse all Nexmo APIsAgent-ready OpenAPI document · curated by JenticCommunicationsSms Messagingbasic6 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Pull SMS, voice, verify, and number-insight activity records from Vonage as either synchronous result sets or asynchronous CSV exports, then download the generated file by ID.
Use for: I need to export the last 30 days of SMS delivery records, Check whether my asynchronous report job has finished generating, Retrieve the CSV file for a completed Vonage report, List all report jobs created in the past week
Not supported: Does not send messages, place calls, or run verification challenges - use for retrieving historical Vonage activity records only.
Jentic publishes the only available OpenAPI specification for Reports API, keeping it validated and agent-ready. The Vonage Reports API exposes activity records for SMS, voice, verify, conversion, and number-insight traffic on a Vonage account, supporting both asynchronous bulk exports and synchronous lookups. Asynchronous reports are tuned for batches of millions of records (Vonage recommends capping each request at 20 million rows) while synchronous reports return small windows of records or a single record fetched by ID. Generated report files are downloaded through the media endpoint as CSV.
Install Jentic One Beta
Connect the Reports API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Reports API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fnexmo.com%2Freports-api" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fnexmo.com%2Freports-api" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Reports API.
Submit asynchronous report jobs for SMS, voice, verify, conversion, and number-insight records spanning up to 20 million rows
Poll the status of an in-flight report job and cancel it before completion if the date range needs to change
Fetch synchronous record batches scoped by product, start date, end date, and account ID for periodic dashboard refreshes
Retrieve a single message or call record by its individual ID for support investigations and audit trails
Download completed report CSV files through the media endpoint using the file ID returned in the report status response
List recent report jobs filed against the account so agents can resume work on a previously requested export
Use Cases
Patterns agents use Reports API for, with concrete tasks.
★ Bulk SMS Activity Export
Export millions of SMS delivery records from Vonage for analytics, billing reconciliation, or compliance archiving. The asynchronous Reports API accepts a date range and product filter, queues the job, and produces a downloadable CSV. Vonage recommends keeping each job under 20 million records and budgeting roughly 5-10 minutes per million rows generated. Status polling and cancellation let agents recover from misconfigured queries.
POST /v2/reports with product=SMS and a 7-day date range, poll GET /v2/reports/{report_id} until status is SUCCESS, then download the CSV via GET /v3/media/{file_id}
Synchronous Record Lookup
Fetch a small window of records or a single message record on demand for support tickets and dashboards. The synchronous endpoint returns records inline rather than queueing a job, making it suitable for tens of thousands of records or fewer. Lookups by message ID power deliverability triage when a customer reports a missing SMS or unanswered call.
Call GET /v2/reports/records with product=SMS, account_id, and a message_id query parameter to retrieve the delivery record for a specific message
Job Lifecycle Management
Track and clean up running report jobs. The list endpoint surfaces recent jobs with their statuses, the get endpoint returns progress for a single job, and the cancel endpoint stops a job that was started with incorrect parameters. This prevents wasted compute on bulk exports that target the wrong product or date range.
Call GET /v2/reports to list jobs, then DELETE /v2/reports/{report_id} to cancel any job whose date range exceeds 20 million records
AI Agent Reporting Pipeline
Through Jentic, an AI agent submits a Reports API job, polls for completion, and pipes the resulting CSV into a downstream data warehouse without ever holding the Vonage Basic auth credentials. The agent searches Jentic for the report intent, loads the schema for POST /v2/reports, and executes the call with structured arguments. Status polling and the media download are chained as additional Jentic operations.
Use Jentic search query 'export Vonage activity report' to load the create-report schema, execute with product=SMS and a date range, then chain status and media download calls
Key Endpoints
6 endpoints — jentic publishes the only available openapi specification for reports api, keeping it validated and agent-ready.
METHOD
PATH
DESCRIPTION
POST
/v2/reports
Create an asynchronous report job
GET
/v2/reports
List report jobs on the account
GET
/v2/reports/{report_id}
Get status of a report job
DELETE
/v2/reports/{report_id}
Cancel a running report job
GET
/v2/reports/records
Load records synchronously
GET
/v3/media/{file_id}
Download generated report data
POST
/v2/reports
Create an asynchronous report job
GET
/v2/reports
List report jobs on the account
GET
/v2/reports/{report_id}
Get status of a report job
DELETE
/v2/reports/{report_id}
Cancel a running report job
GET
/v2/reports/records
Load records synchronously
GET
/v3/media/{file_id}
Download generated report data
Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring the Vonage Reports API by hand means encoding your API key and secret into an HTTP Basic header, then polling asynchronous report jobs against api.nexmo.com and fetching the finished file separately. Through Jentic you install once, import the Reports API from the API Directory, store the key and secret once, and your agent calls it.
Permission scoping
The Reports API puts the report job id in the URL path (/v2/reports/{report_id}), so you choose the operations your agent may call: you can allow it to create and read report jobs while leaving job deletion out of the allowed set unless you add it.
Credential isolation
Your Vonage API key and secret are stored once, encrypted, by your own Jentic One instance and assembled into the Basic auth header at execution time. They never enter the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'export Vonage SMS activity records' and Jentic returns the matching Reports operation with its input schema so the agent can submit and retrieve a job without browsing the reference docs.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Reports API through Jentic.
Why is there no official OpenAPI spec for Reports API?
Vonage does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Reports API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.
What authentication does the Vonage Reports API use?
The Reports API uses HTTP Basic authentication with your Vonage API key as the username and API secret as the password. Through Jentic, those credentials sit encrypted in your Jentic One instance and are injected at execution time, so agents never see the raw secret in their context.
Can I export more than 20 million records in one report?
Vonage recommends capping each asynchronous job at 20 million records by tightening the start_date and end_date parameters on POST /v2/reports. For larger windows, split the range into multiple jobs and chain the downloads through GET /v3/media/{file_id}.
How long does an asynchronous Vonage report take to generate?
Vonage estimates 5-10 minutes per million records for asynchronous jobs. Poll GET /v2/reports/{report_id} until the status field returns SUCCESS, then call GET /v3/media/{file_id} with the file_id from the response to download the CSV.
How do I look up a single SMS or call record without running a bulk job?
Use the synchronous endpoint GET /v2/reports/records with product, account_id, and the relevant message or call ID. This returns the record inline without queueing an asynchronous job, which is the right path for support investigations on a specific message.
How do I run a Vonage Reports job through Jentic?
Run pip install jentic, then use the Jentic search query 'export Vonage activity report' to find POST /v2/reports. Load the schema, execute with product and date range, and chain GET /v2/reports/{report_id} and GET /v3/media/{file_id} as follow-up Jentic calls. Run it through Jentic One, the self-hosted execution layer.
Can I limit what my agent is allowed to do with the Vonage Reports API?
Yes. Because you run Jentic One yourself, your own rules decide which Reports API operations and credentials the agent may use. Since the report job id lives in the URL path at /v2/reports/{report_id}, you can allow the agent to create and read report jobs and download the CSV via GET /v3/media/{file_id} while leaving DELETE /v2/reports/{report_id} job cancellation out of the allowed set unless you add it. Your Vonage API key and secret stay with your instance and are attached at execution time, so the agent only ever calls the operations you permit.
GET STARTED