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

# Live Call Reports

> A written report on your production calls every day, week or month: targets, trends, what went wrong and what to do about it

## Overview

A live call report is the report Roark writes after a simulation run, for your production traffic. You pick the calls (an agent, narrowed by filters) and the bar they are held to (targets). When each period closes, Roark reads the period's calls and writes a report you can open in Roark, download as a PDF, or have sent to email and Slack.

Each report answers four questions:

* **Did we hit our targets?** Every target with this period's number, the period before, and whether it was met.
* **What changed?** Call volume, how calls ended, and every check's pass rate against the previous period.
* **What went wrong?** Failure themes, grouped from the calls that failed a target or check, each with how many calls it affected, quoted transcript evidence, and links to the calls.
* **What should we do?** Recommendations tied to the themes, in priority order.

Define a report [in code](https://docs.roark.ai/documentation/config-as-code/live-reports.md), or build it in Roark under **Monitor > Reports**.

***

## Create a report

Open **Reports** in the sidebar and click **New report**. The form walks through six steps; the rail on the left shows what each is set to, and you can jump between them.

**1. Details**

The report's name (how it reads in the list, emails and Slack) and an optional description.

**2. Calls**

The agent whose calls it covers, or every agent in the project, and any filters that narrow them further: a call property, the modality (calls or chats), a dataset, or another metric's value (for example, only calls where the task was completed). Simulations are never included.

**3. Targets**

Up to 10 numbers each period is held to, for example "Task completion pass rate at least 85%" or "p95 latency at most 1,200 ms". A report with no targets still describes the period; targets are what turn it into a verdict.

**4. Schedule**

Daily, weekly or monthly, the timezone the periods are read in, and the local hour the report is sent.

**5. Delivery**

Who gets each report: every project member by email (the default), a list of addresses (people without a Roark account included, since the email carries the PDF), no email, and any Slack channels. You can also turn off transcript excerpts here if transcripts must not leave Roark.

**6. Charts**

Optionally, a [dashboard](https://docs.roark.ai/documentation/observability/dashboards.md) whose charts the report embeds. Its widgets are read over the report's own calls and period, so the charts always match the numbers around them.

> [!TIP]
>
> Use **Write the latest period now** from the report's menu to see a report straight away, rather than waiting for the period to close.

***

## Targets

A target is a metric, an aggregation, and a bar:

| Aggregation | Reads | Bar |
| :- | :- | :- |
| Pass rate | The share of calls that passed | A percentage, 0 to 100 |
| Average, Median | The metric's typical value | In the metric's units |
| Percentile | p50 to p99 of the metric's value | In the metric's units |
| Min, Max | The extreme value | In the metric's units |

A [threshold](https://docs.roark.ai/documentation/metrics/thresholds.md)'s pass rate uses the threshold's own condition. For any other metric, a pass-rate target also takes the condition a call passes on (for example, "sentiment at least 6"). A target is met when the period's number is **at least** the bar (the default for pass rates) or **at most** it (the default for everything else, such as latency).

Each target is also read per agent, so a report covering several agents shows which one is pulling the number down.

***

## Schedule and periods

A report covers whole calendar periods in its timezone: a day, a Monday-to-Sunday week, or a calendar month. It is written once the period has closed, at the delivery hour on the following day. A weekly report set to 08:00 in `America/Chicago` covers Monday to Sunday and arrives on Monday at 08:00 Chicago time.

Each report is compared with the period before it: a week with the previous week, a month with the previous month. A comparison is only drawn when both periods have enough calls to make it meaningful.

Pause a report from its menu to stop new reports without deleting it. When you resume it, the next report covers the most recent closed period; the periods it was paused for are not written retroactively, but you can still write the latest one on demand.

***

## Reading a report

| Section | What it shows |
| :- | :- |
| **Verdict** | One paragraph on how the period went, with targets met and the headline change. |
| **Targets** | Each target this period and last, met or missed. |
| **Failure themes** | What went wrong, grouped from the failing calls, with how many calls each affected, a quote from the transcript, and links to the calls. A theme that is already an open issue in **Issues** links to it. |
| **Recommendations** | What to change, in priority order, tied to the themes behind them. |
| **By agent** | The busiest agents, with each target read for them alone. |
| **Checks** | Every metric the period's calls were graded on, worst pass rate first. |
| **Volume** | Calls in scope over the period, and how they ended. |
| **Charts** | The linked dashboard's widgets, over this period's calls. |
| **Appendix** | How the report was put together: how many calls were read, how themes were counted, and anything the report could not read. |

When many calls fail, Roark reads a representative sample of them and weights each theme back to the full count, so "affects about 340 calls" means 340 of the period's calls, not 340 of the sample. The appendix says how many calls were read.

Use the period picker to open an earlier report. Every report also has a **Download PDF**; links in emails and Slack open the report they were sent for, even if the report definition is later deleted.

***

## API and CLI

Everything in the form is available over the API, so a report can be created from a script or a deployment pipeline.

| Operation | Endpoint | CLI |
| :- | :- | :- |
| List reports | `GET /v1/live-report` | `roark live-report list` |
| Create a report | `POST /v1/live-report` | `roark live-report create` |
| Get a report | `GET /v1/live-report/{reportId}` | `roark live-report get` |
| Update a report | `PATCH /v1/live-report/{reportId}` | `roark live-report update` |
| Delete a report | `DELETE /v1/live-report/{reportId}` | `roark live-report delete` |
| Write the latest period now | `POST /v1/live-report/{reportId}/generate` | `roark live-report run` |
| List written reports | `GET /v1/live-report/{reportId}/document` | `roark live-report document list` |
| Get a written report | `GET /v1/live-report/{reportId}/document/{documentId}` | `roark live-report document get` |

```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
curl -X POST https://api.roark.ai/v1/live-report \
  -H "Authorization: Bearer $ROARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Frontdesk weekly review",
    "agentId": "6f1c2a8e-3b4d-4e5f-8a9b-0c1d2e3f4a5b",
    "filters": [{ "type": "MODALITY", "value": "call" }],
    "targets": [
      { "metric": "task_completion", "aggregation": "PASS_RATE", "value": 85 },
      { "metric": "response_latency_ms", "aggregation": "PERCENTILE", "percentile": 95, "value": 1200 }
    ],
    "cadence": "WEEKLY",
    "timezone": "America/Chicago",
    "deliveryHour": 8,
    "notifications": {
      "email": { "enabled": true, "recipients": ["ops@example.com"] },
      "slack": []
    }
  }'
```

A written report's document carries the same content as the page: the verdict, targets, themes with their evidence, recommendations, per-agent rows and checks, so you can feed it into your own tooling. See the [API reference](https://docs.roark.ai/api-reference/introduction.md) for every field.

> [!NOTE]
>
> A report defined in [config as code](https://docs.roark.ai/documentation/config-as-code/live-reports.md) is read-only in Roark and over the API: edits and deletes return `409`. Anyone can still write the latest period on demand.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.