--- title: "Get Handler Metrics" method: GET path: "/v1/handlers/{id}/metrics" tags: ["v1"] --- # Get Handler Metrics `GET /v1/handlers/{id}/metrics` ## Request - Base URL: `https://api.ellipsis.dev` - URL: `https://api.ellipsis.dev/v1/handlers/{id}/metrics` - Auth: HTTP bearer Return session counts and accumulated spend for a saved handler. Filters only by session creation time. `buckets` splits the window by `interval`, chosen from the window's length. Counts use the current turn and conversation state, so an open conversation awaiting another message remains active. Spend includes the selected sessions' full accumulated cost, including activity after the creation-time window. Only sessions carrying this exact saved handler id are counted; legacy sessions without handler provenance are excluded. spend_windows reports current trailing 1-, 7-, and 28-day spend, including subscription tokens, and effective handler budgets across all attributed sessions. Those windows use usage timestamps and are independent of start/end. Requires configs:read matching handlers/{service} and unrestricted sessions:read. Session tokens with both grants may read metrics. ## Path parameters - `id` string, required ## Query parameters - `start` string, date-time, required: Inclusive session creation-time bound. Naive timestamps use UTC. - `end` string, date-time, required: Exclusive session creation-time bound. Naive timestamps use UTC. ## Headers - `user-agent` string, nullable ## Response `200` Successful Response - HandlerMetricsResponse: Session counts and spend attributed to one saved handler. - `buckets` ConfigUsageBucket[], required: Sessions created and usage in each bucket of the window, oldest first, with zeros for buckets without either. - `cost` Cost, required: What something cost, in millicents. - `charged` integer, required: What Ellipsis charged to credit, in millicents. It is everything except subscription tokens. - `cpu` integer, required: CPU spend in millicents. - `fee` integer, required: Platform fee in millicents. - `llm` LlmCost, required: What LLM tokens cost, in total and by model. - `all` LlmCostSplit, required: What LLM tokens cost, in millicents, split by who paid (Ellipsis credit or the user's own subscription). - `claude_subscription` integer, required: Token cost paid by a Claude subscription, at Ellipsis rates, in millicents. - `codex_subscription` integer, required: Token cost paid by a Codex subscription, at Ellipsis rates, in millicents. - `platform` integer, required: Token cost charged to Ellipsis credit, in millicents. - `total` integer, required: All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription. - `by_model` ModelLlmCostSplit[], required: Token cost for each model that used tokens. - `claude_subscription` integer, required: Token cost paid by a Claude subscription, at Ellipsis rates, in millicents. - `codex_subscription` integer, required: Token cost paid by a Codex subscription, at Ellipsis rates, in millicents. - `model` string, required: The model that used these tokens. - `platform` integer, required: Token cost charged to Ellipsis credit, in millicents. - `total` integer, required: All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription. - `memory` integer, required: Memory spend in millicents. - `total` integer, required: Everything it cost, whoever paid, in millicents. It is the sum of llm.all.total, cpu, memory, and fee, and it is what the budget caps. - `date` string, date-time, required: When the bucket starts, in UTC. - `sessions` integer, required: Sessions created in the bucket. - `tokens` Tokens, required: Tokens used, in total and by model. - `all` TokenCounts, required: Token counts. - `cache_creation` integer, required: Tokens written to the prompt cache. - `cache_read` integer, required: Tokens read from the prompt cache. - `input` integer, required: Input tokens used. - `output` integer, required: Output tokens used. - `total` integer, required: All tokens used, including prompt cache reads and writes. Token cost is priced on this. - `by_model` ModelTokenCounts[], required: Token counts for each model that used tokens. - `cache_creation` integer, required: Tokens written to the prompt cache. - `cache_read` integer, required: Tokens read from the prompt cache. - `input` integer, required: Input tokens used. - `model` string, required: The model that used these tokens. - `output` integer, required: Output tokens used. - `total` integer, required: All tokens used, including prompt cache reads and writes. Token cost is priced on this. - `cost` Cost, required: What something cost, in millicents. - `charged` integer, required: What Ellipsis charged to credit, in millicents. It is everything except subscription tokens. - `cpu` integer, required: CPU spend in millicents. - `fee` integer, required: Platform fee in millicents. - `llm` LlmCost, required: What LLM tokens cost, in total and by model. - `all` LlmCostSplit, required: What LLM tokens cost, in millicents, split by who paid (Ellipsis credit or the user's own subscription). - `claude_subscription` integer, required: Token cost paid by a Claude subscription, at Ellipsis rates, in millicents. - `codex_subscription` integer, required: Token cost paid by a Codex subscription, at Ellipsis rates, in millicents. - `platform` integer, required: Token cost charged to Ellipsis credit, in millicents. - `total` integer, required: All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription. - `by_model` ModelLlmCostSplit[], required: Token cost for each model that used tokens. - `claude_subscription` integer, required: Token cost paid by a Claude subscription, at Ellipsis rates, in millicents. - `codex_subscription` integer, required: Token cost paid by a Codex subscription, at Ellipsis rates, in millicents. - `model` string, required: The model that used these tokens. - `platform` integer, required: Token cost charged to Ellipsis credit, in millicents. - `total` integer, required: All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription. - `memory` integer, required: Memory spend in millicents. - `total` integer, required: Everything it cost, whoever paid, in millicents. It is the sum of llm.all.total, cpu, memory, and fee, and it is what the budget caps. - `end` string, date-time, required: Exclusive session creation-time bound. - `handler_id` string, required: The saved handler whose sessions are counted. - `interval` 'hour' | 'day' | 'week', required: The width of one entry in a time series, chosen from the window's length. A window of up to 3 days is split by hour, a window of up to 120 days by day, and a longer window by week. Every entry starts on a UTC boundary of its interval, and a week starts on Monday. - `sessions` HandlerSessionCounts, required: Current session outcomes for the requested creation-time window. - `active` integer, required: Unfinished sessions, including open conversations awaiting another message. - `cancelled` integer, required: Sessions cancelled before completion. - `completed` integer, required: Sessions that closed without an error or stop. - `failed` integer, required: Sessions that ended with an error. - `stopped` integer, required: Sessions stopped by a user. - `total` integer, required: All sessions attributed to this saved handler. - `spend_windows` ConfigSpendWindow[], required: Current trailing 1-, 7-, and 28-day spend, including subscription tokens, and enforced handler budgets. Based on usage timestamps across all this handler's sessions and revisions, independently of the start/end session creation filters. - `limit` integer, required: The enforced configuration cap in millicents. It is the configuration's own budget limited to the platform maximum, or the maximum when unset. Account and developer limits also apply. - `platform_max` integer, required: The platform ceiling for this window, in millicents. - `spent` integer, required: Spend during the window across this configuration's sessions, including subscription tokens, in millicents. - `window_days` integer, required: The trailing window in days, which is 1, 7, or 28. - `start` string, date-time, required: Inclusive session creation-time bound. ## Other responses - `401`: The bearer token is missing, invalid, or revoked. - `403`: The credential may not perform this action, or the account is blocked. - `404`: No such current handler in your account or configs grant. - `422`: A time bound is malformed, or start is not earlier than end. --- [API](https://skmtc.dev/ellipsis/apis/ellipsis-rest-api.md) - [All operations](https://skmtc.dev/ellipsis/apis/ellipsis-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ellipsis/apis/ellipsis-rest-api/revisions/344b16df9a1a?raw)