curl --request POST \
--url https://api.timbal.ai/orgs/{org_id}/metrics/definitions/preview \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"workforce_id": "42",
"value_source": "duration_ms",
"label_source": "span_name"
}
'{
"labels": [
{
"count": 123,
"max": 123,
"min": 123,
"sum": 123,
"label": "<string>"
}
],
"observations": 123,
"runs_matched": 123,
"runs_sampled": 123,
"samples": [
{
"run_id": 123,
"span_name": "<string>",
"value": 123
}
]
}{
"code": "<string>",
"message": "<string>"
}{
"code": "<string>",
"message": "<string>"
}Preview Metric Definition
Run a candidate predicate against recent stored traces without saving it, and see what it would have recorded.
Definitions are not retroactive, so a saved predicate that matches nothing looks identical to one that matches nothing yet. This answers that before you commit: which spans matched, what values they’d contribute, and how many distinct labels the metric would carry.
Samples the newest runs (20 by default, 50 max) — enough to tell a working predicate from a broken one, not a measurement of the true rate. Pass workforce_id to make the sample representative of the agent you’re actually matching. This is the only endpoint that reads stored traces, which is why it is capped; do not poll it.
Because it returns trace content, project_id doubles as the permission target: omit it and the sample spans the whole org, which needs alarms.manage; set it and the sample is capped to that project, which needs projects.alarms.manage there. A caller scoped to one project must therefore pass it.
curl --request POST \
--url https://api.timbal.ai/orgs/{org_id}/metrics/definitions/preview \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"workforce_id": "42",
"value_source": "duration_ms",
"label_source": "span_name"
}
'{
"labels": [
{
"count": 123,
"max": 123,
"min": 123,
"sum": 123,
"label": "<string>"
}
],
"observations": 123,
"runs_matched": 123,
"runs_sampled": 123,
"samples": [
{
"run_id": 123,
"span_name": "<string>",
"value": 123
}
]
}{
"code": "<string>",
"message": "<string>"
}{
"code": "<string>",
"message": "<string>"
}Authorizations
Timbal API key. Obtain your API key from the Timbal platform settings. See Authentication for more information.
Path Parameters
Body
Body for POST /orgs/{org_id}/metrics/definitions/preview.
The same predicate fields as create, minus everything about persistence.
Runs to inspect, newest first. Default 20, max 50.
Sample runs from one project only.
Sample runs from one agent/workflow (OrgsApps.id). Strongly
recommended: it makes the sample representative of what you're
filtering, instead of whatever the org ran most recently.
Response
What the definition would record
Per-label aggregates, exactly as they'd land in Metrics. More than a
handful of entries here means label_source: span_name over a
high-cardinality predicate — every label is another bin per minute.
Show child attributes
Show child attributes
Total matching spans across the sample.
Of those, how many produced at least one observation.
Runs with a trace that were actually inspected.
Show child attributes
Show child attributes