Skip to main content
POST
JavaScript

Authorizations

Authorization
string
header
required

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

Body

application/json

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"

slug
string

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

Required string length: 1 - 50
Example:

"customer_satisfaction"

metricId
string

Alias of slug accepted for backwards compatibility. Use slug for new integrations.

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>[]

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.

Minimum array length: 1
Available options:
CALL,
SEGMENT,
TURN
Example:
llmPrompt
string

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.

Maximum string length: 20000
Example:

"Evaluate whether the customer expressed satisfaction with the service provided.\n\n{{transcript}}\n\nContext: {{world_context}}"

analysisPackageId
string<uuid>

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
string

Label for the true case (only for BOOLEAN type)

booleanFalseLabel
string

Label for the false case (only for BOOLEAN type)

gradesShortCalls
boolean

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
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)

classificationOptions
object[]

Options for classification. Required for CLASSIFICATION type.

Minimum array length: 1
maxClassifications
integer

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

Required range: x >= 1

Response

The created metric definition

data
LLM judge metric · object
required

The created metric definition. The variant is selected by calculationType.