Live reports

A kind: liveReport declares a live call report: 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-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

Live reports are YAML-only for now. A defineLiveReport helper for the TypeScript SDK 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` 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. 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.
`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`. `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` 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` 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’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.

Get started

Resource reference

Fields

Targets

References

In Roark

Removing a report

​Fields

​Targets

​References

​In Roark

​Removing a report

Fields

Targets

References

In Roark

Removing a report