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.
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.
Total matching spans across the sample.
Of those, how many produced at least one observation.
Runs with a trace that were actually inspected.