> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/api-reference/readme/platform/metrics.md).

# Metrics

## List latest metric values

> List metric values. By default, the newest period of each metric series.\
> \
> A categorical or boolean series folds its newest period into one row:\
> \`\`distribution\`\` counts each value and \`\`value\`\` is the most frequent.\
> Pages cover the first 10,000 values; narrow the filters or dates to read past them.\
> \
> Permissions: authenticated (any role).

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"MetricValueListResponse":{"properties":{"metrics":{"items":{"oneOf":[{"$ref":"#/components/schemas/NumericalMetricValueResponse"},{"$ref":"#/components/schemas/CategoricalMetricValueResponse"},{"$ref":"#/components/schemas/BooleanMetricValueResponse"}],"discriminator":{"propertyName":"metric_type","mapping":{"boolean":"#/components/schemas/BooleanMetricValueResponse","categorical":"#/components/schemas/CategoricalMetricValueResponse","numerical":"#/components/schemas/NumericalMetricValueResponse"}}},"type":"array","title":"Metrics"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["metrics","has_more"],"title":"MetricValueListResponse"},"NumericalMetricValueResponse":{"properties":{"metric_key":{"type":"string","title":"Metric Key"},"source":{"type":"string","title":"Source","default":"production"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Id"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"period_start":{"type":"string","format":"date-time","title":"Period Start"},"period_end":{"type":"string","format":"date-time","title":"Period End"},"event_count":{"type":"integer","title":"Event Count"},"avg_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Confidence"},"unit":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Unit"},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At"},"metric_type":{"type":"string","const":"numerical","title":"Metric Type"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"}},"type":"object","required":["metric_key","period_start","period_end","event_count","metric_type","value"],"title":"NumericalMetricValueResponse"},"CategoricalMetricValueResponse":{"properties":{"metric_key":{"type":"string","title":"Metric Key"},"source":{"type":"string","title":"Source","default":"production"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Id"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"period_start":{"type":"string","format":"date-time","title":"Period Start"},"period_end":{"type":"string","format":"date-time","title":"Period End"},"event_count":{"type":"integer","title":"Event Count"},"avg_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Confidence"},"unit":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Unit"},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At"},"metric_type":{"type":"string","const":"categorical","title":"Metric Type"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value","description":"The category this row counts. A list-metrics latest row gives its period's most frequent category."},"distribution":{"items":{"$ref":"#/components/schemas/CategoryCount"},"type":"array","title":"Distribution","description":"Events per category in this row's period, most frequent first. A list-metrics latest row\nlists every category its period saw; any other row lists its own category.","default":[]}},"type":"object","required":["metric_key","period_start","period_end","event_count","metric_type","value"],"title":"CategoricalMetricValueResponse"},"CategoryCount":{"properties":{"value":{"type":"string","title":"Value"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["value","count"],"title":"CategoryCount"},"BooleanMetricValueResponse":{"properties":{"metric_key":{"type":"string","title":"Metric Key"},"source":{"type":"string","title":"Source","default":"production"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Id"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"period_start":{"type":"string","format":"date-time","title":"Period Start"},"period_end":{"type":"string","format":"date-time","title":"Period End"},"event_count":{"type":"integer","title":"Event Count"},"avg_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Confidence"},"unit":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Unit"},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At"},"metric_type":{"type":"string","const":"boolean","title":"Metric Type"},"value":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Value","description":"The value this row counts. A list-metrics latest row gives its period's more frequent value."},"distribution":{"items":{"$ref":"#/components/schemas/BooleanCount"},"type":"array","title":"Distribution","description":"Events per value in this row's period, most frequent first. A list-metrics latest row\nlists both values its period saw; any other row lists its own value.","default":[]}},"type":"object","required":["metric_key","period_start","period_end","event_count","metric_type","value"],"title":"BooleanMetricValueResponse"},"BooleanCount":{"properties":{"value":{"type":"boolean","title":"Value"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["value","count"],"title":"BooleanCount"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/metrics":{"get":{"tags":["Metrics"],"summary":"List latest metric values","description":"List metric values. By default, the newest period of each metric series.\n\nA categorical or boolean series folds its newest period into one row:\n``distribution`` counts each value and ``value`` is the most frequent.\nPages cover the first 10,000 values; narrow the filters or dates to read past them.\n\nPermissions: authenticated (any role).","operationId":"list-metrics","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"sort_by","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Order of the page, e.g. `-period_start` (the default, newest first) or `+metric_key`.","default":[],"title":"Sort By"},"description":"Order of the page, e.g. `-period_start` (the default, newest first) or `+metric_key`."},{"name":"source","in":"query","required":false,"schema":{"enum":["production","simulation","all"],"type":"string","default":"production","title":"Source"}},{"name":"scope","in":"query","required":false,"schema":{"enum":["aggregate","entity","all"],"type":"string","default":"aggregate","title":"Scope"}},{"name":"entity_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Entity Type"}},{"name":"entity_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Entity Id"}},{"name":"service_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"}},{"name":"run_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"}},{"name":"session_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"}},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Date From"}},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Date To"}},{"name":"latest_only","in":"query","required":false,"schema":{"type":"boolean","description":"Return each series' newest period only, a categorical or boolean period folded into one row.","default":true,"title":"Latest Only"},"description":"Return each series' newest period only, a categorical or boolean period folded into one row."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"exclusiveMinimum":0,"default":100,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"title":"Continuation Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricValueListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```

