Metric Store

Define custom metrics, evaluate conversations with AI, and query metric values across all channels.

The metric store computes, stores, and serves metrics across all channels from a single config-driven pipeline. 41 built-in metrics ship with every workspace. Custom metrics can be added through the settings API without code changes.

Metric Settings

Metric definitions are stored in workspace settings. The settings API lets you view all definitions (built-in and custom) and add or modify custom ones.

Get Metric Definitions

GET /v1/{workspace_id}/settings/metrics

Returns all metric definitions for the workspace, including the built-in metrics and any custom definitions.

curl

curl -H "Authorization: Bearer $API_KEY" \
  "https://api.platform.amigo.ai/v1/$WORKSPACE_ID/settings/metrics"

Python

TypeScript

Response:

{
  "definitions": [
    {
      "key": "voice_quality_score",
      "name": "Voice Quality Score",
      "metric_type": "numerical",
      "source": "call_intelligence",
      "extraction_mode": "static",
      "extract_path": "$.quality_score",
      "aggregation": "avg",
      "unit": "score",
      "active": true,
      "builtin": true
    }
  ]
}

Create or Update Custom Metrics

PUT /v1/{workspace_id}/settings/metrics

Replaces the custom metric definitions for the workspace. Built-in metrics are preserved automatically - you only need to include your custom definitions.

curl

curl -X PUT \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "definitions": [
      {
        "key": "empathy_score",
        "name": "Agent Empathy",
        "description": "How empathetic was the agent during the conversation",
        "metric_type": "numerical",
        "source": "call_intelligence",
        "event_types": ["call_intelligence.row"],
        "extraction_mode": "ai_query",
        "model_tier": "balanced",
        "ai_query_prompt": "Rate how empathetic the agent was on a scale of 1-10. Consider whether the agent acknowledged concerns, showed understanding, and responded with appropriate sensitivity. Output ONLY a single integer from 1 to 10.",
        "aggregation": "avg",
        "unit": "score",
        "valid_range_min": 1.0,
        "valid_range_max": 10.0
      }
    ]
  }' \
  "https://api.platform.amigo.ai/v1/$WORKSPACE_ID/settings/metrics"

Python

Permissions: Admin or Owner role required.

Metric Definition Fields

Field	Required	Description
key	Yes	Unique identifier. Lowercase alphanumeric and underscores (^[a-z][a-z0-9_]*$). Max 64 characters.
name	Yes	Display name. Max 256 characters.
description	No	Human-readable description. Max 2000 characters.
metric_type	Yes	numerical, categorical, or boolean
source	Yes	Data source. See Sources below.
event_types	Yes	Event types to scan. For call_intelligence source, use ["call_intelligence.row"].
extraction_mode	No	How to extract the value. Default: static. See Extraction Modes.
model_tier	No	AI model tier: free, fast, balanced, max, custom. Default: free. For ai_query, set to fast, balanced, or max (or provide ai_query_endpoint).
ai_query_endpoint	No	Model serving endpoint override for ai_query. If omitted, the platform resolves the endpoint from model_tier. Max 256 characters.
ai_query_prompt	Conditional	Prompt template for ai_query mode. Required when extraction_mode is ai_query. Max 8000 characters.
extract_path	Conditional	JSON path for static mode (e.g., $.quality_score).
ai_labels	Conditional	Labels for ai_classify (categories) and ai_extract (field names). Required for ai_classify; ai_extract requires ai_labels or ai_schema.
ai_schema	Conditional	Extraction schema object for ai_extract mode (alternative to ai_labels).
categories	No	Allowed category values for categorical metrics (e.g., ["scheduling", "billing", "other"]).
aggregation	No	Aggregation function: count, sum, avg, min, max, count_distinct, ratio, rate. Default: count.
unit	No	Display unit (e.g., score, %, seconds). Max 32 characters.
period_granularity	No	hourly or daily. Default: daily.
channel_scope	No	all, voice, text, surface, inbound, outbound. Default: all.
valid_range_min	No	Minimum valid value for numerical metrics. Values below are dropped.
valid_range_max	No	Maximum valid value for numerical metrics. Values above are dropped.
active	No	Set to false to disable without deleting. Default: true.

Sources

Source	What It Reads
call_intelligence	Call and text conversation summaries. Use for evaluating conversation quality, outcomes, and agent behavior.
world_events	All events across all domains. Use for event-level metrics.
surface_events	Form submission lifecycle events.
emotion_events	Audio emotion analysis events.
connector_events	Data connector sync events.
zerobus_events	Streaming-ingestion events (voice calls, SMS messages, LLM usage).
voice_judge_results	Audio-native voice quality scores.
custom	Extension source; set custom_source_key to target a custom event stream.

Extraction Modes

Mode	Cost	Description
static	Free	Extract a value from a known JSON path in the event data.
ai_classify	Free	Classify content into predefined categories. Requires ai_labels.
ai_extract	Free	Extract structured fields from text. Requires ai_labels.
ai_query	Varies	Run a custom prompt against conversation data. Requires model_tier and ai_query_prompt.
sql_expr	Free	Raw SQL expression. Not available for custom metrics (security).

