curl --request POST \
--url https://api.timbal.ai/orgs/{org_id}/metrics/definitions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Tool errors",
"metric_name": "tool_errors",
"has_error": true,
"value_source": "count",
"label_source": "span_name"
}
'{
"created_at": "2023-11-07T05:31:56Z",
"enabled": true,
"id": 123,
"label_source": "<string>",
"metric_name": "<string>",
"name": "<string>",
"source": "trace_span",
"value_source": "<string>",
"has_error": true,
"min_duration_ms": 123,
"project_id": 123,
"span_name": "<string>",
"span_name_prefix": "<string>",
"status_code": "<string>"
}{
"code": "<string>",
"message": "<string>"
}{
"code": "<string>",
"message": "<string>"
}Create Metric Definition
Define a metric of your own, emitted as runs land. Once it exists it behaves like any platform metric: readable through GET /orgs/{org_id}/metrics, listed in the catalog with origin: custom, and alarmable with no extra setup.
The definition is a span predicate over each completed run’s trace. Span paths are {workforce}.{step} and matching is on the leaf: use llm or get_address, not the full path. Predicate fields AND together and all are optional — omitting every one matches every non-root span.
metric_name is forced under the reserved trace. prefix so a definition cannot shadow a platform series. Set label_source to span_name to break the metric out per step, then point an alarm at a single step with dims.label.
Definitions are not retroactive: matching happens as runs arrive, so a new definition only sees traces written after it. Dry-run it against stored traces first with POST /orgs/{org_id}/metrics/definitions/preview. Note also that only sum/count/avg/min/max are available on the result — percentiles are not derivable from metric bins.
Set project_id to scope the definition to one project, which also makes it editable by holders of projects.alarms.manage there. Leaving it out defines an org-wide metric that runs against every project’s traces, and needs alarms.manage.
curl --request POST \
--url https://api.timbal.ai/orgs/{org_id}/metrics/definitions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Tool errors",
"metric_name": "tool_errors",
"has_error": true,
"value_source": "count",
"label_source": "span_name"
}
'{
"created_at": "2023-11-07T05:31:56Z",
"enabled": true,
"id": 123,
"label_source": "<string>",
"metric_name": "<string>",
"name": "<string>",
"source": "trace_span",
"value_source": "<string>",
"has_error": true,
"min_duration_ms": 123,
"project_id": 123,
"span_name": "<string>",
"span_name_prefix": "<string>",
"status_code": "<string>"
}{
"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.
Body
Body for POST /orgs/{org_id}/metrics/definitions.
Every predicate field is optional and they AND together. All omitted means
"every non-root span", which paired with label_source: span_name gives a
per-step call count — a reasonable first definition.
Response
Definition created