Create a threshold on a metric

Create a boolean threshold derived from an existing metric. The source metric is addressed by its UUID or its stable slug. The threshold fires when the source metric meets the comparison condition. Scope and supported contexts are inherited from the source metric.

POST /v1/metric/definitions/{idOrSlug}/thresholds

Create a threshold on a metric

cURL

curl --request POST \
  --url https://api.roark.ai/v1/metric/definitions/{idOrSlug}/thresholds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "operator": "GREATER_THAN_OR_EQUALS",
  "value": "4",
  "slug": "customer_satisfaction",
  "metricId": "customer_satisfaction",
  "aggregationMode": "EACH",
  "countThreshold": 1,
  "sourceVariantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

201

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "slug": "<string>",
    "metricId": "<string>",
    "variantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "versionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "description": "<string>",
    "type": "COUNT",
    "scope": "GLOBAL",
    "supportedContexts": [
      "CALL"
    ],
    "supportedConversationSources": [
      "SIMULATED"
    ],
    "requiresLiveConversation": true,
    "supportsVariants": true,
    "calculationType": "THRESHOLD",
    "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"
    }
  }
}

Authorizations

Authorization · string · header · required

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

Path Parameters

idOrSlug · string · required

The metric definition's Roark ID (UUID) or its stable slug (e.g. customer_satisfaction).

Body

application/json

Input for creating a new threshold derived from a source metric.

operator · enum<string> · required

Comparison operator

Available options: GREATER_THAN, GREATER_THAN_OR_EQUALS, LESS_THAN, LESS_THAN_OR_EQUALS, EQUALS, NOT_EQUALS

Example:

"GREATER_THAN_OR_EQUALS"

value · string · required

Value to compare the source metric against (as a string)

Minimum string length: 1

Example:

"4"

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"

aggregationMode · enum<string> · default: EACH

How to aggregate the source metric before applying the comparison (default: EACH)

Available options: EACH, COUNT, AVERAGE, MIN, MAX, MEDIAN, P95, P99, SUM

countThreshold · integer

Required when aggregationMode is COUNT. The threshold fires when the count is met.

Required range: x >= 0

sourceParticipantRole · enum<string>

When the source metric is per-participant, restrict evaluation to this role. Only valid for sources with TURN/SEGMENT contexts.

Available options: AGENT, CUSTOMER, SIMULATED_CUSTOMER, BACKGROUND_SPEAKER

sourceVariantId · string<uuid>

Variant of the source metric to use

Response

201

application/json

The created threshold (as a metric definition)

data · Threshold metric · object · required

Show child attributes