> ## 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 reports

> Declare a recurring report on your production calls: which calls, the targets they are held to, when it is written and who gets it

A `kind: liveReport` declares a [live call report](https://docs.roark.ai/documentation/observability/live-reports.md): the calls it covers (an agent, narrowed by filters), the targets each period is held to, its cadence, and who it is sent to. When each period closes, Roark writes the report: targets met and missed, what changed since the period before, failure themes with quoted evidence, and recommendations.

Applying a report never writes one. Roark writes a report when each period closes, or when someone asks for the latest period from Roark, the API or `roark live-report run`.

```yaml theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
# yaml-language-server: $schema=https://roark.ai/roark-config.schema.json
kind: liveReport
name: frontdesk-weekly
displayName: Frontdesk weekly review
description: How the frontdesk agent handled last week's production calls.
agent: frontdesk                   # a kind: agent in this config, or an agent made in Roark, by name
filters:
  - { type: MODALITY, value: call }
targets:
  - { metric: task_completion, aggregation: PASS_RATE, value: 85 }
  - { metric: response_latency_ms, aggregation: PERCENTILE, percentile: 95, value: 1200, label: p95 latency }
  - { metric: sentiment_score, aggregation: PASS_RATE, passOperator: GREATER_THAN_OR_EQUAL_TO, passValue: 6, value: 70 }
cadence: WEEKLY
timezone: America/Chicago
deliveryHour: 8                    # Monday 08:00 Chicago time, for the Monday-to-Sunday week
notify:
  email: [ops@example.com, cx-lead@example.com]
  slack:
    - { channelId: C0123ABCD, channelName: cx-reports }
dashboard: frontdesk-health        # embed this dashboard's charts, read over the report's calls
```

> [!NOTE]
>
> Live reports are YAML-only for now. A `defineLiveReport` helper for the [TypeScript SDK](https://docs.roark.ai/documentation/config-as-code/typescript.md) is on the way.

***

## Fields

| Field | Required | |
| :- | :- | :- |
| `name` | yes | The config name. |
| `displayName` | no | The report's title in Roark, emails and Slack. Defaults to `name`. |
| `description` | no | Free text. |
| `agent` | no | The agent whose calls it covers: a [`kind: agent`](https://docs.roark.ai/documentation/config-as-code/agents) in this config, or an agent made in Roark, by name. Left out, the report covers every agent in the project. |
| `filters` | no | Up to 20, narrowing the calls further: `CALL_PROPERTY`, `MODALITY`, `DATASET` or `METRIC_VALUE`, in the same shape as [dashboard filters](https://docs.roark.ai/documentation/config-as-code/dashboards.md#filters). Simulations are never included, and the agent is set with `agent`, not a filter (an `AGENT_PROPERTY` or `CALL_PROPERTY agent_id` filter is refused). |
| `targets` | no | Up to 10. See [Targets](#targets). |
| `cadence` | no | `DAILY`, `WEEKLY` (the default, Monday to Sunday) or `MONTHLY`. |
| `timezone` | no | The IANA zone periods and the delivery hour are read in. Defaults to `UTC`. |
| `deliveryHour` | no | The local hour, `0` to `23`, the report is sent on the day after its period closes. Defaults to `9`. |
| `enabled` | no | `false` pauses the report without deleting it. Defaults to `true`. |
| `notify` | no | Who gets each report, in the same shape as a [plan's `notify`](https://docs.roark.ai/documentation/config-as-code/simulation-plans). `email: true` (the default) emails every project member, `false` sends no email, and a list names the addresses, Roark users or not (the email carries the PDF). `slack` lists channels on the project's connected Slack workspace. |
| `includeTranscriptExcerpts` | no | Quote short transcript passages as evidence. Defaults to `true`; set `false` where transcripts must not leave Roark. |
| `dashboard` | no | A dashboard whose charts the report embeds: a [`kind: dashboard`](https://docs.roark.ai/documentation/config-as-code/dashboards) in this config, by config name, or a dashboard made in Roark, by its title. |

Every field is defaulted, so deleting a line reverts it rather than keeping the last value: removing `dashboard` unlinks it, and removing `notify` goes back to emailing every project member.

### Targets

| Field | Required | |
| :- | :- | :- |
| `metric` | yes | A metric slug: a [`kind: metric`](https://docs.roark.ai/documentation/config-as-code/metrics) in this config, or any metric the project can see. |
| `value` | yes | The bar, in display units. A `PASS_RATE` bar is a percentage, `0` to `100`. |
| `aggregation` | no | `PASS_RATE`, `AVG`, `MEDIAN`, `PERCENTILE`, `MIN` or `MAX`. Defaults to `PASS_RATE` for thresholds and booleans, `AVG` for anything numeric. |
| `percentile` | with `PERCENTILE` | `1` to `99`, for example `95`. |
| `passOperator`, `passValue` | with `PASS_RATE` on a metric that isn't a threshold | The condition a call passes on: `EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN` or `LESS_THAN_OR_EQUAL_TO`, and the value it compares with. |
| `comparator` | no | `AT_LEAST` (the default for a pass rate) or `AT_MOST` (the default for every other aggregation). |
| `label` | no | Shown instead of the metric's name. |

A [threshold](https://docs.roark.ai/documentation/config-as-code/metrics.md#thresholds)'s pass rate uses the threshold's own condition, so it takes no `passOperator`.

A target on a metric that doesn't exist, or one the metric can't answer (an average of a classification), fails that report's apply with the reason and leaves the report as it was.

***

## References

Live reports are applied after everything they name: metrics, agents and dashboards, so a report can name a metric, agent or dashboard defined in the same config. A dashboard that a report in your config still embeds is never pruned: removing the dashboard alone fails with the report named. Remove `dashboard:` from the report, or remove both together.

***

## In Roark

A report created by config shows as managed by config. It is read-only in Roark and over the API (edits, pause and delete return `409`): change it in your config and re-apply. Anyone can still open its reports, download the PDF, and write the latest period on demand.

A report made in Roark with the same title as a `kind: liveReport` (its `displayName`, or `name`) is adopted on the first apply rather than duplicated. Titles are unique in a project, ignoring case.

***

## Removing a report

Deleting a report from your config (with prune on, the default) deletes the report: no more reports are written or sent. Reports it already wrote stay readable from the emails and Slack messages that delivered them.


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