Reports API — Generate and Schedule Analytics Reports

The Reports API lets you generate structured, exportable reports from your NeuronLens data — either on demand for ad-hoc analysis or on a recurring schedule delivered to your inbox. Reports can be exported as JSON for further processing, CSV for spreadsheet tools, or PDF for sharing with stakeholders and compliance teams.

Generate a Report

POST /reports Submits a report generation request. Report generation is asynchronous — you receive a report_id immediately and poll for completion using GET /reports/{id}.

Request Body

string

required

The type of report to generate. Each type draws from a different combination of NeuronLens data:

call_summary — total calls, connected calls, dispositions, average duration, by campaign or date.
qa_performance — QA scores broken down by agent, parameter, and campaign. Includes pass rates and trend lines.
compliance_audit — compliance check results, violation log, and severity breakdown for regulatory review.
agent_coaching — per-agent performance summary with lowest-scoring QA parameters and recommended focus areas.
campaign_performance — full campaign-level results including contact reach rate, disposition mix, and sentiment trends.

string

required

ISO 8601 date — start of the reporting period. Example: 2024-01-01.

string

required

ISO 8601 date — end of the reporting period. Example: 2024-01-31.

object

Optional filters to scope the report to a subset of your data.

Show Filter object fields

string

Limit the report to data from a specific campaign.

string

Limit the report to calls associated with a specific agent.

string

Limit the report to calls in a specific BCP-47 language.

string

default:"json"

Output format for the report. One of:

json — structured JSON returned inline in the API response.
csv — tabular CSV file available via a signed download URL.
pdf — formatted PDF suitable for sharing, available via a signed download URL.

object

Optional — configure the report to run on a recurring schedule. If omitted, the report runs once and no schedule is created.

Show Schedule object fields

string

required

How often to regenerate the report. One of: daily, weekly, monthly. The reporting period shifts automatically with each run — a weekly report always covers the 7 days ending the day before the run; a monthly report covers the previous full calendar month.

string

Day of the week to run a weekly report. One of: monday, tuesday, wednesday, thursday, friday, saturday, sunday. Defaults to monday. Ignored for daily and monthly frequencies.

integer

Day of the month (1–28) to run a monthly report. Defaults to 1. Using values above 28 is not supported — to run on the last day of the month, use 28. Ignored for daily and weekly frequencies.

string

UTC time of day at which the report should be generated, in HH:MM 24-hour format. Example: "06:00" for 6:00 AM UTC. Defaults to "00:00" (midnight UTC) if not specified.

string

Email address to deliver the completed report to. A signed download link is included in the email body. Only one recipient address is supported per scheduled report — for multiple recipients, use GET /reports/{id} to retrieve the download URL programmatically and distribute it via your own notification system.

Example Request

curl https://api.vinfer.ai/v1/reports \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "qa_performance",
    "from": "2024-01-01",
    "to": "2024-01-31",
    "filters": {
      "campaign_id": "cmp_4Rv8sT1wX"
    },
    "format": "pdf",
    "schedule": {
      "frequency": "weekly",
      "day_of_week": "monday",
      "time": "06:00",
      "email": "qa-team@yourcompany.com"
    }
  }'

Example Response

{
  "report_id": "rpt_8Xm3kL9wP",
  "type": "qa_performance",
  "status": "generating",
  "format": "pdf",
  "scheduled": true,
  "schedule": {
    "frequency": "weekly",
    "day_of_week": "monday",
    "time": "06:00",
    "email": "qa-team@yourcompany.com",
    "next_run_at": "2024-02-05T06:00:00Z"
  },
  "created_at": "2024-01-31T18:00:00Z"
}

Fetch a Completed Report

GET /reports/{id} Returns the status and results of a report. For csv and pdf formats, a signed download_url is included once the report is ready. For json format, the full report data is embedded inline.

Example Request

curl https://api.vinfer.ai/v1/reports/rpt_8Xm3kL9wP \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response (PDF / CSV Format)

{
  "report_id": "rpt_8Xm3kL9wP",
  "type": "qa_performance",
  "status": "completed",
  "format": "pdf",
  "from": "2024-01-01",
  "to": "2024-01-31",
  "filters": {
    "campaign_id": "cmp_4Rv8sT1wX"
  },
  "download_url": "https://reports.vinfer.ai/signed/rpt_8Xm3kL9wP.pdf?token=eyJ...&expires=1706870400",
  "download_url_expires_at": "2024-02-02T18:00:00Z",
  "page_count": 8,
  "created_at": "2024-01-31T18:00:00Z",
  "completed_at": "2024-01-31T18:00:47Z"
}

Example Response (JSON Format)

{
  "report_id": "rpt_2Jn5pK8qR",
  "type": "qa_performance",
  "status": "completed",
  "format": "json",
  "from": "2024-01-01",
  "to": "2024-01-31",
  "data": {
    "calls_evaluated": 842,
    "overall_score": 85.2,
    "pass_rate": 0.78,
    "trend": [
      {"week": "2024-W01", "overall_score": 82.1, "calls_evaluated": 201},
      {"week": "2024-W02", "overall_score": 84.8, "calls_evaluated": 215},
      {"week": "2024-W03", "overall_score": 86.4, "calls_evaluated": 198},
      {"week": "2024-W04", "overall_score": 87.3, "calls_evaluated": 228}
    ],
    "parameter_breakdown": [
      {"parameter": "Greeting Compliance", "avg_score": 9.4, "max_score": 10, "pass_rate": 0.94},
      {"parameter": "Product Pitch Accuracy", "avg_score": 16.1, "max_score": 20, "pass_rate": 0.72},
      {"parameter": "DND Handling", "avg_score": 9.8, "max_score": 10, "pass_rate": 0.98}
    ]
  },
  "created_at": "2024-01-31T18:00:00Z",
  "completed_at": "2024-01-31T18:00:22Z"
}

