> ## Documentation Index > Fetch the complete documentation index at: https://docs.timbal.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml POST /orgs/{org_id}/metrics/definitions/preview openapi: 3.1.0 info: title: Timbal Platform API description: Public API documentation for the Timbal platform license: name: '' version: 2.0.0 servers: - url: https://api.timbal.ai description: Production - url: https://api.dev.timbal.ai description: Development security: [] tags: - name: ace description: Action Control Engine (ACE) operations - name: alarms description: Metric series and threshold alarms - name: analytics description: Org and project analytics - name: billing description: Subscriptions, usage, and payment-related operations - name: channels description: Delivery channels alarms notify through - name: content description: Re-sign stored content URLs - name: files description: File operations - name: iam description: IAM — actions, roles, users, and authorization introspection - name: k2 description: Knowledge Bases v2 operations - name: orgs description: Organization operations - name: projects description: Project operations - name: runs description: Execution operations - name: templates description: Public project template catalog - name: users description: Authenticated user profile paths: /orgs/{org_id}/metrics/definitions/preview: post: tags: - alarms summary: Dry-run a custom metric definition description: >- 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. operationId: preview_org_metric_definition parameters: - name: org_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PreviewMetricDefinitionReq' examples: Per-step latency: value: workforce_id: '42' value_source: duration_ms label_source: span_name Which tools are failing: value: workforce_id: '42' has_error: true value_source: count label_source: span_name required: true responses: '200': description: What the definition would record content: application/json: schema: $ref: '#/components/schemas/PreviewMetricDefinitionOut' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' security: - bearer_auth: [] components: schemas: PreviewMetricDefinitionReq: type: object description: |- Body for **POST** `/orgs/{org_id}/metrics/definitions/preview`. The same predicate fields as create, minus everything about persistence. properties: has_error: type: - boolean - 'null' label_source: type: string limit: type: - integer - 'null' format: int64 description: Runs to inspect, newest first. Default 20, max 50. min_duration_ms: type: - integer - 'null' format: int32 project_id: type: - string - 'null' description: Sample runs from one project only. span_name: type: - string - 'null' span_name_prefix: type: - string - 'null' status_code: type: - string - 'null' value_source: type: string workforce_id: type: - string - 'null' description: |- 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. PreviewMetricDefinitionOut: type: object required: - runs_sampled - runs_matched - observations - labels - samples properties: labels: type: array items: $ref: '#/components/schemas/PreviewLabelOut' description: >- 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. observations: type: integer format: int64 description: Total matching spans across the sample. runs_matched: type: integer format: int64 description: Of those, how many produced at least one observation. runs_sampled: type: integer format: int64 description: Runs with a trace that were actually inspected. samples: type: array items: $ref: '#/components/schemas/PreviewSampleOut' ErrorMessage: type: object required: - code - message properties: code: type: string description: Machine-readable error code (e.g. `ALREADY_EXISTS`, `BAD_REQUEST`). message: type: string description: Human-readable description. PreviewLabelOut: type: object description: What the filter would have recorded for one label. required: - count - sum - min - max properties: count: type: integer format: int64 label: type: - string - 'null' description: '`null` when `label_source` is `none`.' max: type: number format: double min: type: number format: double sum: type: number format: double PreviewSampleOut: type: object description: >- One matched span, for eyeballing that the predicate hit what was intended. required: - run_id - span_name - value properties: run_id: type: integer format: int64 span_name: type: string value: type: number format: double securitySchemes: bearer_auth: type: http scheme: bearer description: >- Timbal API key. Obtain your API key from the Timbal platform settings. See [Authentication](/api-reference/authentication) for more information. ````