> ## 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 metric definition

> Create a new metric definition. The `calculationType` field selects the variant: LLM_JUDGE (LLM-evaluated), FORMULA (computed from a math expression over other metrics), or PATTERN (detects a trigger→outcome pattern within a window). To create a threshold on top of an existing metric, use `POST /metric/definitions/{idOrSlug}/thresholds` instead.



## OpenAPI

````yaml /api-reference/openapi.documented.json post /v1/metric/definitions
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: Health
    x-displayName: Health
  - name: Authentication
    x-displayName: Current credential
  - name: Project API Key
    x-displayName: Project API keys
  - name: Personal API Key
    x-displayName: Personal API keys
  - name: Agent
    x-displayName: Agents
  - name: Agent Endpoint
    x-displayName: Endpoints
  - name: Tool
    x-displayName: Tools
  - name: Agent Setup
    x-displayName: Automatic test setup
  - name: Autoimprove
    x-displayName: Autoimprove
  - name: Customer Flow
    x-displayName: Customer flows
  - name: Customer Flow Folder
    x-displayName: Customer flow folders
  - name: Simulation Persona
    x-displayName: Personas
  - name: Simulation Environment
    x-displayName: Environments
  - name: Simulation Template
    x-displayName: Templates
  - name: Simulation Run Plan
    x-displayName: Plans
  - name: Simulation Run
    x-displayName: Runs
  - name: Simulation Tool Mock
    x-displayName: Tool mocks and fixtures
  - name: Metric
    x-displayName: Definitions
  - name: Metric Variant
    x-displayName: Variants
  - name: Metric Policy
    x-displayName: Policies
  - name: Metric Collection Job
    x-displayName: Collection jobs
  - name: Call
    x-displayName: Calls
  - name: Chat
    x-displayName: Chats
  - name: Customer
    x-displayName: Customers
  - name: Issue
    x-displayName: Issues
  - name: Analytics
    x-displayName: Analytics
  - name: Dashboard
    x-displayName: Dashboards
  - name: Live Report
    x-displayName: Reports
  - name: Agent Connection
    x-displayName: Agent platforms
  - name: Calendar Connection
    x-displayName: Calendars
  - name: MCP Server Connection
    x-displayName: MCP servers
  - name: Knowledge Base
    x-displayName: Knowledge bases
  - name: HTTP Request Definition
    x-displayName: HTTP request definitions
  - name: Webhook
    x-displayName: Webhooks
  - name: Config
    x-displayName: Config as code
  - name: Organization Project
    x-displayName: Projects
  - name: Organization Project Member
    x-displayName: Project members
  - name: Usage
    x-displayName: Usage
  - name: Benchmark
    x-displayName: Benchmarks
paths:
  /v1/metric/definitions:
    post:
      tags:
        - Metric
      summary: Create a metric definition
      description: >-
        Create a new metric definition. The `calculationType` field selects the
        variant: LLM_JUDGE (LLM-evaluated), FORMULA (computed from a math
        expression over other metrics), or PATTERN (detects a trigger→outcome
        pattern within a window). To create a threshold on top of an existing
        metric, use `POST /metric/definitions/{idOrSlug}/thresholds` instead.
      operationId: postV1MetricDefinitions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMetricDefinitionInput'
      responses:
        '201':
          description: The created metric definition
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CreateMetricDefinitionResponse'
                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: Bad Request
        '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
        '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 response = await client.metric.createDefinition({
              calculationType: 'LLM_JUDGE',
              name: 'Customer Satisfaction',
              outputType: 'BOOLEAN',
            });

            console.log(response.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
            )
            response = client.metric.create_definition(
                calculation_type="LLM_JUDGE",
                name="Customer Satisfaction",
                output_type="BOOLEAN",
            )
            print(response.data)
