> ## Documentation Index
> Fetch the complete documentation index at: https://kb.vinfer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Reports API — Generate and Schedule Analytics Reports

> Generate on-demand performance reports or schedule recurring reports for call analytics, QA, compliance, and agent coaching from NeuronLens.

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

<code>POST /reports</code>

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

<ParamField body="type" 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.
</ParamField>

<ParamField body="from" type="string" required>
  ISO 8601 date — start of the reporting period. Example: `2024-01-01`.
</ParamField>

<ParamField body="to" type="string" required>
  ISO 8601 date — end of the reporting period. Example: `2024-01-31`.
</ParamField>

<ParamField body="filters" type="object">
  Optional filters to scope the report to a subset of your data.

  <Expandable title="Filter object fields">
    <ParamField body="filters.campaign_id" type="string">
      Limit the report to data from a specific campaign.
    </ParamField>

    <ParamField body="filters.agent_id" type="string">
      Limit the report to calls associated with a specific agent.
    </ParamField>

    <ParamField body="filters.language" type="string">
      Limit the report to calls in a specific BCP-47 language.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="format" type="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.
</ParamField>

<ParamField body="schedule" type="object">
  Optional — configure the report to run on a recurring schedule. If omitted, the report runs once and no schedule is created.

  <Expandable title="Schedule object fields">
    <ParamField body="schedule.frequency" type="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.
    </ParamField>

    <ParamField body="schedule.day_of_week" type="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.
    </ParamField>

    <ParamField body="schedule.day_of_month" type="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.
    </ParamField>

    <ParamField body="schedule.time" type="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.
    </ParamField>

    <ParamField body="schedule.email" type="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.
    </ParamField>
  </Expandable>
</ParamField>

### Example Request

```bash theme={null}
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

```json theme={null}
{
  "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

<code>GET /reports/\{id}</code>

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

```bash theme={null}
curl https://api.vinfer.ai/v1/reports/rpt_8Xm3kL9wP \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response (PDF / CSV Format)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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"
}
```

<Warning>
  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).
</Warning>

***

## List Reports

<code>GET /reports</code>

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

### Query Parameters

<ParamField query="type" type="string">
  Filter by report type (e.g., `qa_performance`, `compliance_audit`).
</ParamField>

<ParamField query="status" type="string">
  Filter by report status: `generating`, `completed`, or `failed`.
</ParamField>

<ParamField query="scheduled" type="boolean">
  When `true`, return only scheduled (recurring) reports. When `false`, return only one-time reports.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Number of results per page. Maximum `100`.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of results to skip for pagination.
</ParamField>

### Example Request

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

***

## Cancel a Scheduled Report

<code>DELETE /reports/\{id}/schedule</code>

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

```bash theme={null}
curl https://api.vinfer.ai/v1/reports/rpt_8Xm3kL9wP/schedule \
  -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "report_id": "rpt_8Xm3kL9wP",
  "scheduled": false,
  "message": "Recurring schedule cancelled. Previously generated reports remain accessible."
}
```

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

***

## 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:**

```bash theme={null}
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"
    }
  }'
```

```json theme={null}
{
  "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`:**

```bash theme={null}
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:**

```json theme={null}
{
  "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`.