Download URLs for PDF and CSV reports are signed and expire after 24 hours. Store the file to your own storage before the URL expires. To regenerate a download URL for an expired report, call this endpoint again — a fresh signed URL is issued as long as the report file is still on VInfer’s servers (retained for 90 days).

List Reports

GET /reports Returns a paginated list of all reports generated in your workspace, ordered by creation date descending.

Query Parameters

string

Filter by report type (e.g., qa_performance, compliance_audit).

string

Filter by report status: generating, completed, or failed.

boolean

When true, return only scheduled (recurring) reports. When false, return only one-time reports.

integer

default:"20"

Number of results per page. Maximum 100.

integer

default:"0"

Number of results to skip for pagination.

Example Request

curl "https://api.vinfer.ai/v1/reports?type=qa_performance&status=completed&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Cancel a Scheduled Report

DELETE /reports/{id}/schedule Cancels the recurring schedule for a report. The report itself (and any previously generated runs) are preserved and still accessible via GET /reports/{id}. Only future scheduled runs are cancelled.

Example Request

curl https://api.vinfer.ai/v1/reports/rpt_8Xm3kL9wP/schedule \
  -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "report_id": "rpt_8Xm3kL9wP",
  "scheduled": false,
  "message": "Recurring schedule cancelled. Previously generated reports remain accessible."
}

Deleting the schedule does not delete the report or any historical runs. To remove report data entirely, contact VInfer support.

End-to-End Example: Weekly QA Performance Report

Here is a complete walkthrough of generating a weekly QA performance report and fetching the result. Step 1 — Generate the report:

curl https://api.vinfer.ai/v1/reports \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "qa_performance",
    "from": "2024-01-22",
    "to": "2024-01-28",
    "format": "json",
    "schedule": {
      "frequency": "weekly",
      "day_of_week": "monday",
      "time": "06:00",
      "email": "qa-team@yourcompany.com"
    }
  }'

{
  "report_id": "rpt_9Yk4nM2sT",
  "status": "generating",
  "format": "json",
  "scheduled": true,
  "schedule": {
    "frequency": "weekly",
    "day_of_week": "monday",
    "time": "06:00",
    "email": "qa-team@yourcompany.com",
    "next_run_at": "2024-01-29T06:00:00Z"
  }
}

Step 2 — Poll until status is completed:

curl https://api.vinfer.ai/v1/reports/rpt_9Yk4nM2sT \
  -H "Authorization: Bearer YOUR_API_KEY"

Step 3 — Read the inline JSON data from the response:

{
  "report_id": "rpt_9Yk4nM2sT",
  "status": "completed",
  "format": "json",
  "from": "2024-01-22",
  "to": "2024-01-28",
  "data": {
    "calls_evaluated": 312,
    "overall_score": 86.1,
    "pass_rate": 0.80,
    "parameter_breakdown": [
      {"parameter": "Greeting Compliance", "avg_score": 9.5, "max_score": 10, "pass_rate": 0.95},
      {"parameter": "Product Pitch Accuracy", "avg_score": 16.8, "max_score": 20, "pass_rate": 0.76},
      {"parameter": "DND Handling", "avg_score": 10.0, "max_score": 10, "pass_rate": 1.00},
      {"parameter": "Escalation Protocol", "avg_score": 8.4, "max_score": 10, "pass_rate": 0.84}
    ]
  },
  "completed_at": "2024-01-28T20:01:05Z"
}

Every Monday at 06:00 UTC, VInfer will automatically regenerate this report for the previous week and email it to qa-team@yourcompany.com. Cancel the schedule at any time with DELETE /reports/rpt_9Yk4nM2sT/schedule.

Overview

Neuron API

NeuronLens API

Reports API — Generate and Schedule Analytics Reports

Generate a Report

Request Body

Example Request

Example Response

Fetch a Completed Report

Example Request

Example Response (PDF / CSV Format)

Example Response (JSON Format)

List Reports

Query Parameters

Example Request

Cancel a Scheduled Report

Example Request

Example Response

End-to-End Example: Weekly QA Performance Report

​Generate a Report

​Request Body

​Example Request

​Example Response

​Fetch a Completed Report

​Example Request

​Example Response (PDF / CSV Format)

​Example Response (JSON Format)

​List Reports

​Query Parameters

​Example Request

​Cancel a Scheduled Report

​Example Request

​Example Response

​End-to-End Example: Weekly QA Performance Report

Generate a Report

Request Body

Example Request

Example Response

Fetch a Completed Report

Example Request

Example Response (PDF / CSV Format)

Example Response (JSON Format)

List Reports

Query Parameters

Example Request

Cancel a Scheduled Report

Example Request

Example Response

End-to-End Example: Weekly QA Performance Report