> ## Documentation Index > Fetch the complete documentation index at: https://fireworks.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Usage & Cost Breakdown > Break down usage by deployment, model, API key, or custom tags, and read account-level rated costs — via firectl or the billingUsage API ## Overview Fireworks reports billing along two dimensions: * **Usage** — metered quantities such as tokens, accelerator-seconds, and audio input seconds. You can break usage down by deployment, model, API key, or custom tags. * **Cost** — rated dollar amounts. Costs are reported at the account level: a range-wide total, or line items grouped by billing category (serverless, dedicated, training). They aren't broken down by the same dimensions as usage, so per-API-key or per-deployment dollar figures aren't returned today — to approximate them, multiply usage by the published [serverless prices](/docs/serverless/pricing). For Enterprise accounts, these rated costs match monthly spend alerts: they include usage paid for with credits. Credit grants and purchases are reported separately. Two tools expose this data: * **CLI** — [`firectl billing get-usage`](/docs/tools-sdks/firectl/commands/billing-get-usage) shows the account cost total alongside the usage breakdown. Best for ad-hoc queries and shell scripting. * **HTTP API** — [`GET /v1/accounts/{account_id}/billingUsage`](/docs/api-reference/get-billing-usage) returns the usage breakdown, and its companion [`GET /v1/accounts/{account_id}/billing/summary`](/docs/api-reference/get-billing-summary) returns rated costs. Best for cron jobs, dashboards, and reporting pipelines. The CLI and `billingUsage` share the same usage response shape and dimensions. Most examples below show the CLI form and the equivalent cURL side by side. Over HTTP, grouping and time-range parameters go on `GET /billingUsage`; **filtering** uses the companion **`POST /billingUsage:query`** endpoint, which carries the filter in a JSON body. * **`GET /billingUsage`** — metered *quantities* (tokens, accelerator-seconds) grouped by deployment/model/API key/custom tags. No dollars. To **filter** (not just group) over HTTP, use **`POST /billingUsage:query`** with the same request shape in a JSON body (see the filter examples below). * **`GET /billing/summary`** — rated *dollar line items* by billing category (serverless, dedicated, training), grouped by your billing config. Optional daily buckets. No per-model/per-key breakdown. * **`POST /usageCosts:query`** — rated *dollar subtotals* grouped by caller-supplied dimensions (`HOUR`, `DAY`, `MODEL`, `USER`, `API_KEY`), with pagination and an account-wide `subtotal`. This is the endpoint to use when you need *costs* (not just quantities) broken down by model, user, or API key. Requires account administrator access for `ACCOUNT` scope; `SELF` scope returns only the authenticated user's costs. See [Query usage costs](/docs/api-reference/query-usage-costs). This page complements [Exporting Billing Metrics](/docs/accounts/exporting-billing-metrics): use `export-metrics` for a raw per-event CSV dump, and the workflows here for grouped usage and rated views. CLI examples require `firectl` 1.7.21 or later. Run `firectl version`, then `firectl upgrade` if needed. ## Authentication For the API, send your Fireworks API key as a bearer token. Any key on the target account works. ```bash theme={null} export ACCOUNT_ID="" export FIREWORKS_API_KEY="fw_..." ``` For the CLI, run `firectl login` once and `firectl` reads credentials from `~/.fireworks/auth.ini`. ## Basic usage Get a 30-day account-wide breakdown (defaults to all usage types, grouped by model for serverless and by deployment + accelerator for dedicated): ```bash theme={null} firectl billing get-usage \ --start-time 2026-05-01 \ --end-time 2026-06-01 ``` Add `-o json` for machine-readable output. ```bash theme={null} curl -sG "https://api.fireworks.ai/v1/accounts/${ACCOUNT_ID}/billingUsage" \ -H "Authorization: Bearer ${FIREWORKS_API_KEY}" \ --data-urlencode "startTime=2026-05-01T00:00:00Z" \ --data-urlencode "endTime=2026-06-01T00:00:00Z" ``` ## Examples ### Serverless usage by model ```bash theme={null} firectl billing get-usage \ --start-time 2026-05-01 --end-time 2026-06-01 \ --usage-type serverless \ --group-by model_name ``` ```bash theme={null} curl -sG "https://api.fireworks.ai/v1/accounts/${ACCOUNT_ID}/billingUsage" \ -H "Authorization: Bearer ${FIREWORKS_API_KEY}" \ --data-urlencode "startTime=2026-05-01T00:00:00Z" \ --data-urlencode "endTime=2026-06-01T00:00:00Z" \ --data-urlencode "usageType=SERVERLESS" \ --data-urlencode "groupBy=model_name" ``` ### Serverless usage by API key Breaks out serverless token consumption per API key. Pass both `api_key_id` (stable internal ID) and `api_key_name` (human-readable label from the console / `firectl api-key create --name`) so the response carries both. ```bash theme={null} firectl billing get-usage \ --start-time 2026-05-01 --end-time 2026-06-01 \ --usage-type serverless \ --group-by api_key_id \ --group-by api_key_name \ --group-by model_name ``` ```bash theme={null} curl -sG "https://api.fireworks.ai/v1/accounts/${ACCOUNT_ID}/billingUsage" \ -H "Authorization: Bearer ${FIREWORKS_API_KEY}" \ --data-urlencode "startTime=2026-05-01T00:00:00Z" \ --data-urlencode "endTime=2026-06-01T00:00:00Z" \ --data-urlencode "usageType=SERVERLESS" \ --data-urlencode "groupBy=api_key_id" \ --data-urlencode "groupBy=api_key_name" \ --data-urlencode "groupBy=model_name" ``` Sample row from the API response: ```json theme={null} { "startTime": "2026-05-28T00:00:00Z", "endTime": "2026-05-29T00:00:00Z", "promptTokens": "1842301", "completionTokens": "412980", "audioInputSeconds": 0, "usageType": "TEXT_COMPLETION_INFERENCE_USAGE", "group": { "api_key_id": "key_4nMFyHCSZP4CRKqa", "api_key_name": "prod-eng", "model_name": "accounts/fireworks/models/kimi-k2.6" } } ``` Token counts come back as JSON **strings** (int64 over JSON). Cast them with `tonumber` in `jq` or the equivalent in your client before doing arithmetic. The deprecated top-level `apiKeyId` field is only populated when `groupBy=api_key_id` is requested — always read API-key values from the `group` map. ### Filter to a specific API key Multiple values for the same dimension are OR'ed; different dimensions are AND'ed. In `firectl`, repeat `--filter` to OR values; over the API, list them in the dimension's `values` array. Over HTTP, filter with **`POST /billingUsage:query`**, which takes the same request in a JSON body, where `filter` is a map of dimension → `{ "values": [...] }`. ```bash theme={null} firectl billing get-usage \ --start-time 2026-05-01 --end-time 2026-06-01 \ --usage-type serverless \ --group-by model_name \ --filter api_key_name=prod-eng ``` ```bash theme={null} curl -sS -X POST "https://api.fireworks.ai/v1/accounts/${ACCOUNT_ID}/billingUsage:query" \ -H "Authorization: Bearer ${FIREWORKS_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "startTime": "2026-05-01T00:00:00Z", "endTime": "2026-06-01T00:00:00Z", "usageType": "SERVERLESS", "groupBy": ["model_name"], "filter": { "api_key_name": { "values": ["prod-eng"] } } }' ``` ### Dedicated deployment usage by deployment and GPU type ```bash theme={null} firectl billing get-usage \ --start-time 2026-05-01 --end-time 2026-06-01 \ --usage-type dedicated-deployment \ --group-by deployment_name \ --group-by accelerator_type ``` ```bash theme={null} curl -sG "https://api.fireworks.ai/v1/accounts/${ACCOUNT_ID}/billingUsage" \ -H "Authorization: Bearer ${FIREWORKS_API_KEY}" \ --data-urlencode "startTime=2026-05-01T00:00:00Z" \ --data-urlencode "endTime=2026-06-01T00:00:00Z" \ --data-urlencode "usageType=DEDICATED_DEPLOYMENT" \ --data-urlencode "groupBy=deployment_name" \ --data-urlencode "groupBy=accelerator_type" ``` ### Filter to a single deployment ```bash theme={null} firectl billing get-usage \ --start-time 2026-05-01 --end-time 2026-06-01 \ --filter deployment_name=accounts/my-account/deployments/my-deployment ``` ```bash theme={null} curl -sS -X POST "https://api.fireworks.ai/v1/accounts/${ACCOUNT_ID}/billingUsage:query" \ -H "Authorization: Bearer ${FIREWORKS_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "startTime": "2026-05-01T00:00:00Z", "endTime": "2026-06-01T00:00:00Z", "filter": { "deployment_name": { "values": ["accounts/my-account/deployments/my-deployment"] } } }' ``` ### Account-level cost totals only Get just the rated costs, without the usage rows: ```bash theme={null} firectl billing get-usage \ --start-time 2026-05-01 --end-time 2026-06-01 \ --account-costs-only ``` ```bash theme={null} curl -sG "https://api.fireworks.ai/v1/accounts/${ACCOUNT_ID}/billing/summary" \ -H "Authorization: Bearer ${FIREWORKS_API_KEY}" \ --data-urlencode "startTime=2026-05-01T00:00:00Z" \ --data-urlencode "endTime=2026-06-01T00:00:00Z" \ --data-urlencode "granularity=DAILY" ``` The companion [`GET /v1/accounts/{account_id}/billing/summary`](/docs/api-reference/get-billing-summary) endpoint returns rated billing line items. Grouping comes from your billing configuration rather than a caller-supplied `groupBy` or `filter`, so line items follow billing categories (serverless, dedicated, training) instead of arbitrary dimensions. Each `lineItem` carries a `series` and its rated `totalCost`, and `granularity=DAILY` adds a per-day `usageBuckets` breakdown. These are rated line items, so they may differ from the final invoice once credits or adjustments are applied. ## Reference ### CLI flags | Flag | Description | | ---------------------- | ---------------------------------------------------------------------------------- | | `--start-time` | Start time (inclusive), as `YYYY-MM-DD` or `'YYYY-MM-DD hh:mm:ss'`. | | `--end-time` | End time (exclusive), same formats. | | `--usage-type` | `all`, `serverless`, or `dedicated-deployment`. Defaults to all. | | `--group-by` | Dimension to group by. Repeatable. | | `--filter` | `key=value` filter. Repeatable; repeated values for the same key are OR'ed. | | `--timezone` | IANA timezone for daily aggregation (e.g. `America/Los_Angeles`). Defaults to UTC. | | `--account-costs-only` | Print only account-level cumulative costs for the range. | | `-o, --output` | `text` (default) or `json`. | Run `firectl billing get-usage --help` for the full list. ### API parameters Over HTTP, pass dimensions as `groupBy=` (repeat for multiple). `usageType` takes `SERVERLESS`, `DEDICATED_DEPLOYMENT`, or omitted for all. `timezone` and `startTime`/`endTime` mirror the CLI flags. See [the full API reference](/docs/api-reference/get-billing-usage) for parameter schemas and response types. To filter over HTTP, send **`POST /v1/accounts/{account_id}/billingUsage:query`** with the same request in a JSON body, where `filter` is a map of dimension → `{ "values": [...] }` (repeated values OR within a dimension; distinct dimensions are AND'ed). ### Grouping dimensions Valid `--group-by` / `groupBy` and `--filter` / `filter` dimensions depend on the usage type, and both are available over CLI and HTTP (grouping on `GET /billingUsage`, filtering on `POST /billingUsage:query`): * **Serverless**: `model_name`, `api_key_id`, `api_key_name`, `annotations.team`, `annotations.project`, `annotations.environment` * **Dedicated deployment**: `deployment_name`, `accelerator_type`, `annotations.team`, `annotations.project`, `annotations.environment` The `annotations.*` dimensions require an **Enterprise** plan (see [Custom tags](#custom-tags-team--project--environment)); the other dimensions are available to all accounts. Dedicated-deployment rows also include the deployment's region (`placement`, e.g. `US`, `EUROPE`, `GLOBAL`) and metered `accelerator_seconds`. ## Custom tags (team / project / environment) Breaking usage down by annotations (`annotations.team` / `annotations.project` / `annotations.environment`) requires an **Enterprise** plan. Grouping or filtering by an annotation dimension without it returns HTTP `400` (`FAILED_PRECONDITION`); breakdowns by model, API key, or deployment remain available to all accounts. Annotation tags are still recorded on your usage regardless of plan, so past usage is immediately available for these breakdowns once an account is on Enterprise. Group by `annotations.team`, `annotations.project`, or `annotations.environment` to split usage by your own labels. The tag source depends on usage type: * **Dedicated deployments**: set an `annotations` map on the deployment, e.g. `{"team": "search", "project": "x", "environment": "prod"}`. * **Serverless**: send a per-request header on inference calls: ```http theme={null} POST /inference/v1/chat/completions HTTP/1.1 Host: api.fireworks.ai Authorization: Bearer fw_... Fireworks-Annotations: team=search,project=ranker,environment=prod Content-Type: application/json ``` Annotation values are validated server-side. Only the recognized keys — `team`, `project`, `environment` — are stored; any other segment (an unknown key, an empty value like `project=`, or a bare token) is dropped on its own, and the recognized keys in the same header are always preserved. In responses these tags appear under the short keys `team` / `project` / `environment` in the `group` map: you group and filter by the `annotations.`-prefixed names, but the response omits the prefix. ## Cookbook: per-API-key reporting recipes These recipes target the HTTP API, where downstream aggregation in `jq` (or any client) is easiest. ### Aggregate per key, across models Sums prompt and completion tokens for each API key across every model it called, sorted by prompt volume. ```bash theme={null} curl -sG "https://api.fireworks.ai/v1/accounts/${ACCOUNT_ID}/billingUsage" \ -H "Authorization: Bearer ${FIREWORKS_API_KEY}" \ --data-urlencode "startTime=2026-05-01T00:00:00Z" \ --data-urlencode "endTime=2026-06-01T00:00:00Z" \ --data-urlencode "usageType=SERVERLESS" \ --data-urlencode "groupBy=api_key_id" \ --data-urlencode "groupBy=api_key_name" \ --data-urlencode "groupBy=model_name" \ | jq '.serverlessCosts | group_by(.group.api_key_id) | map({ api_key_id: .[0].group.api_key_id, api_key_name: .[0].group.api_key_name, models: (map(.group.model_name) | unique), prompt_tokens: ([.[].promptTokens | tonumber] | add), completion_tokens: ([.[].completionTokens | tonumber] | add) }) | sort_by(-.prompt_tokens)' ``` ### Group by model, then by key (cost-by-tool view) If reporting starts from "how much did each model cost me, and which keys drove that", flip the nesting: ```bash theme={null} curl -sG "https://api.fireworks.ai/v1/accounts/${ACCOUNT_ID}/billingUsage" \ -H "Authorization: Bearer ${FIREWORKS_API_KEY}" \ --data-urlencode "startTime=2026-05-01T00:00:00Z" \ --data-urlencode "endTime=2026-06-01T00:00:00Z" \ --data-urlencode "usageType=SERVERLESS" \ --data-urlencode "groupBy=api_key_id" \ --data-urlencode "groupBy=api_key_name" \ --data-urlencode "groupBy=model_name" \ | jq '.serverlessCosts | group_by(.group.model_name) | map({ model: .[0].group.model_name, api_keys: ( group_by(.group.api_key_id) | map({ api_key_id: .[0].group.api_key_id, api_key_name: .[0].group.api_key_name, prompt_tokens: ([.[].promptTokens | tonumber] | add), completion_tokens: ([.[].completionTokens | tonumber] | add) }) | sort_by(-.prompt_tokens) ) }) | sort_by(.model)' ``` Multiply the token totals by the published [serverless prices](/docs/serverless/pricing) to convert to dollars for chargeback. ### Backfill more than 31 days The endpoint caps each request at a 31-day window. To pull a longer history, loop month-by-month: ```bash theme={null} start_date="2026-01-01" end_date="2026-06-01" current="$start_date" while [ "$(date -u -d "$current" '+%s')" -lt "$(date -u -d "$end_date" '+%s')" ]; do next="$(date -u -d "$current +30 days" '+%Y-%m-%d')" if [ "$(date -u -d "$next" '+%s')" -gt "$(date -u -d "$end_date" '+%s')" ]; then next="$end_date" fi curl -sG "https://api.fireworks.ai/v1/accounts/${ACCOUNT_ID}/billingUsage" \ -H "Authorization: Bearer ${FIREWORKS_API_KEY}" \ --data-urlencode "startTime=${current}T00:00:00Z" \ --data-urlencode "endTime=${next}T00:00:00Z" \ --data-urlencode "usageType=SERVERLESS" \ --data-urlencode "groupBy=api_key_id" \ --data-urlencode "groupBy=api_key_name" \ > "usage_${current}_to_${next}.json" current="$next" done ``` ## Granularity and freshness * Usage is aggregated into **daily** buckets (`--timezone` / `timezone=` sets the day boundary). There are no sub-daily buckets. * Responses are cached for several minutes — fine for cron jobs and dashboards, not for real-time. ## Coverage caveats * **Tokens, not dollars.** The endpoint returns metered quantities (`promptTokens`, `completionTokens`, `accelerator_seconds`, `audioInputSeconds`). Multiply by the [serverless prices](/docs/serverless/pricing) for cost, or use `--account-costs-only` for account-level dollar totals. * **Inference types covered today**: text completion / chat completion and audio inference. Embeddings and image generation aren't yet reflected in `billingUsage` responses; coverage will expand in subsequent releases. * **Dedicated deployments** are attributed at the deployment level, not by API key. Use `usageType=DEDICATED_DEPLOYMENT` with `groupBy=deployment_name` for that breakdown. Run `firectl billing get-usage --help` to see all available CLI flags and options. ## See also * [`firectl billing get-usage`](/docs/tools-sdks/firectl/commands/billing-get-usage) - CLI command reference * [`GET /v1/accounts/{account_id}/billingUsage`](/docs/api-reference/get-billing-usage) - HTTP API reference * [`GET /v1/accounts/{account_id}/billing/summary`](/docs/api-reference/get-billing-summary) - Rated dollar costs by billing category, with optional daily breakdown * [`POST /v1/accounts/{account_id}/usageCosts:query`](/docs/api-reference/query-usage-costs) - Rated dollar subtotals grouped by hour/day/model/user/API key * [Exporting Billing Metrics](/docs/accounts/exporting-billing-metrics) - Raw per-event billing CSV export * [Account quotas](/docs/guides/quotas_usage/account-quotas) - Spending tiers and monthly spend limits