--- title: "Get Usage" method: GET path: "/v1/account/usage" tags: ["v1"] --- # Get Usage `GET /v1/account/usage` ## Request - Base URL: `https://api.ellipsis.dev` - URL: `https://api.ellipsis.dev/v1/account/usage` - Auth: HTTP bearer Get usage for a calendar month, split by billing source. Omit period_start for the current UTC month. Pass a period from billing_periods to view history. Platform usage is charged to Ellipsis credit. Tokens paid by a developer's Claude or Codex subscription show their cost at Ellipsis rates and charge no credit. Pending and unresolved requests are missing measurements. ## Query parameters - `period_start` string, date, nullable ## Headers - `user-agent` string, nullable ## Response `200` Successful Response - GetUsageOverTimeResponse - `agent_sessions` UsageTotals, required: Cost and tokens over a set of sessions. - `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. - `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. - `billing_periods` BillingPeriodOption[], required - `is_current` boolean, required - `period_end` string, required - `period_start` string, required - `by_billing_source` BillingSourceUsage[] - `billing_source` 'platform' | 'claude_subscription' | 'codex_subscription' | 'unknown', required: Who paid for a usage event's tokens. Every new request is `platform`. The subscription values remain on rows written while a developer's own Claude or ChatGPT plan paid, before Ellipsis retired that route, so past sessions keep reporting what their tokens cost. - `charged` integer - `pending_requests` integer - `requests` integer - `token_charged` integer - `token_cost` integer, nullable - `tokens` integer - `unresolved_requests` integer - `by_day` UsageDay[], required: One entry per day of the period, oldest first, with zeros for days without usage. - `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, required: The UTC day, formatted yyyy-MM-dd. - `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. - `by_developer` DeveloperUsage[], required: Agent session cost and tokens for each developer, highest cost first. - `attribution_id` string, nullable, required - `attribution_login` string, nullable, required - `attribution_type` string, nullable, required - `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. - `runs` integer, required: Agent sessions the developer started. - `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. - `period_end` string, required - `period_start` string, required - `prior_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. - `prior_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. - `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. ## Other responses - `401`: The bearer token is missing, invalid, or revoked. - `403`: The credential may not perform this action, or the account is blocked. - `422`: Validation Error --- [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)