> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/platform-api/safety/metric-store.md). # Metric Store The metric store provides a common value shape for operational, quality, and evaluation metrics. A value carries a metric key and type, production or simulation source, aggregate or entity scope identifiers, period, event count, optional confidence, unit, and computation time. The active catalog contains 41 built-in definitions plus supported workspace custom definitions. A catalog entry describes a metric the platform knows how to represent; it does not guarantee that every workspace, channel, or interaction produces a value for that key. Metric values arrive through multiple paths. Recent per-call values can be projected with low latency, while scheduled processing produces aggregate and AI-evaluated history. The read API merges recent values with durable history, preferring the recent value when both stores contain the same metric identity. {% hint style="info" %} Production and simulation are separate value sources. Simulations compute only metrics selected by their evaluation configuration; they do not automatically produce every active workspace metric. {% endhint %} ## Metric Settings Metric definitions are managed in workspace settings. Reads require authenticated workspace access. Updates require the Admin or Owner role (`Workspace:Update`). Built-in keys cannot be reused by custom definitions. The settings response always merges built-ins back into the list. For built-ins, saved overrides are limited to `active`, `freshness_sla_minutes`, `period_granularity`, `valid_range_min`, `valid_range_max`, and the stable `id`; extraction behavior and source remain platform-owned. ### Get Metric Definitions {% openapi src="" path="/v1/{workspace\_id}/settings/metrics" method="get" %} {% endopenapi %} ```bash curl -H "Authorization: Bearer $API_KEY" \ "https://api.platform.amigo.ai/v1/$WORKSPACE_ID/settings/metrics" ``` ### Create or Update Custom Metrics {% openapi src="" path="/v1/{workspace\_id}/settings/metrics" method="put" %} {% endopenapi %} ```bash curl -X PUT \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "definitions": [ { "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 empathy from 1 to 10. Input: {data}. Output only the number.", "aggregation": "avg", "granularity": "per_entity", "unit": "score", "valid_range_min": 1, "valid_range_max": 10 } ] }' \ "https://api.platform.amigo.ai/v1/$WORKSPACE_ID/settings/metrics" ``` The `definitions` array is replaced when supplied. Include every custom definition you want to retain; built-ins are merged back automatically. ### Sources | Source | Current Evidence Class | | --------------------- | -------------------------------------------------------------------------------- | | `call_intelligence` | Terminal voice and supported text conversation summaries | | `world_events` | Eligible world-event records | | `surface_events` | Surface-domain lifecycle events | | `emotion_events` | Emotion-domain acoustic analysis events | | `connector_events` | Connector-runner-sourced events | | `zerobus_events` | Supported streaming-ingestion event families such as voice, SMS, and model usage | | `voice_judge_results` | Audio-native per-call Voice Judge results | | `custom` | Extension producer selected through `custom_source_key` | The source enum describes where a definition expects evidence. It does not mean every event in that source is evaluated or that every source has an active producer in each workspace. ### Extraction Modes | Mode | Current Boundary | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `static` | Reads a configured path from matching evidence; custom static execution is primarily suited to numerical values | | `ai_classify` | Classifies selected content into configured `ai_labels` | | `ai_extract` | Settings validation accepts `ai_labels` or `ai_schema`, but the current scheduled execution path requires labels; prefer `ai_labels` and do not rely on schema-only execution | | `ai_query` | Runs a model-based rubric against call-intelligence or supported event content; output is non-deterministic and can fail or be missing | | `sql_expr` | Reserved for platform definitions; rejected for custom metrics | Not every metric type, aggregation, extraction mode, source, and channel-scope combination has an active executor. Prefer combinations exercised by the Developer Console or verify the intended producer before deploying a custom definition. ## Processing and Freshness Definition metadata does not create a producer. `latency_tier` describes intended processing class, and `freshness_sla_minutes` is a configured staleness target rather than a contractual SLA. A definition update takes effect when the applicable execution path next processes eligible evidence. It does not guarantee immediate recomputation, atomic replacement of history, or backfill of earlier interactions. A missing value can mean no eligible evidence, pending processing, evaluator failure, or an unavailable analytical dependency. Recent API values can appear before durable analytical/dashboard views catch up. Preserve the difference between a missing value, numerical `0`, boolean `false`, a categorical value, and `null`. ## Query Metric Values ### List Metric Values Returns the latest value per metric identity by default; request history explicitly when needed. {% openapi src="" path="/v1/{workspace\_id}/metrics" method="get" %} {% endopenapi %} ### Get One Metric {% openapi src="" path="/v1/{workspace\_id}/metrics/{metric\_key}" method="get" %} {% endopenapi %} ### Get Metric Trend {% openapi src="" path="/v1/{workspace\_id}/metrics/{metric\_key}/trend" method="get" %} {% endopenapi %} ### Metric Catalog Returns active built-in and active custom catalog entries. The catalog exposes base definition metadata; it is not a computation-status or freshness endpoint. {% openapi src="" path="/v1/{workspace\_id}/metrics/catalog" method="get" %} {% endopenapi %} ### List Call Metric Values Returns recent metric values for compatibility call-detail views. Use [Runs](/developer-guide/platform-api/conversations/runs.md) as the canonical interaction inventory and the general metric filters for run- and session-scoped analysis. {% openapi src="" path="/v1/{workspace\_id}/calls/{call\_id}/metrics" method="get" %} {% endopenapi %} ## Production Evals Metric definitions and [production eval definitions](/developer-guide/platform-api/safety/production-evals.md) are related but distinct. This operation runs active production eval definitions for one completed conversation and persists the results; it is not a non-persisting preview for an arbitrary metric definition. {% openapi src="" path="/v1/{workspace\_id}/calls/{conversation\_id}/evaluate" method="post" %} {% endopenapi %} Automatic eager evaluation is best-effort and feature-dependent. It can be skipped or fail; simulations evaluate only definitions captured and selected by their run configuration. ## Limits | Limit | Value | | ------------------------------------ | ---------------- | | Custom definitions per workspace | 50 | | Metric key length | 64 characters | | Event types per definition | 100 | | `ai_query_prompt` length | 8,000 characters | | `freshness_sla_minutes` | 5-1,440 | | Merged list fetch (`limit + offset`) | 500 | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.amigo.ai/developer-guide/platform-api/safety/metric-store.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.