List Usage Metrics

Returns the unique metric names configured by published extractor rule sets that are available to a project. Use this endpoint to populate metric selectors for usage queries. Clients may also provide a valid custom metric name when a metric is produced dynamically and is not configured in an extractor.

Endpoint

GET /v1/projects/:project_id/usage/metrics

Authentication

Authorization: Bearer <api-key>

Requires usage read access.

Path Parameters

Field	Required	Description
project_id	Yes	Project whose published extractor metrics should be listed.

Query Parameters

This endpoint has no query parameters.

Request Body

The request body is empty.

Example

curl 'http://127.0.0.1:8080/v1/projects/proj_gateway/usage/metrics' \
  -H 'Authorization: Bearer <api-key>'

Response

{
  "metrics": ["input_tokens", "output_tokens", "requests", "tool_call.web_search"]
}

Field	Type	Description
metrics	string[]	Unique metric names in ascending order. The array is empty when no available published extractor defines a charge-item metric.

Behavior

• Only extractor rule sets with status="published" contribute metrics.
• Published rule sets with a future effective_from are excluded until they become effective.
• Draft and archived rule sets are excluded.
• Tenant-level extractor rule sets that are available to the project are included for compatibility.
• Duplicate and blank metric names are removed before sorting.
• Dotted metric names such as tool_call.web_search are returned unchanged.

Create metrics with Create Rule Set and make them available with Publish Rule Set. Pass the returned names to Analysis Query or List Usage Event Details.