components:
  schemas:
    CreateMetricDefinitionInput:
      oneOf:
        - $ref: '#/components/schemas/PromptMetricInput'
        - $ref: '#/components/schemas/FormulaMetricInput'
        - $ref: '#/components/schemas/PatternMetricInput'
        - $ref: '#/components/schemas/HttpRequestMetricInput'
      discriminator:
        propertyName: calculationType
        mapping:
          LLM_JUDGE: '#/components/schemas/PromptMetricInput'
          FORMULA: '#/components/schemas/FormulaMetricInput'
          PATTERN: '#/components/schemas/PatternMetricInput'
          HTTP_REQUEST: '#/components/schemas/HttpRequestMetricInput'
      description: >-
        Input for creating a new metric definition. `calculationType` selects
        the variant and defaults to LLM_JUDGE when omitted (legacy prompt-metric
        payloads remain valid). To create a threshold, use the threshold
        sub-resource.
    CreateMetricDefinitionResponse:
      oneOf:
        - $ref: '#/components/schemas/LlmJudgeMetricResponse'
        - $ref: '#/components/schemas/FormulaMetricResponse'
        - $ref: '#/components/schemas/PatternMetricResponse'
        - $ref: '#/components/schemas/HttpRequestMetricResponse'
      discriminator:
        propertyName: calculationType
        mapping:
          LLM_JUDGE: '#/components/schemas/LlmJudgeMetricResponse'
          FORMULA: '#/components/schemas/FormulaMetricResponse'
          PATTERN: '#/components/schemas/PatternMetricResponse'
          HTTP_REQUEST: '#/components/schemas/HttpRequestMetricResponse'
      description: >-
        The created metric definition. The variant is selected by
        `calculationType`.
    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
    PromptMetricInput:
      type: object
      properties:
        calculationType:
          type: string
          const: LLM_JUDGE
          description: LLM-evaluated metric.
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Name of the metric
          example: Customer Satisfaction
        slug:
          type: string
          minLength: 1
          maxLength: 50
          description: Stable slug for the metric. Auto-generated from name if omitted.
          example: customer_satisfaction
        metricId:
          type: string
          minLength: 1
          maxLength: 50
          description: >-
            Alias of `slug` accepted for backwards compatibility. Use `slug` for
            new integrations.
          example: customer_satisfaction
        outputType:
          type: string
          enum:
            - COUNT
            - NUMERIC
            - BOOLEAN
            - SCALE
            - TEXT
            - CLASSIFICATION
            - OFFSET
          description: Type of value this metric produces
          example: BOOLEAN
        scope:
          type: string
          enum:
            - GLOBAL
            - PER_PARTICIPANT
          default: GLOBAL
          description: 'Whether metric is global or per-participant (default: GLOBAL)'
        participantRole:
          type: string
          enum:
            - AGENT
            - CUSTOMER
            - SIMULATED_CUSTOMER
            - BACKGROUND_SPEAKER
          description: >-
            Participant role to evaluate. Required when scope is
            PER_PARTICIPANT.
        supportedContexts:
          type: array
          items:
            type: string
            enum:
              - CALL
              - SEGMENT
              - TURN
          minItems: 1
          default:
            - CALL
          description: >-
            What the judge grades (default: ["CALL"], the whole conversation).
            ["CALL", "SEGMENT"] also grades each utterance of `participantRole`;
            ["CALL", "TURN"] also grades each agent reply to the caller
            (requires `participantRole: AGENT`). Per-utterance and per-reply
            grading needs `scope: PER_PARTICIPANT` and a BOOLEAN, SCALE, NUMERIC
            or COUNT output; the CALL value stays the graded result and the
            per-unit values are its evidence.
          example:
            - CALL
            - TURN
        llmPrompt:
          type: string
          maxLength: 20000
          description: >-
            LLM prompt/criteria for evaluating this metric. Required for
            BOOLEAN, NUMERIC, TEXT, and SCALE types. A custom metric prompt must
            include a transcript variable such as `{{transcript}}` and
            `{{world_context}}`, which gives the judge the current date and time
            when it grades.
          example: >-
            Evaluate whether the customer expressed satisfaction with the
            service provided.


            {{transcript}}


            Context: {{world_context}}
        analysisPackageId:
          type: string
          format: uuid
          description: >-
            ID of the analysis package to add this metric to. Optional: when
            omitted, the metric is added to a default "Custom Metrics" package
            for your project (created automatically the first time).
        booleanTrueLabel:
          type: string
          description: Label for the true case (only for BOOLEAN type)
        booleanFalseLabel:
          type: string
          description: Label for the false case (only for BOOLEAN type)
        gradesShortCalls:
          type: boolean
          description: >-
            Score this metric on a simulated call with fewer than 4 transcript
            lines or where your agent never spoke (custom metrics only, not ones
            that judge the audio). Such calls skip every other metric. Default
            false.
        scaleMin:
          type: integer
          minimum: 0
          maximum: 100
          description: Minimum value for scale. Required for SCALE type.
        scaleMax:
          type: integer
          minimum: 0
          maximum: 100
          description: Maximum value for scale. Required for SCALE type.
        scaleLabels:
          type: array
          items:
            type: object
            properties:
              rangeMin:
                type: number
                description: Minimum value for this label range
              rangeMax:
                type: number
                description: Maximum value for this label range
              label:
                type: string
                description: Label for this range
              description:
                type: string
                description: Description of what this range means
              displayOrder:
                type: integer
                description: Display order of this label
              colorHex:
                type: string
                description: Hex color code for this label (e.g. "#FF0000")
            required:
              - rangeMin
              - rangeMax
              - label
              - displayOrder
          description: Labels for scale ranges (only for SCALE type)
        classificationOptions:
          type: array
          items:
            type: object
            properties:
              label:
                type: string
              description:
                type: string
              displayOrder:
                type: integer
            required:
              - label
              - description
              - displayOrder
            description: Option for classification metrics.
          minItems: 1
          description: Options for classification. Required for CLASSIFICATION type.
        maxClassifications:
          type: integer
          minimum: 1
          description: >-
            Maximum number of classifications that can be selected (only for
            CLASSIFICATION type)
      required:
        - calculationType
        - name
        - outputType
      title: LLM judge metric
    FormulaMetricInput:
      type: object
      properties:
        calculationType:
          type: string
          const: FORMULA
          description: >-
            Metric computed by evaluating a mathematical expression over other
            metrics.
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Name of the metric
          example: Customer Satisfaction
        slug:
          type: string
          minLength: 1
          maxLength: 50
          description: Stable slug for the metric. Auto-generated from name if omitted.
          example: customer_satisfaction
        metricId:
          type: string
          minLength: 1
          maxLength: 50
          description: >-
            Alias of `slug` accepted for backwards compatibility. Use `slug` for
            new integrations.
          example: customer_satisfaction
        outputType:
          type: string
          enum:
            - NUMERIC
            - BOOLEAN
          description: >-
            Output type of the formula. NUMERIC for arithmetic expressions,
            BOOLEAN for comparison expressions.
          example: NUMERIC
        formula:
          type: string
          minLength: 1
          maxLength: 500
          description: >-
            Formula expression using `{{id:<uuid>}}` references to source
            metrics. Operators depend on output type: +, -, *, / for NUMERIC;
            ==, !=, >=, <=, >, < for BOOLEAN.
          example: >-
            {{id:00000000-0000-0000-0000-000000000001}} /
            {{id:00000000-0000-0000-0000-000000000002}}
        sources:
          type: array
          items:
            type: object
            properties:
              sourceMetricDefinitionId:
                type: string
                format: uuid
                description: ID of a metric referenced in the formula
              sourceVariantId:
                type: string
                format: uuid
                description: Variant of the source metric to use
            required:
              - sourceMetricDefinitionId
          minItems: 2
          description: Source metrics referenced by the formula. Minimum 2.
        analysisPackageId:
          type: string
          format: uuid
          description: >-
            ID of the analysis package to add this metric to. Optional: when
            omitted, the metric is added to a default "Custom Metrics" package
            for your project (created automatically the first time).
      required:
        - calculationType
        - name
        - outputType
        - formula
        - sources
      title: Formula metric
    PatternMetricInput:
      type: object
      properties:
        calculationType:
          type: string
          const: PATTERN
          description: >-
            Metric detecting temporal patterns: a trigger condition followed by
            an outcome within a window.
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Name of the metric
          example: Customer Satisfaction
        slug:
          type: string
          minLength: 1
          maxLength: 50
          description: Stable slug for the metric. Auto-generated from name if omitted.
          example: customer_satisfaction
        metricId:
          type: string
          minLength: 1
          maxLength: 50
          description: >-
            Alias of `slug` accepted for backwards compatibility. Use `slug` for
            new integrations.
          example: customer_satisfaction
        operation:
          type: string
          enum:
            - PATTERN_EXISTS
            - PATTERN_COUNT
            - OUTCOME_AGGREGATE
          description: >-
            Pattern operation. PATTERN_EXISTS produces a BOOLEAN; PATTERN_COUNT
            produces a NUMERIC count; OUTCOME_AGGREGATE aggregates a numeric
            outcome.
          example: PATTERN_EXISTS
        windowMode:
          type: string
          enum:
            - seconds
            - segments
          default: seconds
          description: 'Unit for trigger/outcome window values (default: seconds)'
        trigger:
          type: object
          properties:
            sourceMetricDefinitionId:
              type: string
              format: uuid
            operator:
              type: string
              enum:
                - GREATER_THAN
                - GREATER_THAN_OR_EQUALS
                - LESS_THAN
                - LESS_THAN_OR_EQUALS
                - EQUALS
                - NOT_EQUALS
            thresholdValue:
              type: string
              minLength: 1
            sourceParticipantRole:
              type: string
              enum:
                - AGENT
                - CUSTOMER
                - SIMULATED_CUSTOMER
                - BACKGROUND_SPEAKER
            sourceVariantId:
              type: string
              format: uuid
          required:
            - sourceMetricDefinitionId
            - operator
            - thresholdValue
          description: >-
            Single trigger condition. Use either trigger or triggers +
            triggerCombinator.
        triggers:
          type: array
          items:
            type: object
            properties:
              sourceMetricDefinitionId:
                type: string
                format: uuid
              operator:
                type: string
                enum:
                  - GREATER_THAN
                  - GREATER_THAN_OR_EQUALS
                  - LESS_THAN
                  - LESS_THAN_OR_EQUALS
                  - EQUALS
                  - NOT_EQUALS
              thresholdValue:
                type: string
                minLength: 1
              sourceParticipantRole:
                type: string
                enum:
                  - AGENT
                  - CUSTOMER
                  - SIMULATED_CUSTOMER
                  - BACKGROUND_SPEAKER
              sourceVariantId:
                type: string
                format: uuid
            required:
              - sourceMetricDefinitionId
              - operator
              - thresholdValue
          minItems: 1
          description: Multiple trigger conditions. Use with triggerCombinator.
        triggerCombinator:
          type: string
          enum:
            - AND
            - OR
          description: >-
            How to combine multiple triggers. Required when triggers has more
            than 1 entry.
        outcome:
          type: object
          properties:
            sourceMetricDefinitionId:
              type: string
              format: uuid
            operator:
              type: string
              enum:
                - GREATER_THAN
                - GREATER_THAN_OR_EQUALS
                - LESS_THAN
                - LESS_THAN_OR_EQUALS
                - EQUALS
                - NOT_EQUALS
            thresholdValue:
              type: string
              minLength: 1
            sourceParticipantRole:
              type: string
              enum:
                - AGENT
                - CUSTOMER
                - SIMULATED_CUSTOMER
                - BACKGROUND_SPEAKER
            sourceVariantId:
              type: string
              format: uuid
            windowAfter:
              type: integer
              minimum: 0
              description: >-
                How far after the trigger to look for the outcome (in seconds or
                segments, see windowMode)
            windowBefore:
              type: integer
              minimum: 0
              description: 'How far before the trigger to look for the outcome (default: 0)'
          required:
            - sourceMetricDefinitionId
            - operator
            - thresholdValue
            - windowAfter
          description: >-
            Outcome condition evaluated within the window relative to the
            trigger.
        analysisPackageId:
          type: string
          format: uuid
          description: >-
            ID of the analysis package to add this metric to. Optional: when
            omitted, the metric is added to a default "Custom Metrics" package
            for your project (created automatically the first time).
      required:
        - calculationType
        - name
        - operation
        - outcome
      title: Pattern metric
    HttpRequestMetricInput:
      type: object
      properties:
        calculationType:
          type: string
          const: HTTP_REQUEST
          description: >-
            BOOLEAN metric answered by your own endpoint. Roark sends a request
            about each call, live or simulated, and your endpoint answers
            {"passed": true | false, "reason": "..."}.
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Name of the metric
          example: Customer Satisfaction
        slug:
          type: string
          minLength: 1
          maxLength: 50
          description: Stable slug for the metric. Auto-generated from name if omitted.
          example: customer_satisfaction
        metricId:
          type: string
          minLength: 1
          maxLength: 50
          description: >-
            Alias of `slug` accepted for backwards compatibility. Use `slug` for
            new integrations.
          example: customer_satisfaction
        httpRequest:
          type: object
          properties:
            url:
              type: string
              minLength: 1
              maxLength: 2048
              description: >-
                Public http(s) URL. May contain {{path}} placeholders into the
                request payload, which are URL-encoded.
              example: https://api.example.com/roark/checks/pin-changed
            method:
              type: string
              enum:
                - GET
                - POST
              default: POST
              description: GET or POST (default POST). A GET request has no body.
            headers:
              type: object
              propertyNames:
                type: string
                minLength: 1
                maxLength: 200
              additionalProperties:
                type: string
                maxLength: 4000
              description: >-
                Request headers, for example your own Authorization header.
                Values may contain placeholders.
              example:
                Authorization: Bearer sk_live_...
            body:
              type:
                - string
                - 'null'
              minLength: 1
              maxLength: 20000
              description: >-
                A JSON template with {{path}} placeholders into the request
                payload, such as {"cardId": "{{call.properties.cardId}}"}. Omit
                or pass null to send the default payload.
          required:
            - url
          title: HTTP request metric request
          description: >-
            The request to send. With no body, Roark POSTs the default payload:
            { version, requestId, metric, call, simulation }.
        analysisPackageId:
          type: string
          format: uuid
          description: >-
            ID of the analysis package to add this metric to. Optional: when
            omitted, the metric is added to a default "Custom Metrics" package
            for your project (created automatically the first time).
        booleanTrueLabel:
          type: string
          description: 'What a passed check is called (default: Pass)'
        booleanFalseLabel:
          type: string
          description: 'What a failed check is called (default: Fail)'
        gradesShortCalls:
          type: boolean
          description: >-
            Score this metric on a simulated call with fewer than 4 transcript
            lines or where your agent never spoke (custom metrics only, not ones
            that judge the audio). Such calls skip every other metric. Default
            false.
      required:
        - calculationType
        - name
        - httpRequest
      title: HTTP request metric
    LlmJudgeMetricResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the metric definition
        slug:
          type: string
          description: Stable metric slug (e.g. "call_reason", "customer_satisfaction")
        metricId:
          type: string
          description: >-
            Alias of `slug` retained for backwards compatibility. Same value as
            `slug`.
        variantId:
          type: string
          format: uuid
          description: >-
            The resolved variant this response reflects (org-scoped Default if
            the org has customized it, otherwise the system Default). Pass this
            as sourceVariantId when building a derived metric off this one to
            pin the exact config.
        versionId:
          type: string
          format: uuid
          description: >-
            The variant's current version. Immutable snapshot of the config —
            editing the metric produces a new versionId. Use it to detect config
            changes.
        name:
          type: string
          description: Name of the metric
        description:
          type: string
          description: Description of what the metric measures
        type:
          type: string
          enum:
            - COUNT
            - NUMERIC
            - BOOLEAN
            - SCALE
            - TEXT
            - CLASSIFICATION
            - OFFSET
          description: Type of value this metric produces
        scope:
          type: string
          enum:
            - GLOBAL
            - PER_PARTICIPANT
          description: Whether metric is global or per-participant
        supportedContexts:
          type: array
          items:
            type: string
            enum:
              - CALL
              - SEGMENT
              - TURN
          description: Which levels this metric can produce values at
        supportedConversationSources:
          type:
            - array
            - 'null'
          items:
            type: string
            enum:
              - SIMULATED
              - LIVE
          description: >-
            Which kinds of conversation this metric can be scored on. `null`
            means both. `["LIVE"]` marks a metric that can only be scored from
            your own recording of a real call, and `["SIMULATED"]` one that only
            applies to simulations.
        gradesShortCalls:
          type: boolean
          description: >-
            Whether a simulation scores this metric on a call with fewer than 4
            transcript lines or where your agent never spoke. Such calls skip
            every metric without it.
        requiresLiveConversation:
          type: boolean
          description: >-
            True when this metric can only be scored from a live recording
            (`supportedConversationSources` is `["LIVE"]`). Selecting one of
            these on a simulation run forces live enrichment: the run waits for
            your recording and, if none arrives, the metric produces no value.
            Check this before a run rather than discovering the wait afterwards.
        supportsVariants:
          type: boolean
          description: >-
            Whether you can create a variant of this metric with `POST
            /v1/metric/definitions/{idOrSlug}/variants`. False for threshold
            metrics (their configuration comes from the metric they derive
            from), for HTTP request metrics (their configuration is the request,
            edited on the metric), for provider-computed metrics whose
            calculation lives in the collector rather than an editable prompt,
            and for metrics in a package that manages its own variants. Most of
            Roark’s own metrics are false, so read this rather than discovering
            it from a 403.
        unit:
          type: object
          properties:
            name:
              type: string
              description: Name of the unit
            symbol:
              type:
                - string
                - 'null'
              description: Symbol for the unit
          required:
            - name
            - symbol
          description: Unit information if applicable
        evidenceSource:
          type:
            - object
            - 'null'
          properties:
            metricId:
              type: string
              description: >-
                Slug of the metric whose per-turn values are the evidence behind
                this count or rate
            countsWhen:
              type: boolean
              description: >-
                The per-turn value this metric tallies. `false` for an
                "incorrect" count over an appropriateness metric, `true` for a
                count of a boolean event.
          required:
            - metricId
            - countsWhen
          description: >-
            For a Roark count or rate summed from the per-turn verdicts of a
            sibling metric (for example `incorrect_barge_in_yield_count` over
            `barge_in_yield_appropriateness`): where the reasoning and
            transcript positions live. The count value itself carries neither.
            `null` for a metric that is its own evidence.
        calculationType:
          type: string
          const: LLM_JUDGE
          description: Metric evaluated by an LLM against a prompt.
        llmPrompt:
          type:
            - string
            - 'null'
          description: >-
            The rubric this judge applies, as stored. Read it back to confirm
            which criteria are live after a create or update.
        booleanTrueLabel:
          type:
            - string
            - 'null'
          description: >-
            For a BOOLEAN metric, what a `true` value means. Also given to the
            judge as its polarity rule.
        booleanFalseLabel:
          type:
            - string
            - 'null'
          description: >-
            For a BOOLEAN metric, what a `false` value means. Also given to the
            judge as its polarity rule.
      required:
        - id
        - slug
        - metricId
        - variantId
        - versionId
        - name
        - description
        - type
        - scope
        - supportedContexts
        - supportedConversationSources
        - gradesShortCalls
        - requiresLiveConversation
        - supportsVariants
        - evidenceSource
        - calculationType
        - llmPrompt
        - booleanTrueLabel
        - booleanFalseLabel
      title: LLM judge metric
    FormulaMetricResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the metric definition
        slug:
          type: string
          description: Stable metric slug (e.g. "call_reason", "customer_satisfaction")
        metricId:
          type: string
          description: >-
            Alias of `slug` retained for backwards compatibility. Same value as
            `slug`.
        variantId:
          type: string
          format: uuid
          description: >-
            The resolved variant this response reflects (org-scoped Default if
            the org has customized it, otherwise the system Default). Pass this
            as sourceVariantId when building a derived metric off this one to
            pin the exact config.
        versionId:
          type: string
          format: uuid
          description: >-
            The variant's current version. Immutable snapshot of the config —
            editing the metric produces a new versionId. Use it to detect config
            changes.
        name:
          type: string
          description: Name of the metric
        description:
          type: string
          description: Description of what the metric measures
        type:
          type: string
          enum:
            - COUNT
            - NUMERIC
            - BOOLEAN
            - SCALE
            - TEXT
            - CLASSIFICATION
            - OFFSET
          description: Type of value this metric produces
        scope:
          type: string
          enum:
            - GLOBAL
            - PER_PARTICIPANT
          description: Whether metric is global or per-participant
        supportedContexts:
          type: array
          items:
            type: string
            enum:
              - CALL
              - SEGMENT
              - TURN
          description: Which levels this metric can produce values at
        supportedConversationSources:
          type:
            - array
            - 'null'
          items:
            type: string
            enum:
              - SIMULATED
              - LIVE
          description: >-
            Which kinds of conversation this metric can be scored on. `null`
            means both. `["LIVE"]` marks a metric that can only be scored from
            your own recording of a real call, and `["SIMULATED"]` one that only
            applies to simulations.
        gradesShortCalls:
          type: boolean
          description: >-
            Whether a simulation scores this metric on a call with fewer than 4
            transcript lines or where your agent never spoke. Such calls skip
            every metric without it.
        requiresLiveConversation:
          type: boolean
          description: >-
            True when this metric can only be scored from a live recording
            (`supportedConversationSources` is `["LIVE"]`). Selecting one of
            these on a simulation run forces live enrichment: the run waits for
            your recording and, if none arrives, the metric produces no value.
            Check this before a run rather than discovering the wait afterwards.
        supportsVariants:
          type: boolean
          description: >-
            Whether you can create a variant of this metric with `POST
            /v1/metric/definitions/{idOrSlug}/variants`. False for threshold
            metrics (their configuration comes from the metric they derive
            from), for HTTP request metrics (their configuration is the request,
            edited on the metric), for provider-computed metrics whose
            calculation lives in the collector rather than an editable prompt,
            and for metrics in a package that manages its own variants. Most of
            Roark’s own metrics are false, so read this rather than discovering
            it from a 403.
        unit:
          type: object
          properties:
            name:
              type: string
              description: Name of the unit
            symbol:
              type:
                - string
                - 'null'
              description: Symbol for the unit
          required:
            - name
            - symbol
          description: Unit information if applicable
        evidenceSource:
          type:
            - object
            - 'null'
          properties:
            metricId:
              type: string
              description: >-
                Slug of the metric whose per-turn values are the evidence behind
                this count or rate
            countsWhen:
              type: boolean
              description: >-
                The per-turn value this metric tallies. `false` for an
                "incorrect" count over an appropriateness metric, `true` for a
                count of a boolean event.
          required:
            - metricId
            - countsWhen
          description: >-
            For a Roark count or rate summed from the per-turn verdicts of a
            sibling metric (for example `incorrect_barge_in_yield_count` over
            `barge_in_yield_appropriateness`): where the reasoning and
            transcript positions live. The count value itself carries neither.
            `null` for a metric that is its own evidence.
        calculationType:
          type: string
          const: FORMULA
          description: Metric computed by evaluating an expression over other metrics.
        formula:
          $ref: '#/components/schemas/FormulaMetricDetails'
          description: Formula configuration.
      required:
        - id
        - slug
        - metricId
        - variantId
        - versionId
        - name
        - description
        - type
        - scope
        - supportedContexts
        - supportedConversationSources
        - gradesShortCalls
        - requiresLiveConversation
        - supportsVariants
        - evidenceSource
        - calculationType
        - formula
      title: Formula metric
    PatternMetricResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the metric definition
        slug:
          type: string
          description: Stable metric slug (e.g. "call_reason", "customer_satisfaction")
        metricId:
          type: string
          description: >-
            Alias of `slug` retained for backwards compatibility. Same value as
            `slug`.
        variantId:
          type: string
          format: uuid
          description: >-
            The resolved variant this response reflects (org-scoped Default if
            the org has customized it, otherwise the system Default). Pass this
            as sourceVariantId when building a derived metric off this one to
            pin the exact config.
        versionId:
          type: string
          format: uuid
          description: >-
            The variant's current version. Immutable snapshot of the config —
            editing the metric produces a new versionId. Use it to detect config
            changes.
        name:
          type: string
          description: Name of the metric
        description:
          type: string
          description: Description of what the metric measures
        type:
          type: string
          enum:
            - COUNT
            - NUMERIC
            - BOOLEAN
            - SCALE
            - TEXT
            - CLASSIFICATION
            - OFFSET
          description: Type of value this metric produces
        scope:
          type: string
          enum:
            - GLOBAL
            - PER_PARTICIPANT
          description: Whether metric is global or per-participant
        supportedContexts:
          type: array
          items:
            type: string
            enum:
              - CALL
              - SEGMENT
              - TURN
          description: Which levels this metric can produce values at
        supportedConversationSources:
          type:
            - array
            - 'null'
          items:
            type: string
            enum:
              - SIMULATED
              - LIVE
          description: >-
            Which kinds of conversation this metric can be scored on. `null`
            means both. `["LIVE"]` marks a metric that can only be scored from
            your own recording of a real call, and `["SIMULATED"]` one that only
            applies to simulations.
        gradesShortCalls:
          type: boolean
          description: >-
            Whether a simulation scores this metric on a call with fewer than 4
            transcript lines or where your agent never spoke. Such calls skip
            every metric without it.
        requiresLiveConversation:
          type: boolean
          description: >-
            True when this metric can only be scored from a live recording
            (`supportedConversationSources` is `["LIVE"]`). Selecting one of
            these on a simulation run forces live enrichment: the run waits for
            your recording and, if none arrives, the metric produces no value.
            Check this before a run rather than discovering the wait afterwards.
        supportsVariants:
          type: boolean
          description: >-
            Whether you can create a variant of this metric with `POST
            /v1/metric/definitions/{idOrSlug}/variants`. False for threshold
            metrics (their configuration comes from the metric they derive
            from), for HTTP request metrics (their configuration is the request,
            edited on the metric), for provider-computed metrics whose
            calculation lives in the collector rather than an editable prompt,
            and for metrics in a package that manages its own variants. Most of
            Roark’s own metrics are false, so read this rather than discovering
            it from a 403.
        unit:
          type: object
          properties:
            name:
              type: string
              description: Name of the unit
            symbol:
              type:
                - string
                - 'null'
              description: Symbol for the unit
          required:
            - name
            - symbol
          description: Unit information if applicable
        evidenceSource:
          type:
            - object
            - 'null'
          properties:
            metricId:
              type: string
              description: >-
                Slug of the metric whose per-turn values are the evidence behind
                this count or rate
            countsWhen:
              type: boolean
              description: >-
                The per-turn value this metric tallies. `false` for an
                "incorrect" count over an appropriateness metric, `true` for a
                count of a boolean event.
          required:
            - metricId
            - countsWhen
          description: >-
            For a Roark count or rate summed from the per-turn verdicts of a
            sibling metric (for example `incorrect_barge_in_yield_count` over
            `barge_in_yield_appropriateness`): where the reasoning and
            transcript positions live. The count value itself carries neither.
            `null` for a metric that is its own evidence.
        calculationType:
          type: string
          const: PATTERN
          description: >-
            Metric detecting a trigger condition followed by an outcome within a
            window.
        pattern:
          $ref: '#/components/schemas/PatternMetricDetails'
          description: Pattern configuration.
      required:
        - id
        - slug
        - metricId
        - variantId
        - versionId
        - name
        - description
        - type
        - scope
        - supportedContexts
        - supportedConversationSources
        - gradesShortCalls
        - requiresLiveConversation
        - supportsVariants
        - evidenceSource
        - calculationType
        - pattern
      title: Pattern metric
    HttpRequestMetricResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the metric definition
        slug:
          type: string
          description: Stable metric slug (e.g. "call_reason", "customer_satisfaction")
        metricId:
          type: string
          description: >-
            Alias of `slug` retained for backwards compatibility. Same value as
            `slug`.
        variantId:
          type: string
          format: uuid
          description: >-
            The resolved variant this response reflects (org-scoped Default if
            the org has customized it, otherwise the system Default). Pass this
            as sourceVariantId when building a derived metric off this one to
            pin the exact config.
        versionId:
          type: string
          format: uuid
          description: >-
            The variant's current version. Immutable snapshot of the config —
            editing the metric produces a new versionId. Use it to detect config
            changes.
        name:
          type: string
          description: Name of the metric
        description:
          type: string
          description: Description of what the metric measures
        type:
          type: string
          enum:
            - COUNT
            - NUMERIC
            - BOOLEAN
            - SCALE
            - TEXT
            - CLASSIFICATION
            - OFFSET
          description: Type of value this metric produces
        scope:
          type: string
          enum:
            - GLOBAL
            - PER_PARTICIPANT
          description: Whether metric is global or per-participant
        supportedContexts:
          type: array
          items:
            type: string
            enum:
              - CALL
              - SEGMENT
              - TURN
          description: Which levels this metric can produce values at
        supportedConversationSources:
          type:
            - array
            - 'null'
          items:
            type: string
            enum:
              - SIMULATED
              - LIVE
          description: >-
            Which kinds of conversation this metric can be scored on. `null`
            means both. `["LIVE"]` marks a metric that can only be scored from
            your own recording of a real call, and `["SIMULATED"]` one that only
            applies to simulations.
        gradesShortCalls:
          type: boolean
          description: >-
            Whether a simulation scores this metric on a call with fewer than 4
            transcript lines or where your agent never spoke. Such calls skip
            every metric without it.
        requiresLiveConversation:
          type: boolean
          description: >-
            True when this metric can only be scored from a live recording
            (`supportedConversationSources` is `["LIVE"]`). Selecting one of
            these on a simulation run forces live enrichment: the run waits for
            your recording and, if none arrives, the metric produces no value.
            Check this before a run rather than discovering the wait afterwards.
        supportsVariants:
          type: boolean
          description: >-
            Whether you can create a variant of this metric with `POST
            /v1/metric/definitions/{idOrSlug}/variants`. False for threshold
            metrics (their configuration comes from the metric they derive
            from), for HTTP request metrics (their configuration is the request,
            edited on the metric), for provider-computed metrics whose
            calculation lives in the collector rather than an editable prompt,
            and for metrics in a package that manages its own variants. Most of
            Roark’s own metrics are false, so read this rather than discovering
            it from a 403.
        unit:
          type: object
          properties:
            name:
              type: string
              description: Name of the unit
            symbol:
              type:
                - string
                - 'null'
              description: Symbol for the unit
          required:
            - name
            - symbol
          description: Unit information if applicable
        evidenceSource:
          type:
            - object
            - 'null'
          properties:
            metricId:
              type: string
              description: >-
                Slug of the metric whose per-turn values are the evidence behind
                this count or rate
            countsWhen:
              type: boolean
              description: >-
                The per-turn value this metric tallies. `false` for an
                "incorrect" count over an appropriateness metric, `true` for a
                count of a boolean event.
          required:
            - metricId
            - countsWhen
          description: >-
            For a Roark count or rate summed from the per-turn verdicts of a
            sibling metric (for example `incorrect_barge_in_yield_count` over
            `barge_in_yield_appropriateness`): where the reasoning and
            transcript positions live. The count value itself carries neither.
            `null` for a metric that is its own evidence.
        calculationType:
          type: string
          const: HTTP_REQUEST
          description: >-
            BOOLEAN metric answered by your own endpoint: Roark sends a request
            about each call and records the {"passed", "reason"} it answers
            with.
        httpRequest:
          oneOf:
            - $ref: '#/components/schemas/HttpRequestMetricDetails'
            - type: 'null'
          description: The request this metric sends.
        booleanTrueLabel:
          type:
            - string
            - 'null'
          description: What a passed check is called
        booleanFalseLabel:
          type:
            - string
            - 'null'
          description: What a failed check is called
      required:
        - id
        - slug
        - metricId
        - variantId
        - versionId
        - name
        - description
        - type
        - scope
        - supportedContexts
        - supportedConversationSources
        - gradesShortCalls
        - requiresLiveConversation
        - supportsVariants
        - evidenceSource
        - calculationType
        - httpRequest
        - booleanTrueLabel
        - booleanFalseLabel
      title: HTTP request metric
    FormulaMetricDetails:
      type: object
      properties:
        expression:
          type: string
        sources:
          type: array
          items:
            type: object
            properties:
              sourceMetricDefinitionId:
                type: string
                format: uuid
              sourceVariantId:
                type:
                  - string
                  - 'null'
                format: uuid
            required:
              - sourceMetricDefinitionId
              - sourceVariantId
      required:
        - expression
        - sources
    PatternMetricDetails:
      type: object
      properties:
        operation:
          type: string
          enum:
            - PATTERN_EXISTS
            - PATTERN_COUNT
            - OUTCOME_AGGREGATE
        windowMode:
          type:
            - string
            - 'null'
        triggerCombinator:
          type:
            - string
            - 'null'
          enum:
            - AND
            - OR
        triggers:
          type: array
          items:
            type: object
            properties:
              sourceMetricDefinitionId:
                type: string
                format: uuid
              operator:
                type: string
                enum:
                  - GREATER_THAN
                  - GREATER_THAN_OR_EQUALS
                  - LESS_THAN
                  - LESS_THAN_OR_EQUALS
                  - EQUALS
                  - NOT_EQUALS
              thresholdValue:
                type: string
              sourceParticipantRole:
                type:
                  - string
                  - 'null'
                enum:
                  - AGENT
                  - CUSTOMER
                  - SIMULATED_CUSTOMER
                  - BACKGROUND_SPEAKER
              sourceVariantId:
                type:
                  - string
                  - 'null'
                format: uuid
            required:
              - sourceMetricDefinitionId
              - operator
              - thresholdValue
              - sourceParticipantRole
              - sourceVariantId
        outcome:
          type:
            - object
            - 'null'
          properties:
            sourceMetricDefinitionId:
              type: string
              format: uuid
            operator:
              type: string
              enum:
                - GREATER_THAN
                - GREATER_THAN_OR_EQUALS
                - LESS_THAN
                - LESS_THAN_OR_EQUALS
                - EQUALS
                - NOT_EQUALS
            thresholdValue:
              type: string
            sourceParticipantRole:
              type:
                - string
                - 'null'
              enum:
                - AGENT
                - CUSTOMER
                - SIMULATED_CUSTOMER
                - BACKGROUND_SPEAKER
            sourceVariantId:
              type:
                - string
                - 'null'
              format: uuid
            windowBefore:
              type:
                - integer
                - 'null'
            windowAfter:
              type:
                - integer
                - 'null'
          required:
            - sourceMetricDefinitionId
            - operator
            - thresholdValue
            - sourceParticipantRole
            - sourceVariantId
            - windowBefore
            - windowAfter
      required:
        - operation
        - windowMode
        - triggerCombinator
        - triggers
        - outcome
    HttpRequestMetricDetails:
      type: object
      properties:
        url:
          type: string
          description: The URL the request is sent to, placeholders included
        method:
          type: string
          enum:
            - GET
            - POST
        headers:
          type: object
          additionalProperties:
            type: string
          description: Request headers as key-value pairs
        body:
          type:
            - string
            - 'null'
          description: The JSON body template, or null when the default payload is sent
      required:
        - url
        - method
        - headers
        - body
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

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