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.

POST /v1/metric/definitions

JavaScript

JavaScript

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({
  analysisPackageId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
  calculationType: 'LLM_JUDGE',
  name: 'Customer Satisfaction',
  outputType: 'BOOLEAN',
});

console.log(response.data);

201

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "slug": "<string>",
    "variantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "versionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "description": "<string>",
    "calculationType": "PROVIDER",
    "type": "COUNT",
    "scope": "GLOBAL",
    "supportedContexts": [
      "CALL"
    ],
    "unit": {
      "name": "<string>",
      "symbol": "<string>"
    },
    "threshold": {
      "sourceMetricDefinitionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "operator": "GREATER_THAN",
      "thresholdValue": "<string>",
      "aggregationMode": "EACH",
      "countThreshold": 123,
      "sourceParticipantRole": "AGENT",
      "sourceVariantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    },
    "formula": {
      "expression": "<string>",
      "sources": [
        {
          "sourceMetricDefinitionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "sourceVariantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      ]
    },
    "pattern": {
      "operation": "PATTERN_EXISTS",
      "windowMode": "<string>",
      "triggerCombinator": "AND",
      "triggers": [
        {
          "sourceMetricDefinitionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "operator": "GREATER_THAN",
          "thresholdValue": "<string>",
          "sourceParticipantRole": "AGENT",
          "sourceVariantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      ],
      "outcome": {
        "sourceMetricDefinitionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "operator": "GREATER_THAN",
        "thresholdValue": "<string>",
        "sourceParticipantRole": "AGENT",
        "sourceVariantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "windowBefore": 123,
        "windowAfter": 123
      }
    }
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Option 1

Option 2

Option 3

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.

calculationType · string · required

LLM-evaluated metric.

Allowed value: "LLM_JUDGE"

name · string · required

Name of the metric

Required string length: 1 - 100

Example:

"Customer Satisfaction"

outputType · enum<string> · required

Type of value this metric produces

Available options: COUNT, NUMERIC, BOOLEAN, SCALE, TEXT, CLASSIFICATION, OFFSET

Example:

"BOOLEAN"

analysisPackageId · string<uuid> · required

ID of the analysis package to add this metric to

slug · string

Stable slug for the metric. Auto-generated from name if omitted.

Required string length: 1 - 50

Example:

"customer_satisfaction"

scope · enum<string> · default: GLOBAL

Whether metric is global or per-participant (default: GLOBAL)

Available options: GLOBAL, PER_PARTICIPANT

participantRole · enum<string>

Participant role to evaluate. Required when scope is PER_PARTICIPANT.

Available options: AGENT, CUSTOMER, SIMULATED_CUSTOMER, BACKGROUND_SPEAKER

supportedContexts · enum<string>[]

Which levels this metric can produce values at (default: ["CALL"])

Minimum array length: 1

Available options: CALL, SEGMENT, TURN

llmPrompt · string

LLM prompt/criteria for evaluating this metric. Required for BOOLEAN, NUMERIC, TEXT, and SCALE types.

Maximum string length: 2000

Example:

"Evaluate whether the customer expressed satisfaction with the service provided."

booleanTrueLabel · string

Label for the true case (only for BOOLEAN type)

booleanFalseLabel · string

Label for the false case (only for BOOLEAN type)

scaleMin · integer

Minimum value for scale. Required for SCALE type.

Required range: 0 <= x <= 100

scaleMax · integer

Maximum value for scale. Required for SCALE type.

Required range: 0 <= x <= 100

scaleLabels · object[]

Labels for scale ranges (only for SCALE type)

Show child attributes

classificationOptions · object[]

Options for classification. Required for CLASSIFICATION type.

Minimum array length: 1

Show child attributes

maxClassifications · integer

Maximum number of classifications that can be selected (only for CLASSIFICATION type)

Required range: x >= 1

Response

201

application/json

The created metric definition

data · object · required

Metric definition data

Show child attributes