> ## 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. # Create a live report > 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. ## OpenAPI ````yaml /api-reference/openapi.documented.json post /v1/live-report openapi: 3.1.0 info: title: Roark Analytics API description: >- The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform. version: 1.0.0 servers: - description: Production url: https://api.roark.ai security: - Bearer: [] tags: - name: Agent - name: Agent Endpoint - name: Phone Number - name: Call - name: Chat - name: Metric - name: Metric Policy - name: Metric Collection Job - name: Customer Flow - name: Customer Flow Edge Case - name: Simulation - name: Simulation Persona - name: Simulation Environment - name: Simulation Scenario - name: Simulation Run Plan - name: Simulation Template - name: Simulation Run Plan Job - name: Simulation Job - name: HTTP Request Definition - name: Webhook - name: Issue - name: Autoimprove - name: Agent Config - name: Knowledge Base - name: Config - name: Organization Project - name: Organization Project Member - name: Organization Project API Key - name: Organization Config - name: CLI Auth - name: Me - name: Project - name: Usage - name: Analytics - name: Dashboard - name: Live Report - name: Benchmark - name: Health - name: Prospect Simulation paths: /v1/live-report: post: tags: - Live Report summary: Create a live report description: >- 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. operationId: postV1Live-report requestBody: content: application/json: schema: $ref: '#/components/schemas/LiveReportInput' responses: '201': description: The created report content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/LiveReport' required: - data '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Validation error example: type: validation code: invalid_parameter message: The request was invalid param: email description: >- Invalid report: an unknown agent, dashboard or metric, a target its metric cannot be read on, or a bad filter '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication error example: type: authentication code: unauthorized message: Authentication required description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Permission error example: type: forbidden code: permission_denied message: You do not have permission to access this resource description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not found error example: type: not_found code: resource_not_found message: The requested resource could not be found description: Report or document not found '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Conflict error example: type: conflict code: resource_in_use message: The resource is in use and cannot be deleted description: The report is managed by config as code '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Rate limit error example: type: rate_limit code: too_many_requests message: Rate limit exceeded description: Too Many Requests '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Server error example: type: internal code: internal_error message: Internal server error description: Internal Server Error x-codeSamples: - lang: JavaScript source: |- import Roark from '@roarkanalytics/sdk'; const client = new Roark({ bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted }); const liveReport = await client.liveReport.create({ name: 'x' }); console.log(liveReport.data); - lang: Python source: |- import os from roark_analytics import Roark client = Roark( bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"), # This is the default and can be omitted ) live_report = client.live_report.create( name="x", ) print(live_report.data) components: schemas: LiveReportInput: type: object properties: name: type: string minLength: 1 maxLength: 200 description: type: - string - 'null' maxLength: 2000 default: null agentId: type: - string - 'null' format: uuid default: null filters: type: array items: type: object properties: type: type: string enum: - METRIC_PROPERTY - CALL_PROPERTY - AGENT_PROPERTY - CALL_ID - MODALITY - DATASET - METRIC_VALUE description: >- What the filter narrows on. GET /v1/analytics/schema lists each type. property: type: string description: >- The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID. operator: type: string enum: - 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 description: >- 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: anyOf: - type: string - type: number - type: boolean description: >- The value to compare against (an agent id, "call" / "chat", a property value). Required except with IS_SET / IS_NOT_SET. required: - type maxItems: 20 default: [] targets: type: array items: type: object properties: metric: type: string minLength: 1 description: The metric's slug (e.g. `task_completion`) or id. aggregation: type: string enum: - PASS_RATE - AVG - MEDIAN - PERCENTILE - MIN - MAX description: >- Defaults to PASS_RATE for thresholds and booleans, AVG for anything numeric. percentile: type: integer minimum: 1 maximum: 99 description: Required with PERCENTILE, e.g. 95. passOperator: type: string enum: - EQUALS - NOT_EQUALS - GREATER_THAN - GREATER_THAN_OR_EQUAL_TO - LESS_THAN - LESS_THAN_OR_EQUAL_TO description: >- PASS_RATE on a metric that isn't a threshold: the per-call condition a call passes on. passValue: anyOf: - type: string - type: number - type: boolean comparator: type: string enum: - AT_LEAST - AT_MOST description: >- AT_LEAST (default for PASS_RATE) or AT_MOST (default for every other aggregation). value: type: number description: >- The bar, in display units. A PASS_RATE bar is a percentage, 0-100. label: type: string minLength: 1 maxLength: 120 description: Shown instead of the metric's name. required: - metric - value maxItems: 10 default: [] dashboardId: type: - string - 'null' format: uuid default: null cadence: type: string enum: - DAILY - WEEKLY - MONTHLY default: WEEKLY timezone: type: string minLength: 1 default: UTC deliveryHour: type: integer minimum: 0 maximum: 23 default: 9 status: type: string enum: - ACTIVE - PAUSED default: ACTIVE notifications: type: object properties: email: type: object properties: enabled: type: boolean recipients: type: array items: type: string format: email maxItems: 50 required: - enabled - recipients slack: type: array items: type: object properties: channelId: type: string minLength: 1 channelName: type: string minLength: 1 required: - channelId - channelName maxItems: 10 required: - email - slack default: email: enabled: true recipients: [] slack: [] includeTranscriptExcerpts: type: boolean default: true generateNow: type: boolean default: true description: >- Write the report for the latest closed period right away. Default true. required: - name description: >- 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. example: name: Front desk weekly agentId: 0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d filters: - type: CALL_PROPERTY property: region operator: EQUALS value: EU targets: - metric: task_completion_check value: 85 - metric: customer_frustration aggregation: AVG comparator: AT_MOST value: 2 cadence: WEEKLY timezone: Europe/London deliveryHour: 9 notifications: email: enabled: true recipients: [] slack: [] includeTranscriptExcerpts: true generateNow: true LiveReport: type: object properties: id: type: string format: uuid projectId: type: string format: uuid name: type: string description: type: - string - 'null' agentId: type: - string - 'null' format: uuid filters: type: array items: type: object properties: type: type: string enum: - METRIC_PROPERTY - CALL_PROPERTY - AGENT_PROPERTY - CALL_ID - MODALITY - DATASET - METRIC_VALUE description: >- What the filter narrows on. GET /v1/analytics/schema lists each type. property: type: string description: >- The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID. operator: type: string enum: - 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 description: >- 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: anyOf: - type: string - type: number - type: boolean description: >- The value to compare against (an agent id, "call" / "chat", a property value). Required except with IS_SET / IS_NOT_SET. required: - type targets: type: array items: type: object properties: metric: type: string minLength: 1 description: The metric's slug (e.g. `task_completion`) or id. aggregation: type: string enum: - PASS_RATE - AVG - MEDIAN - PERCENTILE - MIN - MAX description: >- Defaults to PASS_RATE for thresholds and booleans, AVG for anything numeric. percentile: type: integer minimum: 1 maximum: 99 description: Required with PERCENTILE, e.g. 95. passOperator: type: string enum: - EQUALS - NOT_EQUALS - GREATER_THAN - GREATER_THAN_OR_EQUAL_TO - LESS_THAN - LESS_THAN_OR_EQUAL_TO description: >- PASS_RATE on a metric that isn't a threshold: the per-call condition a call passes on. passValue: anyOf: - type: string - type: number - type: boolean comparator: type: string enum: - AT_LEAST - AT_MOST description: >- AT_LEAST (default for PASS_RATE) or AT_MOST (default for every other aggregation). value: type: number description: >- The bar, in display units. A PASS_RATE bar is a percentage, 0-100. label: type: string minLength: 1 maxLength: 120 description: Shown instead of the metric's name. required: - metric - value dashboardId: type: - string - 'null' format: uuid cadence: type: string enum: - DAILY - WEEKLY - MONTHLY timezone: type: string deliveryHour: type: integer status: type: string enum: - ACTIVE - PAUSED notifications: type: object properties: email: type: object properties: enabled: type: boolean recipients: type: array items: type: string format: email maxItems: 50 required: - enabled - recipients slack: type: array items: type: object properties: notificationConfigId: type: string format: uuid channelId: type: string channelName: type: string required: - notificationConfigId - channelId - channelName maxItems: 10 fromConfig: type: boolean required: - email - slack includeTranscriptExcerpts: type: boolean configKey: type: - string - 'null' createdAt: type: string updatedAt: type: string configManaged: type: boolean description: 'Managed by config as code: read-only here (edits return 409).' nextDeliveryAt: type: - string - 'null' description: >- When the next scheduled report is written. Null while the report is paused. required: - id - projectId - name - description - agentId - filters - targets - dashboardId - cadence - timezone - deliveryHour - status - notifications - includeTranscriptExcerpts - configKey - createdAt - updatedAt - configManaged - nextDeliveryAt ErrorResponse: type: object properties: type: type: string enum: - validation - authentication - forbidden - not_found - conflict - payment_required - rate_limit - internal description: The error type category examples: - validation - authentication code: type: string description: Machine-readable error code identifier examples: - invalid_parameter - missing_required_field - unauthorized message: type: string description: Human-readable error message examples: - The request was invalid - Authentication required param: type: string description: The parameter that caused the error (if applicable) examples: - email - user_id details: description: Additional error context information required: - type - code - message securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.