Custom metrics cannot use extraction_mode: "sql_expr" due to SQL injection risk. Use ai_query for complex evaluations.

Query Metric Values

Computed metric values are available through four query endpoints. Values are computed by the batch pipeline (hourly for AI metrics, continuously for static metrics) and synced to the operational database.

List Latest Values

GET /v1/{workspace_id}/metrics

Returns the most recent value for each metric.

Parameter	Type	Default	Description
source	string	production	production, simulation, or all
scope	string	aggregate	aggregate (workspace-level), entity (per-call), or all
entity_type	string	-	Filter by entity type (e.g., call)
entity_id	string	-	Filter by specific entity
service_id	string	-	Filter by service
run_id	string	-	Filter by simulation run
session_id	string	-	Filter by session (CallSid)

Get Metric Values

GET /v1/{workspace_id}/metrics/{metric_key}

Returns values for a specific metric with optional time range.

Parameter	Type	Default	Description
date_from	datetime	-	Start of range (ISO-8601)
date_to	datetime	-	End of range (ISO-8601)
limit	integer	90	Max values to return (1-365)

Get Metric Trend

GET /v1/{workspace_id}/metrics/{metric_key}/trend

Returns time-series data for dashboard visualizations.

Parameter	Type	Default	Description
days	integer	30	Lookback window (1-365)

Metric Catalog

GET /v1/{workspace_id}/metrics/catalog

Lists all available metrics (built-in and custom) with their configuration.

Custom Metric Examples

Conversation Empathy Score

A numerical metric that rates how empathetic the agent was during each conversation.

{
  "key": "empathy_score",
  "name": "Agent Empathy",
  "metric_type": "numerical",
  "source": "call_intelligence",
  "event_types": ["call_intelligence.row"],
  "extraction_mode": "ai_query",
  "model_tier": "balanced",
  "ai_query_prompt": "Rate how empathetic the agent was during this conversation on a scale of 1-10. Consider: did the agent acknowledge patient concerns, show understanding, and respond with appropriate emotional sensitivity? Output ONLY a single integer from 1 to 10.",
  "aggregation": "avg",
  "unit": "score",
  "valid_range_min": 1.0,
  "valid_range_max": 10.0
}

Protocol Adherence Check

A boolean metric that checks whether the agent followed the required clinical protocol.

{
  "key": "protocol_followed",
  "name": "Protocol Adherence",
  "metric_type": "boolean",
  "source": "call_intelligence",
  "event_types": ["call_intelligence.row"],
  "extraction_mode": "ai_query",
  "model_tier": "balanced",
  "ai_query_prompt": "Did the agent follow the standard clinical intake protocol? The protocol requires: (1) verify patient identity, (2) confirm reason for call, (3) collect or verify insurance information, (4) schedule or confirm next steps. Respond with exactly: true or false.",
  "aggregation": "rate",
  "unit": "rate"
}

Call Topic Classification

A categorical metric that classifies the primary reason for each call.

{
  "key": "call_topic",
  "name": "Call Topic",
  "metric_type": "categorical",
  "source": "call_intelligence",
  "event_types": ["call_intelligence.row"],
  "extraction_mode": "ai_query",
  "model_tier": "fast",
  "ai_query_prompt": "What was the primary topic of this conversation? Respond with exactly one of: scheduling, billing, clinical_question, prescription, referral, complaint, other.",
  "aggregation": "count",
  "unit": "count",
  "categories": ["scheduling", "billing", "clinical_question", "prescription", "referral", "complaint", "other"]
}

Lifecycle

Custom metrics follow this lifecycle:

1. Define - Create the metric definition via PUT /settings/metrics.
2. Deploy - Once the definition is saved, the batch pipeline picks it up automatically on the next hourly run. No deployment or code change needed.
3. Query - After the first pipeline run, values appear in GET /metrics/{key} and the metric catalog. Dashboard panels can visualize the new metric immediately.
4. Iterate - Update the prompt or extraction settings via PUT /settings/metrics. Changes take effect on the next pipeline run.

The batch pipeline runs hourly. After defining a new metric, the first computed values appear within one hour.

Limits

Limit	Value
Custom metrics per workspace	50
ai_query_prompt length	8,000 characters
Conversations evaluated per metric per run	500 (most recent)
Evaluation lookback window	24 hours

Forge CLI

The Forge CLI provides commands for working with metrics:

# View all metric definitions (built-in + custom)
forge platform metrics settings --env myorg

# Create or update custom metrics
forge platform metrics define --env myorg --body '{"definitions": [...]}'

# List latest metric values
forge platform metrics list --env myorg

# Get values for a specific metric
forge platform metrics get empathy_score --env myorg

# View time-series trend
forge platform metrics trend empathy_score --days 14 --env myorg