---
title: "Create a live report"
method: POST
path: "/v1/live-report"
tags: ["Live Report"]
---

# Create a live report

`POST /v1/live-report`

## Request

- Base URL: `https://api.roark.ai`
- URL: `https://api.roark.ai/v1/live-report`
- Auth: HTTP bearer

Saves a report on the project's live calls. Simulations are never included.

Targets are analytics measures held to a bar: a threshold metric is read as its pass rate (`value` is a
percentage, 0-100, held AT_LEAST by default); a numeric metric as its average (held AT_MOST by default).
Every target is read for the period and the period before it, so the report says whether each was met
and how it moved.

Scheduled reports are written `deliveryHour` hours into the day after each period ends in `timezone`
(a week runs Monday to Sunday), then emailed and posted per `notifications`. With `generateNow` (the
default) the report for the latest closed period is written right away and not sent.

## Request body

- LiveReportInput: A report on the project's live calls: which calls (one agent or all, plus conversation filters in the analytics vocabulary), the targets the period is held to, how often it is written, and who receives it.
  - `name` string, required
  - `description` string, nullable
  - `agentId` string, uuid, nullable
  - `filters` object[]
    - `type` 'METRIC_PROPERTY' | 'CALL_PROPERTY' | 'AGENT_PROPERTY' | 'CALL_ID' | 'MODALITY' | 'DATASET' | 'METRIC_VALUE', required: What the filter narrows on. GET /v1/analytics/schema lists each type.
    - `property` string: The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID.
    - `operator` 'EQUALS' | 'NOT_EQUALS' | 'GREATER_THAN' | 'GREATER_THAN_OR_EQUAL_TO' | 'LESS_THAN' | 'LESS_THAN_OR_EQUAL_TO' | 'CONTAINS' | 'STARTS_WITH' | 'IS_SET' | 'IS_NOT_SET': Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value.
    - `value` union: The value to compare against (an agent id, "call" / "chat", a property value). Required except with IS_SET / IS_NOT_SET.
      - string
      - number
      - boolean
  - `targets` object[]
    - `metric` string, required: The metric's slug (e.g. `task_completion`) or id.
    - `aggregation` 'PASS_RATE' | 'AVG' | 'MEDIAN' | 'PERCENTILE' | 'MIN' | 'MAX': Defaults to PASS_RATE for thresholds and booleans, AVG for anything numeric.
    - `percentile` integer: Required with PERCENTILE, e.g. 95.
    - `passOperator` 'EQUALS' | 'NOT_EQUALS' | 'GREATER_THAN' | 'GREATER_THAN_OR_EQUAL_TO' | 'LESS_THAN' | 'LESS_THAN_OR_EQUAL_TO': PASS_RATE on a metric that isn't a threshold: the per-call condition a call passes on.
    - `passValue` union
      - string
      - number
      - boolean
    - `comparator` 'AT_LEAST' | 'AT_MOST': AT_LEAST (default for PASS_RATE) or AT_MOST (default for every other aggregation).
    - `value` number, required: The bar, in display units. A PASS_RATE bar is a percentage, 0-100.
    - `label` string: Shown instead of the metric's name.
  - `dashboardId` string, uuid, nullable
  - `cadence` 'DAILY' | 'WEEKLY' | 'MONTHLY'
  - `timezone` string
  - `deliveryHour` integer
  - `status` 'ACTIVE' | 'PAUSED'
  - `notifications` object
    - `email` object, required
      - `enabled` boolean, required
      - `recipients` string[], required
    - `slack` object[], required
      - `channelId` string, required
      - `channelName` string, required
  - `includeTranscriptExcerpts` boolean
  - `generateNow` boolean: Write the report for the latest closed period right away. Default true.

## Response `201`

The created report

- object
  - `data` LiveReport, required
    - `id` string, uuid, required
    - `projectId` string, uuid, required
    - `name` string, required
    - `description` string, nullable, required
    - `agentId` string, uuid, nullable, required
    - `filters` object[], required
      - `type` 'METRIC_PROPERTY' | 'CALL_PROPERTY' | 'AGENT_PROPERTY' | 'CALL_ID' | 'MODALITY' | 'DATASET' | 'METRIC_VALUE', required: What the filter narrows on. GET /v1/analytics/schema lists each type.
      - `property` string: The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID.
      - `operator` 'EQUALS' | 'NOT_EQUALS' | 'GREATER_THAN' | 'GREATER_THAN_OR_EQUAL_TO' | 'LESS_THAN' | 'LESS_THAN_OR_EQUAL_TO' | 'CONTAINS' | 'STARTS_WITH' | 'IS_SET' | 'IS_NOT_SET': Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value.
      - `value` union: The value to compare against (an agent id, "call" / "chat", a property value). Required except with IS_SET / IS_NOT_SET.
        - string
        - number
        - boolean
    - `targets` object[], required
      - `metric` string, required: The metric's slug (e.g. `task_completion`) or id.
      - `aggregation` 'PASS_RATE' | 'AVG' | 'MEDIAN' | 'PERCENTILE' | 'MIN' | 'MAX': Defaults to PASS_RATE for thresholds and booleans, AVG for anything numeric.
      - `percentile` integer: Required with PERCENTILE, e.g. 95.
      - `passOperator` 'EQUALS' | 'NOT_EQUALS' | 'GREATER_THAN' | 'GREATER_THAN_OR_EQUAL_TO' | 'LESS_THAN' | 'LESS_THAN_OR_EQUAL_TO': PASS_RATE on a metric that isn't a threshold: the per-call condition a call passes on.
      - `passValue` union
        - string
        - number
        - boolean
      - `comparator` 'AT_LEAST' | 'AT_MOST': AT_LEAST (default for PASS_RATE) or AT_MOST (default for every other aggregation).
      - `value` number, required: The bar, in display units. A PASS_RATE bar is a percentage, 0-100.
      - `label` string: Shown instead of the metric's name.
    - `dashboardId` string, uuid, nullable, required
    - `cadence` 'DAILY' | 'WEEKLY' | 'MONTHLY', required
    - `timezone` string, required
    - `deliveryHour` integer, required
    - `status` 'ACTIVE' | 'PAUSED', required
    - `notifications` object, required
      - `email` object, required
        - `enabled` boolean, required
        - `recipients` string[], required
      - `slack` object[], required
        - `notificationConfigId` string, uuid, required
        - `channelId` string, required
        - `channelName` string, required
      - `fromConfig` boolean
    - `includeTranscriptExcerpts` boolean, required
    - `configKey` string, nullable, required
    - `createdAt` string, required
    - `updatedAt` string, required
    - `configManaged` boolean, required: Managed by config as code: read-only here (edits return 409).
    - `nextDeliveryAt` string, nullable, required: When the next scheduled report is written. Null while the report is paused.

## Other responses

- `400`: Invalid report: an unknown agent, dashboard or metric, a target its metric cannot be read on, or a bad filter
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Report or document not found
- `409`: The report is managed by config as code
- `429`: Too Many Requests
- `500`: Internal Server Error

## Changes

> 188 revisions in range; 1 not diffed.

- **2026-11-03** `1a91a5c90e44`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/live-report/post.md)

---

[API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) - [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roarkhq/apis/roark-analytics-api/revisions/efc3377249d1?raw)