## List available metrics (builtin + custom)

> List the workspace's active metrics: builtins plus custom definitions.\
> \
> Resolved from the workspace's metric settings, so a builtin turned off\
> there is not listed.\
> \
> Permissions: authenticated (any role).

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"MetricCatalogResponse":{"properties":{"metrics":{"items":{"$ref":"#/components/schemas/MetricCatalogEntry"},"type":"array","title":"Metrics"}},"type":"object","required":["metrics"],"title":"MetricCatalogResponse"},"MetricCatalogEntry":{"properties":{"key":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Key","description":"Metric key (lowercase alphanumeric + underscores)"},"name":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"metric_type":{"type":"string","enum":["numerical","categorical","boolean"],"title":"Metric Type"},"source":{"type":"string","enum":["call_intelligence","world_events","surface_events","emotion_events","connector_events","zerobus_events","voice_judge_results","custom"],"title":"Source"},"custom_source_key":{"anyOf":[{"type":"string","maxLength":128,"pattern":"^[a-z][a-z0-9_]*$"},{"type":"null"}],"title":"Custom Source Key"},"extraction_mode":{"type":"string","enum":["static","ai_classify","ai_extract","ai_query","sql_expr"],"title":"Extraction Mode","default":"static"},"granularity":{"type":"string","enum":["aggregate","per_entity"],"title":"Granularity","default":"aggregate"},"period_granularity":{"type":"string","enum":["hourly","daily"],"title":"Period Granularity","default":"daily"},"latency_tier":{"type":"string","enum":["streaming","near_realtime","batch"],"title":"Latency Tier","default":"batch"},"model_tier":{"type":"string","enum":["free","fast","balanced","max","custom"],"title":"Model Tier","default":"free"},"unit":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Unit"},"has_prompt":{"type":"boolean","title":"Has Prompt","default":false},"builtin":{"type":"boolean","title":"Builtin"}},"type":"object","required":["key","name","metric_type","source","builtin"],"title":"MetricCatalogEntry"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000}}},"paths":{"/v1/{workspace_id}/metrics/catalog":{"get":{"tags":["Metrics"],"summary":"List available metrics (builtin + custom)","description":"List the workspace's active metrics: builtins plus custom definitions.\n\nResolved from the workspace's metric settings, so a builtin turned off\nthere is not listed.\n\nPermissions: authenticated (any role).","operationId":"get-metric-catalog","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricCatalogResponse"}}}},"429":{"description":"Rate limited"}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Get values for a specific metric

