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

type

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.

from

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.

filters

object

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

Show Filter object fields

filters.campaign_id

string

Limit the report to data from a specific campaign.

filters.agent_id

string

Limit the report to calls associated with a specific agent.

filters.language

string

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

format

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.

schedule

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

schedule.frequency

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.

schedule.day_of_week

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.

schedule.day_of_month

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.

schedule.time

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.

schedule.email

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

type

string

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

status

string

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

scheduled

boolean

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

limit

integer

default:"20"

Number of results per page. Maximum 100.

offset

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.

​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