> Get values for a specific metric with optional time range, newest period first.\
> \
> Permissions: authenticated (any role).

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"MetricListResponse":{"properties":{"metrics":{"items":{"oneOf":[{"$ref":"#/components/schemas/NumericalMetricValueResponse"},{"$ref":"#/components/schemas/CategoricalMetricValueResponse"},{"$ref":"#/components/schemas/BooleanMetricValueResponse"}],"discriminator":{"propertyName":"metric_type","mapping":{"boolean":"#/components/schemas/BooleanMetricValueResponse","categorical":"#/components/schemas/CategoricalMetricValueResponse","numerical":"#/components/schemas/NumericalMetricValueResponse"}}},"type":"array","title":"Metrics"}},"type":"object","required":["metrics"],"title":"MetricListResponse"},"NumericalMetricValueResponse":{"properties":{"metric_key":{"type":"string","title":"Metric Key"},"source":{"type":"string","title":"Source","default":"production"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Id"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"period_start":{"type":"string","format":"date-time","title":"Period Start"},"period_end":{"type":"string","format":"date-time","title":"Period End"},"event_count":{"type":"integer","title":"Event Count"},"avg_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Confidence"},"unit":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Unit"},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At"},"metric_type":{"type":"string","const":"numerical","title":"Metric Type"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"}},"type":"object","required":["metric_key","period_start","period_end","event_count","metric_type","value"],"title":"NumericalMetricValueResponse"},"CategoricalMetricValueResponse":{"properties":{"metric_key":{"type":"string","title":"Metric Key"},"source":{"type":"string","title":"Source","default":"production"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Id"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"period_start":{"type":"string","format":"date-time","title":"Period Start"},"period_end":{"type":"string","format":"date-time","title":"Period End"},"event_count":{"type":"integer","title":"Event Count"},"avg_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Confidence"},"unit":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Unit"},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At"},"metric_type":{"type":"string","const":"categorical","title":"Metric Type"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value","description":"The category this row counts. A list-metrics latest row gives its period's most frequent category."},"distribution":{"items":{"$ref":"#/components/schemas/CategoryCount"},"type":"array","title":"Distribution","description":"Events per category in this row's period, most frequent first. A list-metrics latest row\nlists every category its period saw; any other row lists its own category.","default":[]}},"type":"object","required":["metric_key","period_start","period_end","event_count","metric_type","value"],"title":"CategoricalMetricValueResponse"},"CategoryCount":{"properties":{"value":{"type":"string","title":"Value"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["value","count"],"title":"CategoryCount"},"BooleanMetricValueResponse":{"properties":{"metric_key":{"type":"string","title":"Metric Key"},"source":{"type":"string","title":"Source","default":"production"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Id"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"period_start":{"type":"string","format":"date-time","title":"Period Start"},"period_end":{"type":"string","format":"date-time","title":"Period End"},"event_count":{"type":"integer","title":"Event Count"},"avg_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Confidence"},"unit":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Unit"},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At"},"metric_type":{"type":"string","const":"boolean","title":"Metric Type"},"value":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Value","description":"The value this row counts. A list-metrics latest row gives its period's more frequent value."},"distribution":{"items":{"$ref":"#/components/schemas/BooleanCount"},"type":"array","title":"Distribution","description":"Events per value in this row's period, most frequent first. A list-metrics latest row\nlists both values its period saw; any other row lists its own value.","default":[]}},"type":"object","required":["metric_key","period_start","period_end","event_count","metric_type","value"],"title":"BooleanMetricValueResponse"},"BooleanCount":{"properties":{"value":{"type":"boolean","title":"Value"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["value","count"],"title":"BooleanCount"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/metrics/{metric_key}":{"get":{"tags":["Metrics"],"summary":"Get values for a specific metric","description":"Get values for a specific metric with optional time range, newest period first.\n\nPermissions: authenticated (any role).","operationId":"get-metric-values","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"metric_key","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z][a-z0-9_]*$","description":"Metric key (lowercase alphanumeric + underscores)","title":"Metric Key"},"description":"Metric key (lowercase alphanumeric + underscores)"},{"name":"source","in":"query","required":false,"schema":{"enum":["production","simulation","all"],"type":"string","default":"production","title":"Source"}},{"name":"scope","in":"query","required":false,"schema":{"enum":["aggregate","entity","all"],"type":"string","default":"aggregate","title":"Scope"}},{"name":"entity_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Entity Type"}},{"name":"entity_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Entity Id"}},{"name":"service_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"}},{"name":"run_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"}},{"name":"session_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"}},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Date From"}},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Date To"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"default":90,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricListResponse"}}}},"404":{"description":"Metric key is not defined in this workspace"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```

## Get time-series trend for a metric

> Get every value a metric recorded in the last \`\`days\`\` days, newest period first.\
> \
> Permissions: authenticated (any role).

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"MetricListResponse":{"properties":{"metrics":{"items":{"oneOf":[{"$ref":"#/components/schemas/NumericalMetricValueResponse"},{"$ref":"#/components/schemas/CategoricalMetricValueResponse"},{"$ref":"#/components/schemas/BooleanMetricValueResponse"}],"discriminator":{"propertyName":"metric_type","mapping":{"boolean":"#/components/schemas/BooleanMetricValueResponse","categorical":"#/components/schemas/CategoricalMetricValueResponse","numerical":"#/components/schemas/NumericalMetricValueResponse"}}},"type":"array","title":"Metrics"}},"type":"object","required":["metrics"],"title":"MetricListResponse"},"NumericalMetricValueResponse":{"properties":{"metric_key":{"type":"string","title":"Metric Key"},"source":{"type":"string","title":"Source","default":"production"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Id"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"period_start":{"type":"string","format":"date-time","title":"Period Start"},"period_end":{"type":"string","format":"date-time","title":"Period End"},"event_count":{"type":"integer","title":"Event Count"},"avg_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Confidence"},"unit":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Unit"},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At"},"metric_type":{"type":"string","const":"numerical","title":"Metric Type"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"}},"type":"object","required":["metric_key","period_start","period_end","event_count","metric_type","value"],"title":"NumericalMetricValueResponse"},"CategoricalMetricValueResponse":{"properties":{"metric_key":{"type":"string","title":"Metric Key"},"source":{"type":"string","title":"Source","default":"production"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Id"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"period_start":{"type":"string","format":"date-time","title":"Period Start"},"period_end":{"type":"string","format":"date-time","title":"Period End"},"event_count":{"type":"integer","title":"Event Count"},"avg_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Confidence"},"unit":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Unit"},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At"},"metric_type":{"type":"string","const":"categorical","title":"Metric Type"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value","description":"The category this row counts. A list-metrics latest row gives its period's most frequent category."},"distribution":{"items":{"$ref":"#/components/schemas/CategoryCount"},"type":"array","title":"Distribution","description":"Events per category in this row's period, most frequent first. A list-metrics latest row\nlists every category its period saw; any other row lists its own category.","default":[]}},"type":"object","required":["metric_key","period_start","period_end","event_count","metric_type","value"],"title":"CategoricalMetricValueResponse"},"CategoryCount":{"properties":{"value":{"type":"string","title":"Value"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["value","count"],"title":"CategoryCount"},"BooleanMetricValueResponse":{"properties":{"metric_key":{"type":"string","title":"Metric Key"},"source":{"type":"string","title":"Source","default":"production"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Id"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"period_start":{"type":"string","format":"date-time","title":"Period Start"},"period_end":{"type":"string","format":"date-time","title":"Period End"},"event_count":{"type":"integer","title":"Event Count"},"avg_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Confidence"},"unit":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Unit"},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At"},"metric_type":{"type":"string","const":"boolean","title":"Metric Type"},"value":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Value","description":"The value this row counts. A list-metrics latest row gives its period's more frequent value."},"distribution":{"items":{"$ref":"#/components/schemas/BooleanCount"},"type":"array","title":"Distribution","description":"Events per value in this row's period, most frequent first. A list-metrics latest row\nlists both values its period saw; any other row lists its own value.","default":[]}},"type":"object","required":["metric_key","period_start","period_end","event_count","metric_type","value"],"title":"BooleanMetricValueResponse"},"BooleanCount":{"properties":{"value":{"type":"boolean","title":"Value"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["value","count"],"title":"BooleanCount"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/metrics/{metric_key}/trend":{"get":{"tags":["Metrics"],"summary":"Get time-series trend for a metric","description":"Get every value a metric recorded in the last ``days`` days, newest period first.\n\nPermissions: authenticated (any role).","operationId":"get-metric-trend","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"metric_key","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z][a-z0-9_]*$","description":"Metric key (lowercase alphanumeric + underscores)","title":"Metric Key"},"description":"Metric key (lowercase alphanumeric + underscores)"},{"name":"source","in":"query","required":false,"schema":{"enum":["production","simulation","all"],"type":"string","default":"production","title":"Source"}},{"name":"scope","in":"query","required":false,"schema":{"enum":["aggregate","entity","all"],"type":"string","default":"aggregate","title":"Scope"}},{"name":"entity_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Entity Type"}},{"name":"entity_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Entity Id"}},{"name":"service_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"}},{"name":"run_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"}},{"name":"session_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"default":30,"title":"Days"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricListResponse"}}}},"404":{"description":"Metric key is not defined in this workspace"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/api-reference/readme/platform/metrics.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.