# Data residency Source: https://docs.fireworks.ai/accounts/data-residency Restrict inference for your Enterprise account to a selected region Data residency restricts inference on your account to a single region. Once a region is set, every request must use that region's API endpoint and a model served in that region. It does not change how your requests are routed. Turning it on will not move existing traffic into the region. This setting *enforces* all requests to be in the set region, and rejects the ones that are not. **Enterprise feature.** Data residency is available on Enterprise accounts. Contact your Fireworks representative if you need this enabled. Only account **Admins** can change data residency. Other roles can view the current setting but cannot change it. Residency applies **account-wide**: every API key on the account is restricted to the selected region. ## Available regional restrictions | Regional restrictions | API endpoint | Serverless | Dedicated deployments | | :-------------------- | :-------------------------------------------- | :--------------------------------------------------- | :----------------------------------------------------------------------------------- | | None | api.fireworks.ai | Any model | Any region | | US | us.api.fireworks.ai | [US-only Serverless](/serverless/us-only-serverless) | [`US` multi-region](/deployments/regions), or a single US region such as `US_IOWA_1` | **None** is the default. For a region that is not listed, contact [sales](https://fireworks.ai/company/contact-us). ## Before you switch it on A residency change takes effect as soon as you save it, and anything that does not match the region is rejected. ### Serverless Point your clients at the region's API endpoint and change every request to use a model from that region. See [US-only Serverless](/serverless/us-only-serverless) for the US endpoint and model IDs. **`inference_geo` is deprecated** in favor of data residency. As you switch over, remove the `inference_geo` field from your request bodies and the `Fireworks-Inference-Geo` header from your requests. ### Dedicated deployments Every dedicated deployment must run in the selected region. Create it with `--region` set to that region, or to a single region inside it. See [Regions](/deployments/regions). Check what you already have before you save the setting: ```bash theme={null} firectl deployment list ``` * **New deployments outside the region are rejected** when you create them. * **Existing deployments are not checked, moved, or stopped** when you switch the setting on. One outside the region keeps running and keeps costing you money, but requests to it are rejected. Replace it first. * **You can move a deployment to another region inside your residency region, but not out of it.** ## Configure in the console Account admins can set data residency in the Fireworks console at **Settings → Governances → Data Residency** ([open in console](https://app.fireworks.ai/settings/governances/region-access)). Select the region and save. The console asks you to confirm that your clients already use the endpoint and models shown for that region. ## Configure with firectl Set the region: ```bash theme={null} firectl policy residency set US ``` Inspect the current setting: ```bash theme={null} firectl policy residency get ``` Remove the restriction and return the account to unrestricted serving: ```bash theme={null} firectl policy residency clear ``` ## Pricing Regional models are priced at a premium over the base serverless price for the same model. See [Serverless pricing](/serverless/pricing). ## Limitations The following are not supported while a region is set: calls are rejected, and stay rejected until you clear the setting. * **Training.** Fine-tuning and training jobs are blocked. Support is coming soon. * **FireRouter.** [FireRouter](/ecosystem/firerouter/overview) can pass a request through to a third-party provider, which Fireworks cannot constrain to a region. * **BYOC.** [BYOC](/ecosystem/integrations/byoc/overview) deployments run in your own cloud account, so Fireworks cannot enforce where they run. ## Related * [US-only Serverless](/serverless/us-only-serverless) — endpoint and model IDs for the US region * [Enterprise features](/accounts/enterprise-features) — overview of Enterprise administration capabilities * [Managing users](/accounts/users) — account roles and permissions * [Data Security](/guides/security_compliance/data_security) — encryption, retention, and access controls # Enterprise features Source: https://docs.fireworks.ai/accounts/enterprise-features Administrative capabilities available to Enterprise accounts Fireworks Enterprise accounts can use additional governance and administration features beyond the standard platform. This section documents those capabilities and how account admins configure them. These features require an **Enterprise** account. If you are on another plan and need access, contact your Fireworks representative. Only account **Admins** can configure Enterprise features. Other roles can view some settings (for example, the active model access policy) but cannot change them. ## Available features Restrict which models users on your account can use for serverless inference, Fast mode, dedicated deployments, and training. Restrict inference and training data processing to a selected region for the account. Bring your own OpenID Connect or SAML identity provider for enterprise authentication. Monitor API and data-access activity across your account for security review and compliance. ## Who can manage Enterprise features Most Enterprise administration features require the **Admin** role on the account. Any account member can usually read current settings (for example, viewing the active model access policy), but only admins can change them. See [Managing users](/accounts/users) for role definitions. ## Getting access Enterprise features are enabled on your Fireworks account type. Contact [inquiries@fireworks.ai](mailto:inquiries@fireworks.ai) or your account representative if you need Enterprise access or want to confirm which features are active on your account. # Exporting Billing Metrics Source: https://docs.fireworks.ai/accounts/exporting-billing-metrics Export billing and usage metrics for all Fireworks services ## Overview Fireworks provides a CLI tool to export comprehensive billing metrics for all usage types including serverless inference, on-demand deployments, and training jobs. The exported data can be used for cost analysis, internal billing, and usage tracking. This export reports metered **quantities** — tokens and accelerator-seconds — not dollars. For a CSV of rated serverless **costs** grouped by model, model tier, user, or API key, use [Exporting Usage Costs](/accounts/exporting-usage-costs). ## Exporting billing metrics Use the Fireworks CLI to export a billing CSV that includes all usage: ```bash theme={null} # Authenticate (once) firectl login # Export billing metrics to CSV firectl billing export-metrics ``` ## Examples Export all billing metrics for an account: ```bash theme={null} firectl billing export-metrics ``` Export metrics for a specific date range and filename: ```bash theme={null} firectl billing export-metrics \ --start-time "2025-01-01" \ --end-time "2025-01-31" \ --filename january_metrics.csv ``` ## Output format The exported CSV includes the following columns: * **email**: Account email * **start\_time**: Request start timestamp * **end\_time**: Request end timestamp * **usage\_type**: Type of usage (e.g., TEXT\_COMPLETION\_INFERENCE\_USAGE) * **accelerator\_type**: GPU/hardware type used * **accelerator\_seconds**: Compute time in seconds * **base\_model\_name**: The model used * **model\_bucket**: Model category * **parameter\_count**: Model size * **prompt\_tokens**: Input tokens * **completion\_tokens**: Output tokens * **cached\_prompt\_tokens**: Prompt tokens served from cache (text inference only). Subset of `prompt_tokens`. * **uncached\_prompt\_tokens**: Prompt tokens not served from cache (text inference only). `prompt_tokens - cached_prompt_tokens`. Older usage records and non-text usage types may not have a cached/uncached split in the underlying data. Exports normalize these rows to `cached_prompt_tokens=0` and `uncached_prompt_tokens=prompt_tokens`, so `prompt_tokens = cached_prompt_tokens + uncached_prompt_tokens` always holds. ### Sample row ```csv theme={null} email,start_time,end_time,usage_type,accelerator_type,accelerator_seconds,base_model_name,model_bucket,parameter_count,prompt_tokens,completion_tokens,cached_prompt_tokens,uncached_prompt_tokens user@example.com,2025-10-20 17:16:48 UTC,2025-10-20 17:16:48 UTC,TEXT_COMPLETION_INFERENCE_USAGE,,,accounts/fireworks/models/llama4-maverick-instruct-basic,Llama 4 Maverick Basic,401583781376,803,109,200,603 ``` ## Automation Each `firectl billing export-metrics` call supports a maximum 31-day time range. To export longer historical ranges, run the command in multiple 31-day chunks and combine the CSV files in your downstream pipeline. You can automate exports in cron jobs and load the CSV into your internal systems: ```bash theme={null} # Example: Daily export with dated filename firectl billing export-metrics \ --start-time "$(date -v-1d '+%Y-%m-%d')" \ --end-time "$(date '+%Y-%m-%d')" \ --filename "billing_$(date '+%Y%m%d').csv" ``` ```bash theme={null} # Example: Backfill 6 months in 31-day chunks start_date="2025-01-01" end_date="2025-07-01" current_start="$start_date" while [ "$(date -j -f "%Y-%m-%d" "$current_start" "+%s")" -lt "$(date -j -f "%Y-%m-%d" "$end_date" "+%s")" ]; do current_end="$(date -j -v+31d -f "%Y-%m-%d" "$current_start" "+%Y-%m-%d")" # Clamp the chunk end to the requested end_date if [ "$(date -j -f "%Y-%m-%d" "$current_end" "+%s")" -gt "$(date -j -f "%Y-%m-%d" "$end_date" "+%s")" ]; then current_end="$end_date" fi firectl billing export-metrics \ --start-time "$current_start" \ --end-time "$current_end" \ --filename "billing_${current_start}_to_${current_end}.csv" current_start="$current_end" done ``` Run `firectl billing export-metrics --help` to see all available flags and options. ## Coverage This export includes: * **Serverless inference**: All serverless API usage * **On-demand deployments**: Deployment usage (see also [Exporting deployment metrics](/deployments/exporting-metrics) for real-time Prometheus metrics) * **Training jobs**: Training compute usage * **Other services**: All billable Fireworks services For real-time monitoring of on-demand deployment performance metrics (latency, throughput, etc.), use the [Prometheus metrics endpoint](/deployments/exporting-metrics) instead. ## See also * [firectl CLI overview](/tools-sdks/firectl/firectl) * [Exporting Usage Costs](/accounts/exporting-usage-costs) - Rated serverless cost CSV grouped by model, model tier, user, or API key * [Exporting deployment metrics](/deployments/exporting-metrics) - Real-time Prometheus metrics for on-demand deployments * [Account quotas](/guides/quotas_usage/account-quotas) - Spending tiers, monthly spend limits, and account-wide request limits * [Serverless rate limits](/serverless/rate-limits) - Adaptive serverless TPM bounds # Usage & Cost Breakdown Source: https://docs.fireworks.ai/accounts/exporting-usage-and-costs 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](/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`](/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`](/api-reference/get-billing-usage) returns the usage breakdown, and its companion [`GET /v1/accounts/{account_id}/billing/summary`](/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](/api-reference/query-usage-costs). For a ready-made CSV of the same data, use [`firectl billing export-usage-costs`](/accounts/exporting-usage-costs). This page complements the two CSV exports: use [`export-metrics`](/accounts/exporting-billing-metrics) for a raw per-event dump, [`export-usage-costs`](/accounts/exporting-usage-costs) for rated serverless costs grouped by model, model tier, user, or API key, and the workflows here for ad-hoc 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`](/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](/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 [Usage annotations](#usage-annotations-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`. ## Usage annotations (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. Supported usage annotations from the sources described below are recorded on usage regardless of plan, so past usage containing them becomes available for these breakdowns once the account is on Enterprise. Deployment tags and usage annotations are separate features. Tags managed with `firectl deployment tag` or stored under `custom/*` do not populate the `annotations.team`, `annotations.project`, or `annotations.environment` billing dimensions. 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**: existing `team`, `project`, and `environment` annotations remain unchanged and continue to appear in usage reports. New values cannot currently be configured through customer-facing deployment tag APIs. * **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](/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](/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`](/tools-sdks/firectl/commands/billing-get-usage) - CLI command reference * [`GET /v1/accounts/{account_id}/billingUsage`](/api-reference/get-billing-usage) - HTTP API reference * [`GET /v1/accounts/{account_id}/billing/summary`](/api-reference/get-billing-summary) - Rated dollar costs by billing category, with optional daily breakdown * [`POST /v1/accounts/{account_id}/usageCosts:query`](/api-reference/query-usage-costs) - Rated dollar subtotals grouped by hour/day/model/user/API key * [Exporting Usage Costs](/accounts/exporting-usage-costs) - Rated serverless cost CSV via `firectl billing export-usage-costs` * [Exporting Billing Metrics](/accounts/exporting-billing-metrics) - Raw per-event billing CSV export * [Account quotas](/guides/quotas_usage/account-quotas) - Spending tiers and monthly spend limits # Exporting Usage Costs Source: https://docs.fireworks.ai/accounts/exporting-usage-costs Export rated serverless usage costs to CSV, grouped by model, model tier, user, or API key ## Overview Fireworks provides a CLI tool to export **rated dollar costs** for serverless inference as a CSV. Rows are bucketed by UTC day and grouped by one dimension you choose — model, model tier, user, or API key — which makes it the fastest way to produce a chargeback or per-team spend report. The export is the CSV counterpart of [`POST /usageCosts:query`](/api-reference/query-usage-costs). * **This page** — rated dollar costs for serverless inference, as a CSV grouped by model, model tier, user, or API key. * **[Exporting Billing Metrics](/accounts/exporting-billing-metrics)** — metered quantities (tokens, accelerator-seconds) for every usage type, one CSV row per usage event. No dollars. * **[Usage & Cost Breakdown](/accounts/exporting-usage-and-costs)** — the same data as ad-hoc CLI or HTTP API queries rather than a CSV, with richer grouping and filtering. This export reports costs for the whole account, so it requires **account administrator** access. Non-admin users can read their own costs through [`POST /usageCosts:query`](/api-reference/query-usage-costs) at `SELF` scope. ## Exporting usage costs ```bash theme={null} # Authenticate (once) firectl login # Export usage costs to CSV firectl billing export-usage-costs ``` With no flags, this exports the last 24 hours grouped by model and writes `usage_costs.csv` to the current directory. ## Examples Group costs by API key instead of model: ```bash theme={null} firectl billing export-usage-costs --group-by api_key ``` Export a specific date range, dimension, and filename: ```bash theme={null} firectl billing export-usage-costs \ --start-time "2026-05-01" \ --end-time "2026-06-01" \ --group-by user \ --filename may_costs_by_user.csv ``` ## Output format The exported CSV always has these six columns, regardless of which dimension you group by: * **account\_id**: Your Fireworks account ID * **date**: UTC day bucket, as `YYYY-MM-DD` * **group\_by\_dimension**: The dimension the row is grouped by — `model`, `model_tier`, `user`, or `api_key` * **group\_by\_value**: The value for that dimension (see below) * **subtotal\_usd**: Rated cost for that day and value, as an exact decimal with nine fractional digits * **currency**: Currency code for `subtotal_usd`, for example `USD` `group_by_value` depends on `--group-by`: | `--group-by` | `group_by_value` | | ----------------- | ---------------------------------------------------------------------------- | | `model` (default) | Model resource name, e.g. `accounts/my-account/models/glm-5p2` | | `model_tier` | Serving capability tier used to price the usage, e.g. `GLM 5.2 (Fast)` | | `user` | User resource name, e.g. `accounts/my-account/users/alice` | | `api_key` | Stable API key ID, e.g. `key_4nMFyHCSZP4CRKqa`. Never plaintext key material | Two reserved values can appear in `group_by_value`: `unattributed`, when the underlying billing event carries no value for the requested dimension, and `unknown_model`, when a billing model can't be mapped to a public model. Days with an exact-zero subtotal are omitted rather than written as `0.000000000` rows, so a dimension value only appears on days it actually cost money. ### Sample row ```csv theme={null} account_id,date,group_by_dimension,group_by_value,subtotal_usd,currency my-account,2026-05-14,model,accounts/my-account/models/glm-5p2,8.400000000,USD ``` ## Automation Each `firectl billing export-usage-costs` call supports a maximum 31-day time range, and `--start-time` cannot be more than 100 days in the past. To export longer historical ranges, run the command in multiple 31-day chunks and combine the CSV files in your downstream pipeline. ```bash theme={null} # Example: Daily export with dated filename firectl billing export-usage-costs \ --start-time "$(date -v-1d '+%Y-%m-%d')" \ --end-time "$(date '+%Y-%m-%d')" \ --group-by api_key \ --filename "usage_costs_$(date '+%Y%m%d').csv" ``` ```bash theme={null} # Example: Backfill 90 days in 31-day chunks start_date="2026-03-01" end_date="2026-06-01" current_start="$start_date" while [ "$(date -j -f "%Y-%m-%d" "$current_start" "+%s")" -lt "$(date -j -f "%Y-%m-%d" "$end_date" "+%s")" ]; do current_end="$(date -j -v+31d -f "%Y-%m-%d" "$current_start" "+%Y-%m-%d")" # Clamp the chunk end to the requested end_date if [ "$(date -j -f "%Y-%m-%d" "$current_end" "+%s")" -gt "$(date -j -f "%Y-%m-%d" "$end_date" "+%s")" ]; then current_end="$end_date" fi firectl billing export-usage-costs \ --start-time "$current_start" \ --end-time "$current_end" \ --filename "usage_costs_${current_start}_to_${current_end}.csv" current_start="$current_end" done ``` Run `firectl billing export-usage-costs --help` to see all available flags and options. ## Coverage * **Serverless token usage only.** Costs are priced from cached input, uncached input, and output tokens. Dedicated deployment and training spend are not included — for those, use [Exporting Billing Metrics](/accounts/exporting-billing-metrics) or the account-level totals from [`firectl billing get-usage --account-costs-only`](/accounts/exporting-usage-and-costs#account-level-cost-totals-only). * **Subtotals are rated, not invoiced.** They price usage with the subscription prices that apply to your account and exclude fixed fees, invoice-level discounts, minimums, credits, and taxes, so they may differ from the final invoice. * **One dimension at a time.** Rows are always bucketed by day plus the single dimension passed to `--group-by`. To combine dimensions, use [`POST /usageCosts:query`](/api-reference/query-usage-costs), which accepts up to two. ## See also * [`POST /v1/accounts/{account_id}/usageCosts:query`](/api-reference/query-usage-costs) - The HTTP API behind this export * [Exporting Billing Metrics](/accounts/exporting-billing-metrics) - Raw per-event usage CSV across all usage types * [Usage & Cost Breakdown](/accounts/exporting-usage-and-costs) - Grouped usage and rated cost queries via `firectl billing get-usage` and the billing APIs * [Serverless pricing](/serverless/pricing) - Published per-token prices # Model access policy Source: https://docs.fireworks.ai/accounts/model-access-policy Restrict which models users on your Enterprise account can access for inference, deployments, and training Model access policy lets Enterprise account admins control which models users on the account can use. You can allowlist models (deny by default, then permit specific models) or deny specific models while leaving the rest of the catalog open. **Enterprise feature.** Model access policy is available on Enterprise accounts. Contact your Fireworks representative if you need this enabled. Policy applies **account-wide**: every user on the account shares the same rules. There is no per-user or per-group model access control today. ## What it controls Each model can be allowed or denied independently across four capabilities: | Capability | What it governs | | :------------------------ | :---------------------------------------------------------------- | | **Serverless inference** | Chat, completions, embeddings, and other serverless API routes | | **Serverless Fast** | The model's Fast serving mode (separate from standard serverless) | | **Dedicated deployments** | Creating on-demand deployments on that base model | | **Training** | Supervised fine-tuning, DPO, and reinforcement fine-tuning jobs | Fast mode is evaluated separately from standard serverless. You can allow one without the other. ## Default behavior Accounts that never configure a policy keep today's open default: **all models are allowed** for all users. | State | Effect | | :--------------------------------------- | :---------------------------- | | No policy configured | All models allowed | | After `policy clear` | All models allowed (restored) | | Deny-all default + per-model allow rules | Only listed models allowed | ## Configure in the console Account admins can manage model access policy in the Fireworks console at **Settings → Governances → Model Access** ([open in console](https://app.fireworks.ai/settings/governances/model-access)). Use the console to allowlist or block models and toggle capabilities (serverless, Fast, deployments, and training) without using the CLI or API. You can also configure policy with [firectl](#allowlist-a-set-of-models) or the [REST API](#rest-api). ## Allowlist a set of models The most common pattern is to deny everything by default and allow only the models your organization approves. ```bash theme={null} firectl policy allowlist qwen3-235b-a22b kimi-k2-instruct ``` This sets a deny-all default and creates one allow rule per model ID. By default, all four capabilities are allowed for each listed model. To allow only serverless inference (not training or deployments): ```bash theme={null} firectl policy allowlist qwen3-235b-a22b \ --deployments=false --training=false ``` Inspect the active policy: ```bash theme={null} firectl policy get ``` Restore the open default: ```bash theme={null} firectl policy clear ``` ## Deny specific models (blocklist) To block individual models while leaving the rest of the catalog open, add per-model deny rules without changing the default: ```bash theme={null} firectl policy set \ --serverless=false --serverless-fast=false --deployments=false --training=false ``` Or set a partial deny, such as blocking Fast mode only: ```bash theme={null} firectl policy set --serverless-fast=false ``` ## Step-by-step allowlist If you prefer explicit steps instead of `policy allowlist`: ```bash theme={null} # 1. Deny all models by default firectl policy set-default --deny-all # 2. Allow specific models (hosted models use the fireworks account) firectl policy set qwen3-235b-a22b --model-account fireworks firectl policy set kimi-k2-instruct --model-account fireworks ``` Remove a model from the allowlist: ```bash theme={null} firectl policy remove ``` ## Authorization | Action | Who | | :------------ | :----------------- | | View policy | Any account member | | Update policy | Account **Admin** | ## REST API Account admins can also manage policy through the API: * `GET /v1/accounts/{account_id}/policySettings` * `PATCH /v1/accounts/{account_id}/policySettings` Example allowlist body: ```json theme={null} { "name": "accounts/my-account/policySettings", "defaultPermissions": { "allowServerless": false, "allowServerlessFast": false, "allowDedicatedDeployments": false, "allowTraining": false }, "rules": [ { "model": "accounts/fireworks/models/qwen3-235b-a22b", "permissions": { "allowServerless": true, "allowServerlessFast": true, "allowDedicatedDeployments": true, "allowTraining": false } } ] } ``` All four permission booleans are required whenever `defaultPermissions` or a rule's `permissions` object is sent. ## Important limitations * **Account-wide only.** Policy cannot differentiate access between teams, divisions, or individual users on the same account. * **Explicit model IDs.** Rules are keyed on model resource names (for example `accounts/fireworks/models/qwen3-235b-a22b`). You must list the models you want to control. * **Hosted models in rules.** New per-model rules apply to Fireworks-hosted serverless models. If you use a deny-all default and need to permit training or deployments on your own uploaded base models, configure those capabilities in `defaultPermissions` instead of per-model rules. * **Propagation delay.** Policy changes are not instant at the API edge. Allow up to several minutes (and up to an hour for idle API keys) before assuming a change has taken effect everywhere. * **Rule limit.** An account can store roughly 85 per-model rules. ## Related * [Enterprise features](/accounts/enterprise-features) — overview of Enterprise administration capabilities * [Managing users](/accounts/users) — account roles and permissions * [Audit & access logs](/guides/security_compliance/audit_logs) — monitor account activity # Service Accounts Source: https://docs.fireworks.ai/accounts/service-accounts How to manage and use service accounts in Fireworks Service accounts in Fireworks allow applications, scripts, and automated systems to authenticate and perform actions securely—without relying on human credentials. They are ideal for CI/CD pipelines, backend services, and automated workflows. Service Accounts let you avoid shared credentials and easily distinguish between what automated systems did vs humans in audit logs. Service accounts can take actions using an API key, like creating deployments, running models or creating datasets (see [API reference](https://fireworks.ai/docs/api-reference/introduction)). Service accounts cannot login through the web interface or use OIDC tokens. To manage service accounts via the Fireworks web UI visit [app.fireworks.ai/account/users](https://app.fireworks.ai/account/users). ## Creating a Service Account Using our firectl you can create service accounts ```bash theme={null} firectl user create --user-id "my-service-account" --service-account ``` ## Creating an API Key for a Service Account Using firectl you can create an API key on behalf of a service account: ```bash theme={null} firectl api-key create --service-account "my-service-account" ``` ## Roles You can assign a role when creating a service account using the `--role` flag: ```bash theme={null} firectl user create --user-id "my-service-account" --service-account --role=contributor ``` If not specified, the default service account role is `user`. To change the role of an existing service account, use the update command: ```bash theme={null} firectl user update my-service-account --role=inference-user ``` See [Managing users](/accounts/users) for available roles. ## Listing Service Accounts To list all service accounts in your account: ```bash theme={null} firectl user list --filter 'service_account=true' ``` ## Billing * Service accounts count toward the same account quotas and limits assigned to the account * Usage is tracked by the account, not individual user vs service account ## Auditing In audit logs users are referenced by their email id's. Service accounts are referenced by `my-service-account@my-account.sa.fireworks.ai`. # Custom SSO Source: https://docs.fireworks.ai/accounts/sso Set up custom Single Sign-On (SSO) authentication and SCIM user and group provisioning for Fireworks AI Fireworks uses single sign-on (SSO) as the primary mechanism to authenticate with the platform. By default, Fireworks supports Google SSO. If you have an enterprise account, Fireworks supports bringing your own identity provider using: * OpenID Connect (OIDC) provider * SAML 2.0 provider * Optionally, the work-email domain your users sign in with, so they can start SSO by entering their email instead of your account ID Coordinate with your Fireworks AI representative to enable the integration. ## OpenID Connect (OIDC) provider Create an OIDC client application in your identity provider, e.g. Okta. Ensure the client is configured for "code authorization" of the "web" type (i.e. with a client\_secret). Set the client's "allowed redirect URL" to the URL provided by Fireworks. It looks like: ``` https://fireworks-.auth.us-west-2.amazoncognito.com/oauth2/idpresponse ``` Note down the `issuer`, `client_id`, and `client_secret` for the newly created client. You will need to provide this to your Fireworks.ai representative to complete your account set up. ## SAML 2.0 provider Create a SAML 2.0 application in your identity provider, e.g. [Okta](https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_SAML.htm). Set the SSO URL to the URL provided by Fireworks. It looks like: ``` https://fireworks-.auth.us-west-2.amazoncognito.com/saml2/idpresponse ``` Configure the Audience URI (SP Entity ID) as provided by Fireworks. It looks like: ``` urn:amazon:cognito:sp: ``` Create an Attribute Statement with the name: ``` http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress ``` and the value `user.email` **Okta:** After saving the app, open **Sign On** → **Attribute Statements (SAML)** → expand **Show legacy configuration** → add the attribute statement there. Okta no longer configures this during app creation. Leave the rest of the settings as defaults. Note down the "metadata url" for your newly created application. You will need to provide this to your Fireworks AI representative to complete your account set up. If the metadata URL is not publicly reachable, provide the metadata XML file instead. ## SAML sign-in flow By default, Fireworks uses **service provider (SP) initiated** SAML: users start at [app.fireworks.ai](https://app.fireworks.ai) or with `firectl signin` and are redirected to your identity provider. **IdP-initiated** SAML is supported as an opt-in for SAML identity providers. When enabled, users can also start from your identity provider's portal (for example, the Okta app tile). Enable it with [`--enable-idp-initiated-sso`](/tools-sdks/firectl/commands/identity-provider-create) when creating or updating the identity provider. This option is SAML-only; OIDC providers cannot use it. ## Just-In-Time (JIT) user provisioning JIT user provisioning automatically creates user accounts when they sign in through SSO for the first time. When enabled, users who authenticate through your identity provider are automatically added to your Fireworks account without requiring manual user creation. To enable JIT user provisioning, use the [`--enable-jit-user-provisioning`](/tools-sdks/firectl/commands/identity-provider-create) flag when creating your identity provider with firectl. ## SCIM provisioning System for Cross-domain Identity Management (SCIM) provisioning synchronizes the user and group lifecycle between your identity provider and Fireworks. Users assigned to Fireworks in your directory are added to your Fireworks account, and users are removed when they are deactivated or unassigned in the directory. SCIM provisioning is available for enterprise accounts and works with supported directory providers, including Okta, Microsoft Entra ID, and Google Workspace. Fireworks uses [WorkOS Directory Sync](https://workos.com/docs/directory-sync) to connect to your directory. SCIM manages provisioning only. Users continue to authenticate through your existing OIDC or SAML SSO integration. ### Set up SCIM provisioning Complete the OIDC or SAML setup above. Custom SSO must be configured before you can enable SCIM provisioning. Contact your Fireworks AI representative. Fireworks will enable Directory Sync for your account and provide a secure setup link. Open the setup link, select your directory provider, and follow the provider-specific instructions to authorize the connection. In your identity provider, assign the users who should have access to Fireworks, plus any groups you want mirrored into Fireworks. Confirm that they appear on the **Users** and **Groups** tabs of the [Users page](https://app.fireworks.ai/account/users). ### Group provisioning Directory groups assigned to Fireworks are synced alongside your users. Creating, renaming, or deleting a group in your directory creates, updates, or deletes the matching Fireworks group, and adding or removing someone from a directory group changes their Fireworks group membership. Deleting a group removes its memberships; the users themselves are unaffected. Synced groups appear on the **Groups** tab of the [Users page](https://app.fireworks.ai/account/users), marked `SCIM-synced`, with their member count and the time of the last sync. Directory sync is the only way to create a Fireworks group, and groups are read-only in Fireworks — your directory is the source of truth for both the group and its membership. Synced groups have one use in Fireworks today: assigning them a [group limit](/fireworks-nexus/usage-limits#group-limits), which caps serverless spend for each of the group's members. That is a **Fireworks Nexus** feature and is enabled separately — syncing groups does not by itself give your account spend limits. Group-to-role mappings are not currently supported: a group's members do not inherit a role from the group, and provisioned users receive the `User` role by default. Set roles per user as described in [Managing users](/accounts/users#updating-a-users-role). We recommend disabling JIT provisioning when SCIM is enabled so that your directory remains the source of truth for account membership. SSO enforcement is also recommended to prevent access outside your configured identity provider. ## Enforce SSO When SSO enforcement is enabled, account access is restricted to users with approved tenant domains only. Users with matching domains must authenticate via the identity provider, and users with other domains are blocked. API keys and service accounts are not blocked by SSO enforcement. To enforce SSO, use the [`--enforce-sso`](/tools-sdks/firectl/commands/identity-provider-create) flag when creating your identity provider with firectl, or toggle "Enforce SSO for all users" in the Fireworks console. ## Troubleshooting ### Invalid samlResponse or relayState from identity provider This error usually means the login started from the identity provider (IdP-initiated) but IdP-initiated SAML is not enabled for your identity provider. * For SP-initiated login, start from [app.fireworks.ai](https://app.fireworks.ai) instead of your IdP's app tile. * For IdP-initiated login, enable [`--enable-idp-initiated-sso`](/tools-sdks/firectl/commands/identity-provider-create) on a SAML identity provider (or ask your Fireworks representative to enable it). See [Understanding SAML](https://developer.okta.com/docs/concepts/saml/#understand-sp-initiated-sign-in-flow) for SP-initiated versus IdP-initiated flows. ### Required String parameter 'RelayState' is not present Same cause as above: an IdP-initiated login without IdP-initiated SSO enabled. # Managing users Source: https://docs.fireworks.ai/accounts/users Add, delete, and manage roles for users in your Fireworks account See the concepts [page](/getting-started/concepts#account) for definitions of accounts and users. ## User roles Each user in an account is assigned a role that determines their level of access: | Role | Description | | :----------------- | :---------------------------------------------------------------------------------------------------------------------- | | **Admin** | Full administrative control over resources, users, and access. Can manage all account settings and add or remove users. | | **User** (default) | Can manage all resources, including those owned by others, but cannot manage users or access settings. | | **Contributor** | Can run inference on any resource and create and manage their own resources. Cannot modify resources owned by others. | | **Inference User** | Can view all resources and run inference, but cannot create or modify resources. | The `contributor` and `inference-user` roles are newer roles that provide more granular access control. Contact Fireworks support if you need these roles enabled for your account. #### Resource management | Permission | Inference User | Contributor | User | Admin | | :------------------------------------------------------------------ | :------------: | :---------: | :--: | :---: | | Execute inference on any deployment | ✅ | ✅ | ✅ | ✅ | | View all resources (deployments, models, training jobs, datasets) | ✅ | ✅ | ✅ | ✅ | | Create new resources (deployments, models, training jobs, datasets) | ❌ | ✅ | ✅ | ✅ | | Manage their own resources (edit/delete) | ❌ | ✅ | ✅ | ✅ | | Manage resources owned by others (edit/delete) | ❌ | ❌ | ✅ | ✅ | #### API key & account management | Permission | Inference User | Contributor | User | Admin | | :----------------------------------------------- | :------------: | :---------: | :--: | :---: | | Manage self-owned API keys (create/delete) | ✅ | ✅ | ✅ | ✅ | | View all users and service accounts | ✅ | ✅ | ✅ | ✅ | | Create service account API keys | ❌ | ❌ | ❌ | ✅ | | Delete other users and service accounts API keys | ❌ | ❌ | ❌ | ✅ | | Add/modify/delete users and their access | ❌ | ❌ | ❌ | ✅ | ## Adding users To add a new user to your Fireworks account, run the following command. If the email for the new user is already associated with a Fireworks account, they will have the option to freely switch between your account and their existing account(s). You can also add users in the Fireworks web UI at [https://app.fireworks.ai/account/users](https://app.fireworks.ai/account/users). ```bash theme={null} firectl user create --email="alice@example.com" ``` To create another admin user, pass the `--role=admin` flag: ```bash theme={null} firectl user create --email="alice@example.com" --role=admin ``` ## Updating a user's role To update a user's role, run ```bash theme={null} firectl user update --role= ``` Where `` is one of: `admin`, `user`, `contributor`, or `inference-user`. ## Deleting users You can remove a user from your account by running: ```bash theme={null} firectl user delete ``` ## Groups Users can be organized into groups. A group is a named set of users in your account; the **Groups** tab on the [Users page](https://app.fireworks.ai/account/users) lists each group with its member count and source, and the **Group** column on the Users tab shows which groups a user belongs to. Groups are provisioned from your identity provider through [SCIM group provisioning](/accounts/sso#group-provisioning), which is the only way to create one. They are read-only in Fireworks: create, rename, delete, and populate groups in your directory. Groups do not confer roles — roles are set per user. What a group can carry is a [group limit](/fireworks-nexus/usage-limits#group-limits), which caps serverless spend for each of its members. That is a **Fireworks Nexus** feature, enabled separately from group sync. # Create a Message Source: https://docs.fireworks.ai/api-reference/anthropic-messages post /v1/messages **Anthropic-compatible endpoint.** Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation. The Messages API can be used for either single queries or stateless multi-turn conversations. **Fireworks Quickstarts:** - [Serverless Quickstart](/getting-started/quickstart) - [Deployments Quickstart](/getting-started/ondemand-quickstart) This endpoint provides an Anthropic-compatible Messages API surface on Fireworks. For setup, supported features, and known differences, see [Anthropic compatibility](/tools-sdks/anthropic-compatibility). # Cancel Reinforcement Fine-tuning Job Source: https://docs.fireworks.ai/api-reference/cancel-reinforcement-fine-tuning-job post /v1/accounts/{account_id}/reinforcementFineTuningJobs/{reinforcement_fine_tuning_job_id}:cancel # Create API Key Source: https://docs.fireworks.ai/api-reference/create-api-key post /v1/accounts/{account_id}/users/{user_id}/apiKeys # Create Batch Inference Job Source: https://docs.fireworks.ai/api-reference/create-batch-inference-job post /v1/accounts/{account_id}/batchInferenceJobs # Create Dataset Source: https://docs.fireworks.ai/api-reference/create-dataset post /v1/accounts/{account_id}/datasets # Load LoRA Source: https://docs.fireworks.ai/api-reference/create-deployed-model post /v1/accounts/{account_id}/deployedModels # Create Deployment Source: https://docs.fireworks.ai/api-reference/create-deployment post /v1/accounts/{account_id}/deployments ## Creating a deployment with a deployment shape [Deployment shapes](/guides/ondemand-deployments#deployment-shapes) are pre-configured templates optimized for speed, cost, or efficiency. To create a deployment with a specific shape, pass the `deploymentShape` field in the request body along with `baseModel`. Use the [Match Deployment Shape Versions](/api-reference/match-deployment-shape-versions) endpoint to find available shapes for your model: it takes a deployment create request and returns the validated shape versions compatible with that model, ready to pass as `deploymentShape`. ```bash theme={null} curl -X POST "https://api.fireworks.ai/v1/accounts/YOUR_ACCOUNT_ID/deployments" \ -H "Authorization: Bearer $FIREWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "baseModel": "accounts/fireworks/models/gpt-oss-120b", "deploymentShape": "accounts/fireworks/deploymentShapes/gpt-oss-120b-minimal", "minReplicaCount": 0, "maxReplicaCount": 1 }' ``` When using a deployment shape, you do not need to specify `activeModelVersion` or `targetModelVersion` — the shape provides the necessary configuration. ## Always pass `deploymentShape` Shapes are validated, so the hardware, precision, and serving configuration are known to work together. Omitting `deploymentShape` — whether or not you set `acceleratorType`, `acceleratorCount`, or `precision` — creates the deployment without a shape. Deployments without a shape are the most common cause of failed deployment creations, and the unshaped path may be deprecated in the future: always pass `deploymentShape`. See [What is a deployment shape?](/faq-new/deployment-infrastructure/what-is-a-deployment-shape) for how to find shapes for your model. Each model is validated only on the accelerator type, GPU count, and precision combinations covered by its shapes — many models support just one. Check [Match Deployment Shape Versions](/api-reference/match-deployment-shape-versions) before overriding `acceleratorType` or `acceleratorCount`: an unsupported combination typically fails at creation with a generic `Internal error occurred` message that does not name the hardware mismatch. # Create dpo job Source: https://docs.fireworks.ai/api-reference/create-dpo-job post /v1/accounts/{account_id}/dpoJobs # Create Evaluation Job Source: https://docs.fireworks.ai/api-reference/create-evaluation-job post /v1/accounts/{account_id}/evaluationJobs # Create Evaluator Source: https://docs.fireworks.ai/api-reference/create-evaluator post /v1/accounts/{account_id}/evaluatorsV2 Creates a custom evaluator for scoring model outputs. Evaluators use the [Eval Protocol](https://evalprotocol.io) to define test cases, run model inference, and score responses. They are used with evaluation jobs and Reinforcement Fine-Tuning (RFT). ## Source Code Requirements Your project should contain: - `requirements.txt` - Python dependencies for your evaluator - `test_*.py` - Pytest test file(s) with [`@evaluation_test`](https://evalprotocol.io/reference/evaluation-test) decorated functions - Any additional code/modules your evaluator needs ## Workflow **Recommended:** Use the [`ep upload`](https://evalprotocol.io/reference/cli#ep-upload) CLI command to handle all these steps automatically. If using the API directly: 1. Call this endpoint to create the evaluator resource 2. Package your source directory as a `.tar.gz` (respecting `.gitignore`) 3. Call [Get Evaluator Upload Endpoint](/api-reference/get-evaluator-upload-endpoint) to get a signed upload URL 4. `PUT` the tar.gz file to the signed URL 5. Call [Validate Evaluator Upload](/api-reference/validate-evaluator-upload) to trigger server-side validation 6. Poll [Get Evaluator](/api-reference/get-evaluator) until ready Once active, reference the evaluator in [Create Evaluation Job](/api-reference/create-evaluation-job) or [Create Reinforcement Fine-tuning Job](/api-reference/create-reinforcement-fine-tuning-job). # Create Model Source: https://docs.fireworks.ai/api-reference/create-model post /v1/accounts/{account_id}/models # Create Reinforcement Fine-tuning Job Source: https://docs.fireworks.ai/api-reference/create-reinforcement-fine-tuning-job post /v1/accounts/{account_id}/reinforcementFineTuningJobs # Create Reinforcement Fine-tuning Step Source: https://docs.fireworks.ai/api-reference/create-reinforcement-fine-tuning-step post /v1/accounts/{account_id}/rlorTrainerJobs # Create Router Source: https://docs.fireworks.ai/api-reference/create-router post /v1/accounts/{account_id}/routers # Create secret Source: https://docs.fireworks.ai/api-reference/create-secret post /v1/accounts/{account_id}/secrets # Create Supervised Fine-tuning Job Source: https://docs.fireworks.ai/api-reference/create-supervised-fine-tuning-job post /v1/accounts/{account_id}/supervisedFineTuningJobs ## Learning rate scheduler Supervised fine-tuning jobs accept an optional `lrScheduler` object on the request body. Set **exactly one** of `constant`, `linear`, or `cosine`. When omitted, the trainer uses a constant learning rate after warmup. Configure warmup separately with `learningRateWarmupSteps` (not inside `lrScheduler`). | Schedule | Object shape | Notes | | ---------- | -------------------------------------------------------- | --------------------------------------------------- | | `constant` | `{ "constant": {} }` | Flat LR after warmup | | `linear` | `{ "linear": { "minLrRatio": 0.1, "decayRatio": 0.8 } }` | Linear decay toward `learningRate * minLrRatio` | | `cosine` | `{ "cosine": { "minLrRatio": 0.1, "decayRatio": 0.8 } }` | Cosine annealing toward `learningRate * minLrRatio` | For `linear` and `cosine`: * `minLrRatio` — floor LR as a fraction of `learningRate` (0.0–1.0). * `decayRatio` — fraction of total training steps over which to decay. Omit or set `0` to decay over the full run. `linear` and `cosine` require a base model on the **Training V2** path. V1-routed models only support a constant schedule. ### Example: cosine schedule ```json theme={null} { "supervisedFineTuningJob": { "baseModel": "accounts/my-account/models/qwen3-8b", "dataset": "accounts/my-account/datasets/my-data", "outputModel": "accounts/my-account/models/my-tuned-model", "learningRate": 0.0001, "learningRateWarmupSteps": 10, "lrScheduler": { "cosine": { "minLrRatio": 0.1, "decayRatio": 0.8 } } } } ``` See also [Training models](/fine-tuning/fine-tuning-models) for CLI equivalents (`--learning-rate-scheduler`, `--learning-rate-min-lr-ratio`, `--learning-rate-decay-ratio`). # Create User Source: https://docs.fireworks.ai/api-reference/create-user post /v1/accounts/{account_id}/users # Create embeddings Source: https://docs.fireworks.ai/api-reference/creates-an-embedding-vector-representing-the-input-text post /embeddings # Delete API Key Source: https://docs.fireworks.ai/api-reference/delete-api-key post /v1/accounts/{account_id}/users/{user_id}/apiKeys:delete # Delete Batch Inference Job Source: https://docs.fireworks.ai/api-reference/delete-batch-inference-job delete /v1/accounts/{account_id}/batchInferenceJobs/{batch_inference_job_id} # Delete Dataset Source: https://docs.fireworks.ai/api-reference/delete-dataset delete /v1/accounts/{account_id}/datasets/{dataset_id} # Unload LoRA Source: https://docs.fireworks.ai/api-reference/delete-deployed-model delete /v1/accounts/{account_id}/deployedModels/{deployed_model_id} # Delete Deployment Source: https://docs.fireworks.ai/api-reference/delete-deployment delete /v1/accounts/{account_id}/deployments/{deployment_id} # Delete dpo job Source: https://docs.fireworks.ai/api-reference/delete-dpo-job delete /v1/accounts/{account_id}/dpoJobs/{dpo_job_id} # Delete Evaluation Job Source: https://docs.fireworks.ai/api-reference/delete-evaluation-job delete /v1/accounts/{account_id}/evaluationJobs/{evaluation_job_id} # Delete Evaluator Source: https://docs.fireworks.ai/api-reference/delete-evaluator delete /v1/accounts/{account_id}/evaluators/{evaluator_id} Deletes an evaluator and its associated versions and build artifacts. # Delete Model Source: https://docs.fireworks.ai/api-reference/delete-model delete /v1/accounts/{account_id}/models/{model_id} # Delete Reinforcement Fine-tuning Job Source: https://docs.fireworks.ai/api-reference/delete-reinforcement-fine-tuning-job delete /v1/accounts/{account_id}/reinforcementFineTuningJobs/{reinforcement_fine_tuning_job_id} # Delete Reinforcement Fine-tuning Step Source: https://docs.fireworks.ai/api-reference/delete-reinforcement-fine-tuning-step delete /v1/accounts/{account_id}/rlorTrainerJobs/{rlor_trainer_job_id} # Delete Response Source: https://docs.fireworks.ai/api-reference/delete-response delete /v1/responses/{response_id} Deletes a model response by its ID. Once deleted, the response data will be gone immediately and permanently. The response cannot be recovered and any conversations that reference this response ID will no longer be able to access it. # Delete Router Source: https://docs.fireworks.ai/api-reference/delete-router delete /v1/accounts/{account_id}/routers/{router_id} # Delete secret Source: https://docs.fireworks.ai/api-reference/delete-secret delete /v1/accounts/{account_id}/secrets/{secret_id} # Delete Supervised Fine-tuning Job Source: https://docs.fireworks.ai/api-reference/delete-supervised-fine-tuning-job delete /v1/accounts/{account_id}/supervisedFineTuningJobs/{supervised_fine_tuning_job_id} # Execute reinforcement fine tuning step Source: https://docs.fireworks.ai/api-reference/execute-reinforcement-fine-tuning-step post /v1/accounts/{account_id}/rlorTrainerJobs/{rlor_trainer_job_id}:executeTrainStep # Get Account Source: https://docs.fireworks.ai/api-reference/get-account get /v1/accounts/{account_id} # Get Batch Inference Job Source: https://docs.fireworks.ai/api-reference/get-batch-inference-job get /v1/accounts/{account_id}/batchInferenceJobs/{batch_inference_job_id} # Get billing summary information for an account Source: https://docs.fireworks.ai/api-reference/get-billing-summary get /v1/accounts/{account_id}/billing/summary # Get Account Usage Source: https://docs.fireworks.ai/api-reference/get-billing-usage get /v1/accounts/{account_id}/billingUsage # Get Dataset Source: https://docs.fireworks.ai/api-reference/get-dataset get /v1/accounts/{account_id}/datasets/{dataset_id} # Get Dataset Download Endpoint Source: https://docs.fireworks.ai/api-reference/get-dataset-download-endpoint get /v1/accounts/{account_id}/datasets/{dataset_id}:getDownloadEndpoint # Get Dataset Upload Endpoint Source: https://docs.fireworks.ai/api-reference/get-dataset-upload-endpoint post /v1/accounts/{account_id}/datasets/{dataset_id}:getUploadEndpoint # Get LoRA Source: https://docs.fireworks.ai/api-reference/get-deployed-model get /v1/accounts/{account_id}/deployedModels/{deployed_model_id} # Get Deployment Source: https://docs.fireworks.ai/api-reference/get-deployment get /v1/accounts/{account_id}/deployments/{deployment_id} # Get Deployment Shape Source: https://docs.fireworks.ai/api-reference/get-deployment-shape get /v1/accounts/{account_id}/deploymentShapes/{deployment_shape_id} # Get Deployment Shape Version Source: https://docs.fireworks.ai/api-reference/get-deployment-shape-version get /v1/accounts/{account_id}/deploymentShapes/{deployment_shape_id}/versions/{version_id} # Get dpo job Source: https://docs.fireworks.ai/api-reference/get-dpo-job get /v1/accounts/{account_id}/dpoJobs/{dpo_job_id} # Get dpo job metrics file endpoint Source: https://docs.fireworks.ai/api-reference/get-dpo-job-metrics-file-endpoint get /v1/accounts/{account_id}/dpoJobs/{dpo_job_id}:getMetricsFileEndpoint # Get Evaluation Job Source: https://docs.fireworks.ai/api-reference/get-evaluation-job get /v1/accounts/{account_id}/evaluationJobs/{evaluation_job_id} # Get Evaluation Job execution logs (stream log endpoint + tracing IDs). Source: https://docs.fireworks.ai/api-reference/get-evaluation-job-log-endpoint get /v1/accounts/{account_id}/evaluationJobs/{evaluation_job_id}:getExecutionLogEndpoint # Get Evaluator Source: https://docs.fireworks.ai/api-reference/get-evaluator get /v1/accounts/{account_id}/evaluators/{evaluator_id} Retrieves an evaluator by name. Use this to monitor build progress after creation (**step 6** in the [Create Evaluator](/api-reference/create-evaluator) workflow). Possible states: - `BUILDING` - Environment is being prepared - `ACTIVE` - Evaluator is ready to use - `BUILD_FAILED` - Check build logs via [Get Evaluator Build Log Endpoint](/api-reference/get-evaluator-build-log-endpoint) # Get Evaluator Build Log Endpoint Source: https://docs.fireworks.ai/api-reference/get-evaluator-build-log-endpoint get /v1/accounts/{account_id}/evaluators/{evaluator_id}:getBuildLogEndpoint Returns a signed URL to download the evaluator's build logs. Useful for debugging `BUILD_FAILED` state. # Get Evaluator Source Code Endpoint Source: https://docs.fireworks.ai/api-reference/get-evaluator-source-code-endpoint get /v1/accounts/{account_id}/evaluators/{evaluator_id}:getSourceCodeSignedUrl Returns a signed URL to download the evaluator's source code archive. Useful for debugging or reviewing the uploaded code. # Get Evaluator Upload Endpoint Source: https://docs.fireworks.ai/api-reference/get-evaluator-upload-endpoint post /v1/accounts/{account_id}/evaluators/{evaluator_id}:getUploadEndpoint Returns signed URLs for uploading evaluator source code (**step 3** in the [Create Evaluator](/api-reference/create-evaluator) workflow). After receiving the signed URL, upload your `.tar.gz` archive using HTTP `PUT` with `Content-Type: application/octet-stream` header. # Get Model Source: https://docs.fireworks.ai/api-reference/get-model get /v1/accounts/{account_id}/models/{model_id} # Get Model Download Endpoint Source: https://docs.fireworks.ai/api-reference/get-model-download-endpoint get /v1/accounts/{account_id}/models/{model_id}:getDownloadEndpoint # Get Model Upload Endpoint Source: https://docs.fireworks.ai/api-reference/get-model-upload-endpoint post /v1/accounts/{account_id}/models/{model_id}:getUploadEndpoint # Get Quota Source: https://docs.fireworks.ai/api-reference/get-quota get /v1/accounts/{account_id}/quotas/{quota_id} Gets a single quota by resource name. # Get Reinforcement Fine-tuning Job Source: https://docs.fireworks.ai/api-reference/get-reinforcement-fine-tuning-job get /v1/accounts/{account_id}/reinforcementFineTuningJobs/{reinforcement_fine_tuning_job_id} # Get Reinforcement Fine-tuning Step Source: https://docs.fireworks.ai/api-reference/get-reinforcement-fine-tuning-step get /v1/accounts/{account_id}/rlorTrainerJobs/{rlor_trainer_job_id} # Get Response Source: https://docs.fireworks.ai/api-reference/get-response get /v1/responses/{response_id} # CRUD APIs for routers. Get Router Source: https://docs.fireworks.ai/api-reference/get-router get /v1/accounts/{account_id}/routers/{router_id} # Get Secret Source: https://docs.fireworks.ai/api-reference/get-secret get /v1/accounts/{account_id}/secrets/{secret_id} Retrieves a secret by name. Note that the `value` field is not returned in the response for security reasons. Only the `name` and `key_name` fields are included. # Get Supervised Fine-tuning Job Source: https://docs.fireworks.ai/api-reference/get-supervised-fine-tuning-job get /v1/accounts/{account_id}/supervisedFineTuningJobs/{supervised_fine_tuning_job_id} # Get User Source: https://docs.fireworks.ai/api-reference/get-user get /v1/accounts/{account_id}/users/{user_id} # Introduction Source: https://docs.fireworks.ai/api-reference/introduction Fireworks AI REST API enables you to interact with various language, image and embedding models using an API Key. It also lets you automate management of models, deployments, datasets, and more. ## Authentication All requests made to the Fireworks AI REST API must include an `Authorization` header with a valid `Bearer` token using your API key, along with the `Content-Type: application/json` header. ### Getting your API key You can obtain an API key by: * Using the [`firectl api-key create`](/tools-sdks/firectl/commands/api-key-create) command * Generating one through the [Fireworks AI dashboard](https://app.fireworks.ai/settings/users/api-keys) ### Request headers Include the following headers in your REST API requests: ```json theme={null} authorization: Bearer content-type: application/json ``` ## Account management APIs In addition to inference and deployment APIs, Fireworks exposes account-scoped quota endpoints. * [List Quotas](/api-reference/list-quotas) * [Get Quota](/api-reference/get-quota) * [Update Quota](/api-reference/update-quota) # List Accounts Source: https://docs.fireworks.ai/api-reference/list-accounts get /v1/accounts # List API Keys Source: https://docs.fireworks.ai/api-reference/list-api-keys get /v1/accounts/{account_id}/users/{user_id}/apiKeys List API keys for the user named in `user_id`. Admins can pass `-` as `user_id` to list keys for all users and service accounts in the account (equivalent to [`firectl api-key list --all-users`](/tools-sdks/firectl/commands/api-key-list)). ```bash theme={null} curl -s "https://api.fireworks.ai/v1/accounts/${ACCOUNT_ID}/users/-/apiKeys" \ -H "Authorization: Bearer ${FIREWORKS_API_KEY}" ``` # List User Audit Logs Source: https://docs.fireworks.ai/api-reference/list-audit-logs get /v1/accounts/{account_id}/auditLogs # List Batch Inference Jobs Source: https://docs.fireworks.ai/api-reference/list-batch-inference-jobs get /v1/accounts/{account_id}/batchInferenceJobs # List Datasets Source: https://docs.fireworks.ai/api-reference/list-datasets get /v1/accounts/{account_id}/datasets # List LoRAs Source: https://docs.fireworks.ai/api-reference/list-deployed-models get /v1/accounts/{account_id}/deployedModels # List Deployment Shapes Versions Source: https://docs.fireworks.ai/api-reference/list-deployment-shape-versions get /v1/accounts/{account_id}/deploymentShapes/{deployment_shape_id}/versions Use this endpoint to query available deployment shape versions for a given model. Use `-` as a wildcard for both `account_id` and `deployment_shape_id` to search across all accounts and shapes. ## Example: List shapes for a model To list validated deployment shapes for a specific model, use the `filter` parameter with `snapshot.base_model` and `latest_validated=true`: ```bash theme={null} curl -s "https://api.fireworks.ai/v1/accounts/-/deploymentShapes/-/versions?filter=snapshot.base_model%3D%22accounts%2Ffireworks%2Fmodels%2Fgpt-oss-120b%22%20AND%20latest_validated%3Dtrue&order_by=create_time%20desc" \ -H "Authorization: Bearer $FIREWORKS_API_KEY" | jq . ``` ### Filter syntax The `filter` parameter uses [AIP-160 filtering](https://google.aip.dev/160). Common patterns: | Filter | Description | | ------------------------------------------------------------ | ------------------------------------------------------ | | `snapshot.base_model="accounts/fireworks/models/MODEL_NAME"` | Filter by base model | | `latest_validated=true` | Only return the latest validated version of each shape | Combine multiple conditions with `AND`: ``` snapshot.base_model="accounts/fireworks/models/MODEL_NAME" AND latest_validated=true ``` Remember to URL-encode the filter value when using curl directly. `=` becomes `%3D`, `"` becomes `%22`, and `/` becomes `%2F`. # List Deployments Source: https://docs.fireworks.ai/api-reference/list-deployments get /v1/accounts/{account_id}/deployments # List dpo jobs Source: https://docs.fireworks.ai/api-reference/list-dpo-jobs get /v1/accounts/{account_id}/dpoJobs # List Evaluation Jobs Source: https://docs.fireworks.ai/api-reference/list-evaluation-jobs get /v1/accounts/{account_id}/evaluationJobs # List Evaluators Source: https://docs.fireworks.ai/api-reference/list-evaluators get /v1/accounts/{account_id}/evaluators Lists all evaluators for an account with pagination support. # List Models Source: https://docs.fireworks.ai/api-reference/list-models get /v1/accounts/{account_id}/models # List Quotas Source: https://docs.fireworks.ai/api-reference/list-quotas get /v1/accounts/{account_id}/quotas Lists all quotas for an account. # List Reinforcement Fine-tuning Jobs Source: https://docs.fireworks.ai/api-reference/list-reinforcement-fine-tuning-jobs get /v1/accounts/{account_id}/reinforcementFineTuningJobs # List Reinforcement Fine-tuning Steps Source: https://docs.fireworks.ai/api-reference/list-reinforcement-fine-tuning-steps get /v1/accounts/{account_id}/rlorTrainerJobs # List Responses Source: https://docs.fireworks.ai/api-reference/list-responses get /v1/responses Get a list of all responses for the authenticated account. Args: limit: Maximum number of responses to return (default: 20, max: 100) after: Cursor for pagination - return responses after this ID before: Cursor for pagination - return responses before this ID # List Routers Source: https://docs.fireworks.ai/api-reference/list-routers get /v1/accounts/{account_id}/routers # List Secrets Source: https://docs.fireworks.ai/api-reference/list-secrets get /v1/accounts/{account_id}/secrets Lists all secrets for an account. Note that the `value` field is not returned in the response for security reasons. Only the `name` and `key_name` fields are included for each secret. # List Supervised Fine-tuning Jobs Source: https://docs.fireworks.ai/api-reference/list-supervised-fine-tuning-jobs get /v1/accounts/{account_id}/supervisedFineTuningJobs # List Users Source: https://docs.fireworks.ai/api-reference/list-users get /v1/accounts/{account_id}/users # Match Deployment Shape Versions Source: https://docs.fireworks.ai/api-reference/match-deployment-shape-versions post /v1/accounts/{account_id}/deploymentShapeVersions:match Returns the deployment shape versions compatible with the provided deployment create request. Use this to discover a validated shape before creating a deployment with `deployment_shape` set - shapeless deployments (raw accelerator type/count) skip validated-configuration checks and are far more likely to fail at creation. Use this endpoint to discover the deployment shape versions compatible with a model before creating a deployment. Pass a [Create Deployment](/api-reference/create-deployment) request in the body — at minimum `createDeploymentRequest.deployment.baseModel` — and the response returns the latest validated shape versions that can serve that model, ready to pass as `deploymentShape`. Match applies the full server-side compatibility logic for you: PEFT base-model resolution (for LoRA addons and live merge, shapes are matched against the PEFT base model), model-type and parameter-count tiers, embedding vs. non-embedding models, the MULTI\_LORA capability gate when `enableAddons` is set, and hiding of FP4 shapes for full-parameter fine-tunes. [List Deployment Shape Versions](/api-reference/list-deployment-shape-versions) only lists versions of a shape you already know and cannot answer "which shapes work with this model?" — use Match for that. The account in the URL must be **your own account** — the account that will own the deployment (you must be a member of it, so `accounts/fireworks` fails with a permission error). The model in the request body, however, can live in any account you can deploy from, including publisher accounts like `accounts/fireworks`; public shapes from the publisher's account flow into the results. ## Example: Match shapes for a model ```bash theme={null} curl -X POST "https://api.fireworks.ai/v1/accounts/YOUR_ACCOUNT_ID/deploymentShapeVersions:match" \ -H "Authorization: Bearer $FIREWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "createDeploymentRequest": { "deployment": { "baseModel": "accounts/fireworks/models/gpt-oss-120b" } } }' ``` To match shapes for a deployment with LoRA addons enabled, include `enableAddons` in the request — only shapes with the MULTI\_LORA capability are returned: ```bash theme={null} curl -X POST "https://api.fireworks.ai/v1/accounts/YOUR_ACCOUNT_ID/deploymentShapeVersions:match" \ -H "Authorization: Bearer $FIREWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "createDeploymentRequest": { "deployment": { "baseModel": "accounts/fireworks/models/gpt-oss-120b", "enableAddons": true } } }' ``` Then pass one of the returned shape versions as `deploymentShape` in the [Create Deployment](/api-reference/create-deployment) request. See [What is a deployment shape?](/faq-new/deployment-infrastructure/what-is-a-deployment-shape) for why you should always create deployments from a shape. # Create Chat Completion Source: https://docs.fireworks.ai/api-reference/post-chatcompletions post /v1/chat/completions Create a completion for the provided prompt and parameters. For RL / agent rollouts, Fireworks inference exposes additional rollout-specific features: [`x-session-affinity` and `x-multi-turn-session-id`](https://docs.fireworks.ai/guides/rollout-inference#session-affinity) for multi-turn trajectories, and [MoE Router Replay (R3)](https://docs.fireworks.ai/guides/rollout-inference#moe-router-replay) for MoE expert tracing during rollouts. # Create Completion Source: https://docs.fireworks.ai/api-reference/post-completions post /v1/completions Create a completion for the provided prompt and parameters. For RL / agent rollouts, Fireworks inference exposes additional rollout-specific features: [`x-session-affinity` and `x-multi-turn-session-id`](https://docs.fireworks.ai/guides/rollout-inference#session-affinity) for multi-turn trajectories, and [MoE Router Replay (R3)](https://docs.fireworks.ai/guides/rollout-inference#moe-router-replay) for MoE expert tracing during rollouts. # Create Response Source: https://docs.fireworks.ai/api-reference/post-responses post /v1/responses Creates a model response, optionally interacting with custom tools via the Model Context Protocol (MCP). This endpoint supports conversational continuation and streaming. Explore our cookbooks for detailed examples: - [Basic MCP Usage](https://github.com/fw-ai/cookbook/blob/main/archived/learn/response-api/fireworks_mcp_examples.ipynb) - [Streaming with MCP](https://github.com/fw-ai/cookbook/blob/main/archived/learn/response-api/fireworks_mcp_with_streaming.ipynb) - [Conversational History with `previous_response_id`](https://github.com/fw-ai/cookbook/blob/main/archived/learn/response-api/fireworks_previous_response_cookbook.ipynb) - [Basic Streaming](https://github.com/fw-ai/cookbook/blob/main/archived/learn/response-api/fireworks_streaming_example.ipynb) - [Controlling Response Storage](https://github.com/fw-ai/cookbook/blob/main/archived/learn/response-api/mcp_server_with_store_false_argument.ipynb) # Prepare Model for different precisions Source: https://docs.fireworks.ai/api-reference/prepare-model post /v1/accounts/{account_id}/models/{model_id}:prepare # Query grouped usage cost subtotals for an account. Source: https://docs.fireworks.ai/api-reference/query-usage-costs post /v1/accounts/{account_id}/usageCosts:query Returns rated dollar subtotals for usage over a time range, grouped by up to two of: HOUR, DAY, MODEL, USER, or API_KEY. Unlike `GET /billingUsage` (metered quantities) and `GET /billing/summary` (line items by billing category), this endpoint returns *rated costs* broken down by caller-supplied dimensions, with pagination and an account-wide `subtotal`. Requires account administrator access for `ACCOUNT` scope; `SELF` scope returns costs for the authenticated principal only. # Rerank documents Source: https://docs.fireworks.ai/api-reference/rerank-documents post /rerank Rerank documents for a query using relevance scoring # Resume Dpo Job Source: https://docs.fireworks.ai/api-reference/resume-dpo-job post /v1/accounts/{account_id}/dpoJobs/{dpo_job_id}:resume # Resume Reinforcement Fine-tuning Job Source: https://docs.fireworks.ai/api-reference/resume-reinforcement-fine-tuning-job post /v1/accounts/{account_id}/reinforcementFineTuningJobs/{reinforcement_fine_tuning_job_id}:resume # Resume Rlor Trainer Job Source: https://docs.fireworks.ai/api-reference/resume-reinforcement-fine-tuning-step post /v1/accounts/{account_id}/rlorTrainerJobs/{rlor_trainer_job_id}:resume # Resume Supervised Fine-tuning Job Source: https://docs.fireworks.ai/api-reference/resume-supervised-fine-tuning-job post /v1/accounts/{account_id}/supervisedFineTuningJobs/{supervised_fine_tuning_job_id}:resume # Scale Deployment to a specific number of replicas or to zero Source: https://docs.fireworks.ai/api-reference/scale-deployment patch /v1/accounts/{account_id}/deployments/{deployment_id}:scale # Undelete Deployment Source: https://docs.fireworks.ai/api-reference/undelete-deployment post /v1/accounts/{account_id}/deployments/{deployment_id}:undelete # Update Dataset Source: https://docs.fireworks.ai/api-reference/update-dataset patch /v1/accounts/{account_id}/datasets/{dataset_id} # Update LoRA Source: https://docs.fireworks.ai/api-reference/update-deployed-model patch /v1/accounts/{account_id}/deployedModels/{deployed_model_id} # Update Deployment Source: https://docs.fireworks.ai/api-reference/update-deployment patch /v1/accounts/{account_id}/deployments/{deployment_id} # Update Evaluator Source: https://docs.fireworks.ai/api-reference/update-evaluator patch /v1/accounts/{account_id}/evaluators/{evaluator_id} Updates evaluator metadata (display_name, description, default_dataset). Changing `requirements` or `entry_point` triggers a rebuild. To upload new source code, set `prepare_code_upload: true` then follow the upload flow. # Update Model Source: https://docs.fireworks.ai/api-reference/update-model patch /v1/accounts/{account_id}/models/{model_id} # Update Quota Source: https://docs.fireworks.ai/api-reference/update-quota patch /v1/accounts/{account_id}/quotas/{quota_id} Updates a quota. # Update Router Source: https://docs.fireworks.ai/api-reference/update-router patch /v1/accounts/{account_id}/routers/{router_id} # Update secret Source: https://docs.fireworks.ai/api-reference/update-secret patch /v1/accounts/{account_id}/secrets/{secret_id} # Update User Source: https://docs.fireworks.ai/api-reference/update-user patch /v1/accounts/{account_id}/users/{user_id} # Upload Dataset Files Source: https://docs.fireworks.ai/api-reference/upload-dataset-files post /v1/accounts/{account_id}/datasets/{dataset_id}:upload Provides a streamlined way to upload a dataset file in a single API request. This path can handle file sizes up to 150Mb. For larger file sizes use [Get Dataset Upload Endpoint](get-dataset-upload-endpoint). # Validate Dataset Upload Source: https://docs.fireworks.ai/api-reference/validate-dataset-upload post /v1/accounts/{account_id}/datasets/{dataset_id}:validateUpload # Validate Evaluator Upload Source: https://docs.fireworks.ai/api-reference/validate-evaluator-upload post /v1/accounts/{account_id}/evaluators/{evaluator_id}:validateUpload Triggers server-side validation of the uploaded source code (**step 5** in the [Create Evaluator](/api-reference/create-evaluator) workflow). The server extracts and processes the archive, then builds the evaluator environment. Poll [Get Evaluator](/api-reference/get-evaluator) to monitor progress. # Validate Model Upload Source: https://docs.fireworks.ai/api-reference/validate-model-upload get /v1/accounts/{account_id}/models/{model_id}:validateUpload # Autoscaling Source: https://docs.fireworks.ai/deployments/autoscaling Configure how your deployment scales based on traffic Control how your deployment scales based on traffic and load. ## Configuration options | Flag | Type | Default | Description | | ------------------------ | --------- | ------------- | ------------------------------------------------------ | | `--min-replica-count` | Integer | 0 | Minimum number of replicas. Set to 0 for scale-to-zero | | `--max-replica-count` | Integer | 1 | Maximum number of replicas | | `--scale-up-window` | Duration | 30s | Wait time before scaling up | | `--scale-down-window` | Duration | 10m | Wait time before scaling down | | `--scale-to-zero-window` | Duration | 1h | Idle time before scaling to zero (min: 5m) | | `--load-targets` | Key-value | `default=0.8` | Scaling thresholds. See options below | **Load target options** (use as `--load-targets =[,=...]`): * `default=` - General load target from 0 to 1 * `tokens_generated_per_second=` - Desired tokens per second per replica * `prompt_tokens_per_second=` - Desired prompt tokens per second per replica * `requests_per_second=` - Desired requests per second per replica * `concurrent_requests=` - Desired concurrent requests per replica When multiple targets are specified, the maximum replica count across all is used. ## Common patterns Scale to zero when idle to minimize costs: ```bash theme={null} firectl deployment create \ --min-replica-count 0 \ --max-replica-count 3 \ --scale-to-zero-window 1h ``` Best for: Development, testing, or intermittent production workloads. Keep replicas running for instant response: ```bash theme={null} firectl deployment create \ --min-replica-count 2 \ --max-replica-count 10 \ --scale-up-window 15s \ --load-targets concurrent_requests=5 ``` Best for: Low-latency requirements, avoiding cold starts, high-traffic applications. Match known traffic patterns: ```bash theme={null} firectl deployment create \ --min-replica-count 3 \ --max-replica-count 5 \ --scale-down-window 30m \ --load-targets tokens_generated_per_second=150 ``` Best for: Steady workloads where you know typical load ranges. ## Scaling from zero behavior When a deployment is scaled to zero and receives a request, the system immediately returns a `503` error with the `DEPLOYMENT_SCALING_UP` error code while initiating the scale-up process: ```json theme={null} { "error": { "message": "Deployment is currently scaled to zero and is scaling up. Please retry your request in a few minutes.", "code": "DEPLOYMENT_SCALING_UP", "type": "error" } } ``` Requests to a scaled-to-zero deployment are **not queued**. Your application must implement retry logic to handle `503` responses while the deployment scales up. ### Handling scale-from-zero responses Implement retry logic with exponential backoff to gracefully handle scale-up delays: ```python theme={null} import time import requests def query_deployment_with_retry(url, payload, max_retries=30, initial_delay=5): """Query a deployment with retry logic for scale-from-zero scenarios.""" delay = initial_delay for attempt in range(max_retries): response = requests.post(url, json=payload, headers=headers) # Only retry if deployment is scaling up if response.status_code == 503: error_code = response.json().get("error", {}).get("code") if error_code == "DEPLOYMENT_SCALING_UP": print(f"Deployment scaling up, retrying in {delay}s...") time.sleep(delay) delay = min(delay * 1.5, 60) # Cap at 60 seconds continue response.raise_for_status() return response.json() raise Exception("Deployment did not scale up in time") ``` ```javascript theme={null} async function queryDeploymentWithRetry(url, payload, maxRetries = 30, initialDelay = 5000) { let delay = initialDelay; for (let attempt = 0; attempt < maxRetries; attempt++) { const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json', ...headers }, body: JSON.stringify(payload) }); // Only retry if deployment is scaling up if (response.status === 503) { const body = await response.json(); if (body.error?.code === 'DEPLOYMENT_SCALING_UP') { console.log(`Deployment scaling up, retrying in ${delay/1000}s...`); await new Promise(resolve => setTimeout(resolve, delay)); delay = Math.min(delay * 1.5, 60000); // Cap at 60 seconds continue; } } if (!response.ok) throw new Error(`HTTP ${response.status}`); return response.json(); } throw new Error('Deployment did not scale up in time'); } ``` ```bash theme={null} # Simple retry loop for scale-from-zero MAX_RETRIES=30 RETRY_DELAY=5 for i in $(seq 1 $MAX_RETRIES); do response=$(curl -s -w "\n%{http_code}" \ https://api.fireworks.ai/inference/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $FIREWORKS_API_KEY" \ -d '{"model": "accounts//deployments/", ...}') http_code=$(echo "$response" | tail -n1) body=$(echo "$response" | head -n -1) # Only retry if deployment is scaling up if [ "$http_code" -eq 503 ]; then error_code=$(echo "$body" | jq -r '.error.code // empty') if [ "$error_code" = "DEPLOYMENT_SCALING_UP" ]; then echo "Deployment scaling up, retrying in ${RETRY_DELAY}s..." sleep $RETRY_DELAY RETRY_DELAY=$((RETRY_DELAY * 2)) continue fi echo "$body" exit 1 fi # Check for success (2xx status codes) if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then echo "$body" exit 0 fi echo "$body" exit 1 done echo "Deployment did not scale up in time" exit 1 ``` Cold start times vary depending on model size—larger models may take longer to download and initialize. If you need instant responses without cold starts, set `--min-replica-count 1` or higher to keep replicas always running. Deployments with min replicas = 0 are auto-deleted after 7 days of no traffic. [Reserved capacity](/deployments/reservations) guarantees availability during scale-up. # Performance benchmarking Source: https://docs.fireworks.ai/deployments/benchmarking Measure and optimize your deployment's performance with load testing Understanding your deployment's performance under various load conditions is essential for production readiness. Fireworks provides tools and best practices for benchmarking throughput, latency, and identifying bottlenecks. ## Fireworks Benchmark Tool Use our open-source benchmarking tool to measure and optimize your deployment's performance: **[Fireworks Benchmark Tool](https://github.com/fw-ai/benchmark)** This tool allows you to: * Test throughput and latency under various load conditions * Simulate production traffic patterns * Identify performance bottlenecks * Compare different deployment configurations ### Installation ```bash theme={null} git clone https://github.com/fw-ai/benchmark.git cd benchmark pip install -r requirements.txt ``` ### Basic usage Run a basic benchmark test: ```bash theme={null} python benchmark.py \ --model "accounts/fireworks/models/llama-v3p1-8b-instruct" \ --deployment "your-deployment-id" \ --num-requests 1000 \ --concurrency 10 ``` ### Key metrics to monitor When benchmarking your deployment, focus on these key metrics: * **Throughput**: Requests per second (RPS) your deployment can handle * **Latency**: Time to first token (TTFT) and end-to-end response time * **Token generation rate**: Tokens per second during generation * **Error rate**: Failed requests under load ## Custom benchmarking You can also develop custom performance testing scripts or integrate with monitoring tools to track metrics over time. Consider: * Using production-like request patterns and payloads * Testing with various concurrency levels * Monitoring resource utilization (GPU, memory, network) * Testing autoscaling behavior under load ## Best practices 1. **Warm up your deployment**: Run a few requests before benchmarking to ensure models are loaded 2. **Test realistic scenarios**: Use request patterns and payloads similar to your production workload 3. **Gradually increase load**: Start with low concurrency and gradually increase to find your deployment's limits 4. **Monitor for errors**: Track error rates and response codes to identify issues under load 5. **Compare configurations**: Test different deployment shapes, quantization levels, and hardware to optimize cost and performance ## Next steps Configure autoscaling to handle variable load Optimize your client code for maximum throughput # Client-side performance optimization Source: https://docs.fireworks.ai/deployments/client-side-performance-optimization Optimize your client code for maximum performance with dedicated deployments When using a dedicated deployment, it is important to optimize the client-side HTTP connection pooling for maximum performance. We recommend using our [Python SDK](/tools-sdks/python-sdk) as it has good defaults for connection pooling and utilizes [httpx](https://www.python-httpx.org/) for optimal performance with Python's `asyncio` library. It also includes retry logic for handling `429` errors that Fireworks returns when the server is overloaded. ## General optimization recommendations Based on our benchmarks, we recommend the following: 1. Use a client library optimized for high concurrency, such as [httpx](https://www.python-httpx.org/) in Python or [http.Agent](https://nodejs.org/api/http.html#class-httpagent) in Node.js. 2. Use the `AsyncFireworks` client for high-concurrency workloads. 3. Increase concurrency until performance stops improving or you observe too many `429` errors. ## Code example: Optimal concurrent requests (Python) Install the [Fireworks Python SDK](/tools-sdks/python-sdk): The SDK is currently in alpha. Use the `--pre` flag when installing to get the latest version. ```bash pip theme={null} pip install --pre fireworks-ai ``` ```bash poetry theme={null} poetry add --pre fireworks-ai ``` ```bash uv theme={null} uv add --pre fireworks-ai ``` Here's how to implement optimal concurrent requests using `asyncio` and the `AsyncFireworks` client: ```python main.py theme={null} import asyncio import time import statistics from fireworks import AsyncFireworks async def make_concurrent_requests( messages: list[str], model: str, max_workers: int = 1000, ): """Make concurrent requests with optimized connection pooling""" client = AsyncFireworks( max_retries=5, ) # Semaphore to limit concurrent requests semaphore = asyncio.Semaphore(max_workers) latencies = [] async def single_request(message: str): """Make a single request with semaphore control""" async with semaphore: start_time = time.perf_counter() response = await client.chat.completions.create( model=model, messages=[{"role": "user", "content": message}], max_tokens=100, ) latency = time.perf_counter() - start_time latencies.append(latency) return response.choices[0].message.content # Create all request tasks tasks = [single_request(message) for message in messages] # Execute all requests concurrently results = await asyncio.gather(*tasks) return results, latencies # Usage example async def main(): messages = ["Hello!"] * 1000 # 1000 requests model = "accounts/fireworks/models/qwen3-0p6b" start_time = time.perf_counter() results, latencies = await make_concurrent_requests( messages=messages, model=model, ) total_time = time.perf_counter() - start_time # Calculate performance metrics num_requests = len(results) requests_per_second = num_requests / total_time # Latency statistics (in milliseconds) latencies_ms = [lat * 1000 for lat in latencies] avg_latency = statistics.mean(latencies_ms) min_latency = min(latencies_ms) max_latency = max(latencies_ms) p50_latency = statistics.median(latencies_ms) p95_latency = statistics.quantiles(latencies_ms, n=20)[18] # 95th percentile p99_latency = statistics.quantiles(latencies_ms, n=100)[98] # 99th percentile print("\n" + "=" * 50) print("Performance Results") print("=" * 50) print(f"Total requests: {num_requests}") print(f"Total time: {total_time:.2f} seconds") print(f"Throughput: {requests_per_second:.2f} requests/second") print("\nLatency Statistics (ms):") print(f" Min: {min_latency:.2f}") print(f" Max: {max_latency:.2f}") print(f" Avg: {avg_latency:.2f}") print(f" P50 (median): {p50_latency:.2f}") print(f" P95: {p95_latency:.2f}") print(f" P99: {p99_latency:.2f}") print("=" * 50) if __name__ == "__main__": asyncio.run(main()) ``` This implementation: * Uses `AsyncFireworks` for non-blocking async requests with optimized connection pooling * Uses `asyncio.Semaphore` to control concurrency to avoid overwhelming the server # Deployment Tags Source: https://docs.fireworks.ai/deployments/deployment-tags Attach customer-defined metadata to dedicated deployments Deployment tags are key-value metadata attached to a dedicated deployment. Use them to record information such as an environment, team, or workload. Tag changes are atomic and do not replace other deployment metadata. ## Manage tags with firectl Upgrade firectl before using the tag commands: ```bash theme={null} firectl upgrade ``` These commands require firectl `1.8.3` or later. Set one tag: ```bash theme={null} firectl deployment tag set --key environment --value prod ``` Set multiple tags atomically: ```bash theme={null} firectl deployment tag set \ --tag environment=prod \ --tag team=search ``` Use either `--key` with `--value` or one or more `--tag` flags. Do not combine the two forms in one command. List tags: ```bash theme={null} firectl deployment tag list ``` Remove one or more tags atomically: ```bash theme={null} firectl deployment tag unset \ --key environment \ --key team ``` `set` overwrites existing values for the specified keys. `unset` ignores keys that do not exist. Each command changes all supplied keys in one request or makes no changes. firectl uses logical tag keys and manages the API's `custom/` prefix for you. Do not add that prefix to firectl keys. For example, `--key environment` writes the API key `custom/environment`; `--key custom/environment` writes `custom/custom/environment`. ## Manage tags with the REST API The REST API exposes canonical tag keys. Customer-managed keys must begin with `custom/`. Set one or more tags: ```bash theme={null} curl --request POST \ --url "https://api.fireworks.ai/v1/accounts/${ACCOUNT_ID}/deployments/${DEPLOYMENT_ID}:setTags" \ --header "Authorization: Bearer ${FIREWORKS_API_KEY}" \ --header "Content-Type: application/json" \ --data '{ "tags": { "custom/environment": "prod", "custom/team": "search" } }' ``` Remove one or more tags: ```bash theme={null} curl --request POST \ --url "https://api.fireworks.ai/v1/accounts/${ACCOUNT_ID}/deployments/${DEPLOYMENT_ID}:deleteTags" \ --header "Authorization: Bearer ${FIREWORKS_API_KEY}" \ --header "Content-Type: application/json" \ --data '{ "keys": [ "custom/environment", "custom/team" ] }' ``` The set and delete endpoints modify only the supplied keys. Other tags and Fireworks-managed annotations remain unchanged. ### Add tags when creating a deployment Direct API clients can include canonical keys in the deployment's `annotations` map: ```json theme={null} { "annotations": { "custom/environment": "prod", "custom/team": "search" } } ``` Bare annotation keys such as `environment`, `team`, or `project` are not customer-writable. Deployment creation requests containing them return `403 PERMISSION_DENIED`. Prefix customer-managed keys with `custom/`, or create the deployment and use `firectl deployment tag set`. To change tags after creation, use `:setTags` and `:deleteTags`. Regular account callers cannot replace the complete `annotations` map through `UpdateDeployment`. ## Read tags For regular account users, `GetDeployment` and `ListDeployments` return only customer-owned deployment tags, with the canonical `custom/` prefix: ```json theme={null} { "annotations": { "custom/environment": "prod", "custom/team": "search" } } ``` firectl's `deployment tag list` command shows deployment tags and removes one leading `custom/` prefix from each displayed key. Regular account responses no longer include legacy bare annotation keys. A client that previously read `annotations["environment"]`, for example, now receives no value and no error for that key. Set the canonical `custom/environment` tag and read `annotations["custom/environment"]` instead. ## Validation * A deployment can have at most 64 customer tags. * firectl logical keys can contain 1–121 ASCII characters. API keys can contain at most 128 characters, including `custom/`. * The `custom/` API prefix is case-sensitive. * The firectl logical key—and the portion of a REST key after `custom/`—may contain ASCII letters, digits, `-`, `_`, `.`, and `/`. It must start and end with an ASCII letter or digit. * Values must be non-empty valid UTF-8 with at most 128 Unicode code points. * Values cannot have leading or trailing whitespace or contain control characters. ## Deployment list filtering Tag filtering in `ListDeployments` and `firectl deployment list` is not currently supported. # Exporting Metrics Source: https://docs.fireworks.ai/deployments/exporting-metrics Export metrics from your dedicated deployments to your observability stack ## Overview Fireworks provides a metrics endpoint in Prometheus format, enabling integration with popular observability tools like Prometheus, OpenTelemetry (OTel) Collector, Datadog Agent, and Vector. This page covers real-time performance metrics (latency, throughput, etc.) for on-demand deployments. For billing and usage data across all Fireworks services, see [Exporting Billing Metrics](/accounts/exporting-billing-metrics). ## Setting Up Metrics Collection ### Endpoint The metrics endpoint is as follows. This URL and authorization header can be directly used by services like Grafana Cloud to ingest Fireworks metrics. ``` https://api.fireworks.ai/v1/accounts//metrics ``` ### Authentication Use the Authorization header with your Fireworks API key: ```json theme={null} { "Authorization": "Bearer YOUR_API_KEY" } ``` ### Scrape Interval We recommend using a 1-minute scrape interval as metrics are updated every 30s. ### Rate Limits To ensure service stability and fair usage: * Maximum of 6 requests per minute per account * Exceeding this limit results in HTTP 429 (Too Many Requests) responses * Use a 1-minute scrape interval to stay within limits ## Integration Options Fireworks metrics can be integrated with various observability platforms through multiple approaches: ### OpenTelemetry Collector Integration The Fireworks metrics endpoint can be integrated with OpenTelemetry Collector by configuring a Prometheus receiver that scrapes the endpoint. This allows Fireworks metrics to be pushed to a variety of popular exporters—see the [OpenTelemetry registry](https://opentelemetry.io/ecosystem/registry/) for a full list. ### Direct Prometheus Integration To integrate directly with Prometheus, specify the Fireworks metrics endpoint in your scrape config: ```yaml theme={null} global: scrape_interval: 60s scrape_configs: - job_name: 'fireworks' metrics_path: 'v1/accounts//metrics' authorization: type: "Bearer" credentials: "YOUR_API_KEY" static_configs: - targets: ['api.fireworks.ai'] scheme: https ``` For more details on Prometheus configuration, refer to the [Prometheus documentation](https://prometheus.io/docs/prometheus/latest/configuration/configuration/). ### Supported Platforms Fireworks metrics can be exported to various observability platforms including: * Prometheus * Datadog * Grafana * New Relic ## Available Metrics ### Common Labels All metrics include the following common labels: * `base_model`: The base model identifier (e.g., "accounts/fireworks/models/deepseek-v3") * `deployment`: Full deployment path (e.g., "accounts/account-name/deployments/deployment-id") * `deployment_account`: The account name * `deployment_id`: The deployment identifier ### Rate Metrics (per second) These metrics show activity rates calculated using 1-minute windows: #### Request Rate * `request_counter_total:sum_by_deployment`: Request rate per deployment #### Error Rate * `requests_error_total:sum_by_deployment`: Error rate per deployment, broken down by HTTP status code (includes additional `http_code` label) #### Token Processing Rates * `tokens_cached_prompt_total:sum_by_deployment`: Rate of cached prompt tokens per deployment * `tokens_prompt_total:sum_by_deployment`: Rate of total prompt tokens processed per deployment ### Latency Histogram Metrics These metrics provide latency distribution data with histogram buckets, calculated using 1-minute windows: #### Generation Latency * `latency_generation_per_token_ms_bucket:sum_by_deployment`: Per-token generation time distribution * `latency_generation_queue_ms_bucket:sum_by_deployment`: Time spent waiting in generation queue #### Request Latency * `latency_overall_ms_bucket:sum_by_deployment`: End-to-end request latency distribution * `latency_to_first_token_ms_bucket:sum_by_deployment`: Time to first token distribution #### Prefill Latency * `latency_prefill_ms_bucket:sum_by_deployment`: Prefill processing time distribution * `latency_prefill_queue_ms_bucket:sum_by_deployment`: Time spent waiting in prefill queue ### Token Distribution Metrics These histogram metrics show token count distributions per request, calculated using 1-minute windows: * `tokens_generated_per_request_bucket:sum_by_deployment`: Distribution of generated tokens per request * `tokens_prompt_per_request_bucket:sum_by_deployment`: Distribution of prompt tokens per request ### Resource Utilization Metrics These gauge metrics show average resource usage: * `generator_kv_blocks_fraction:avg_by_deployment`: Average fraction of KV cache blocks in use * `generator_kv_slots_fraction:avg_by_deployment`: Average fraction of KV cache slots in use * `generator_model_forward_time:avg_by_deployment`: Average time spent in model forward pass * `requests_coordinator_concurrent_count:avg_by_deployment`: Average number of concurrent requests * `prefiller_prompt_cache_ttl:avg_by_deployment`: Average prompt cache time-to-live # Regions Source: https://docs.fireworks.ai/deployments/regions Fireworks runs a global fleet of hardware on which you can deploy your models. Fireworks runs a global fleet so you can deploy models close to users, meet data-residency needs, and scale across clouds. This page covers **multi-region** (default behavior and quota groupings), **single-region** availability and hardware, how to **use and change** regions, and **quotas**. ## Multi-region (recommended) By default, deployments are multi-region: Fireworks can move and spread them across regions as needed. Multi-regions (**GLOBAL**, **US**, **EUROPE**, **APAC**) are high-level groupings of single regions. Your deployment may run in any single region(s) within that multi-region. Utilizing multiple clouds and locations maximizes the odds that there's capacity to scale. Multi-region deployments enable resilience to localized outages, maintaining application availability as workloads scale across regions. ### Supported multi-regions Supported multi-regions: `GLOBAL`, `US`, `EUROPE`, `APAC`. ## Single region availability Single regions are concrete locations (e.g. `US_IOWA_1`, `EU_FRANKFURT_1`) where your deployment can run. We have the single regions listed below available; we recommend multi-region for most users because of its advantages (elastic scaling, higher reliability). If you have a specific need for a single region, contact [Fireworks](mailto:sales@fireworks.ai) to request it. The table below shows which **Fireworks-managed** single regions are available and what hardware is offered in each. | **Region** | **Accelerator Type(s)** | | ---------------------- | --------------------------------------------------------------------------------- | | `AP_MALAYSIA_2` | `NVIDIA_B300_288GB` | | `AP_NEWSOUTHWALES_1` | `NVIDIA_B200_180GB` | | `AP_TOKYO_1` | `NVIDIA_H100_80GB` | | `AP_TOKYO_2` | `NVIDIA_H200_141GB` | | `EU_FRANKFURT_1` | `NVIDIA_H100_80GB` | | `EU_ICELAND_1` | `NVIDIA_H200_141GB` | | `EU_ICELAND_2` | `NVIDIA_B200_180GB`, `NVIDIA_H200_141GB` | | `NA_BRITISHCOLUMBIA_1` | `NVIDIA_B300_288GB` | | `NA_BRITISHCOLUMBIA_2` | `AMD_MI350X_288GB` | | `NA_BRITISHCOLUMBIA_3` | `NVIDIA_B300_288GB` | | `US_ARIZONA_1` | `NVIDIA_H100_80GB` | | `US_ARIZONA_3` | `AMD_MI325X_256GB` | | `US_CALIFORNIA_1` | `NVIDIA_H200_141GB` | | `US_CALIFORNIA_2` | `AMD_MI325X_256GB` | | `US_GEORGIA_2` | `NVIDIA_B200_180GB` | | `US_GEORGIA_3` | `NVIDIA_H200_141GB` | | `US_ILLINOIS_1` | `NVIDIA_H100_80GB` | | `US_ILLINOIS_2` | `NVIDIA_A100_80GB` | | `US_IOWA_1` | `NVIDIA_H100_80GB` | | `US_MINNESOTA_1` | `NVIDIA_B300_288GB` | | `US_NEWYORK_1` | `AMD_MI325X_256GB` | | `US_OHIO_1` | `NVIDIA_B200_180GB` | | `US_VIRGINIA_1` | `NVIDIA_H100_80GB`, `NVIDIA_H200_141GB`, `NVIDIA_B200_180GB`, `NVIDIA_B300_288GB` | | `US_WASHINGTON_3` | `NVIDIA_B200_180GB` | | `US_WASHINGTON_4` | `NVIDIA_B200_180GB` | | `US_WASHINGTON_5` | `NVIDIA_B200_180GB` | ## Using a region When creating a deployment, you can pass the `--region` flag to pin it to a single region: ``` firectl deployment create accounts/fireworks/models/llama-v3p1-8b-instruct \ --region GLOBAL ``` ## Changing regions Updating the single region for a deployment in-place is not supported. To move a deployment to a different single region, create a new deployment in the desired region, then delete the old deployment. ## Quotas New accounts receive GPU quota for the **GLOBAL** multi-region only. Quota is scoped per placement (multi-region or single region). The **US**, **EUROPE**, and **APAC** multi-regions and all single regions start at zero quota and must be granted by Fireworks. If you deploy with a `--region` you have no quota for, creation is rejected even though that region is generally available. To view your current quotas, run: ``` firectl quota list ``` To use single regions that are not generally available (see the table above), or to request quota for additional placements (multi-region or single region), contact [sales@fireworks.ai](mailto:sales@fireworks.ai). To discuss Bring Your Own Cluster (BYOC) deployments, see the [BYOC overview](/ecosystem/integrations/byoc/overview). # Reserved capacity Source: https://docs.fireworks.ai/deployments/reservations Enterprise accounts can purchase reserved capacity, typically with 1 year commitments. Reserved capacity has the following advantages over ordinary [on-demand deployments](/guides/ondemand-deployments): * Guaranteed capacity * Higher quotas * Lower GPU-hour prices * Pre-GA access to newer regions * Pre-GA access to newest hardware ## Usage and billing Consuming a reservation is done by creating a deployment that meets the reservation parameters. For example, suppose you have a reservation for 12 H100 GPUs and create two deployments, each using 8 H100 GPUs. While both deployments are running, 12 of the H100s will count towards using your reservation, while the excess 4 H100s will be metered and billed at the on-demand rate. Follow [deploying models on-demand](/guides/ondemand-deployments) to create a deployment. When a reservation approaches its end time, ensure that you either renew your reservation or turn down a corresponding number of deployments, otherwise you may be billed at for your usage at on-demand rates. Reservations are invoiced separately from your on-demand usage, at a frequency determined by your reservation contract (e.g. monthly, quarterly, or yearly). Reserved capacity will always be billed until the reservation ends, regardless of whether the reservation is actively used. ## Purchasing or renewing a reservation To purchase a reservation or increase the size or duration of an existing reservation, contact your Fireworks account manager. If you are a new, prospective customer, please reach out to our [sales team](https://fireworks.ai/company/contact-us). ## Viewing your reservations To view your existing reservations, run: ``` firectl reservation list ``` # Routers Source: https://docs.fireworks.ai/deployments/routers Distribute traffic across multiple deployments for A/B testing, traffic migration, and load distribution. A **Router** is a resource that controls how inference traffic is routed to one or more deployments. Instead of sending all requests to a single deployment, a router lets you split traffic across multiple deployments — useful for A/B testing model variants, gradually migrating traffic to a new deployment, or distributing load. Traffic is split proportionally based on the number of replicas in each deployment. For example, if a router covers two deployments — one with 3 replicas and another with 2 — the first receives 60% of traffic and the second receives 40%. Routers only work with multi-region deployments. ## When to use a router ### Stable alias for deployment replacement If you plan to replace a deployment later (e.g., changing to a new model later), give your application the **router name** instead of the deployment name. You can then swap the underlying deployment without your application changing anything. ``` Your app calls: accounts//routers/my-router └── Initially routes to: accounts//deployments/v1 └── Later updated to: accounts//deployments/v2 ``` ### A/B testing between deployments Place multiple deployments under a single router. Traffic is automatically split by replica count, so you can control the ratio by adjusting replicas on each deployment. ```bash theme={null} firectl router create \ --router-id=ab-test \ --deployments=model-a,model-b ``` ### Gradual traffic migration Shift traffic from an old deployment to a new one with zero downtime by scaling replicas up on the new deployment and down on the old. See the [worked example](#example-traffic-migration) below. ## How traffic routing works Traffic is distributed based on **replica count**. Each replica across all deployments in the router receives an equal share of traffic. | Deployment | Replicas | Traffic share | | -------------- | -------- | ------------- | | `deployment-a` | 3 | 60% | | `deployment-b` | 2 | 40% | | **Total** | **5** | **100%** | To shift traffic, scale the replica counts on the underlying deployments. The router automatically adjusts the distribution. ### Sending traffic to a router Use the router's name in the `model` field of your API request, just like you would use a deployment name: ```bash theme={null} curl -s -X POST https://api.fireworks.ai/inference/v1/chat/completions \ -H "Authorization: Bearer $FIREWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "accounts//routers/", "messages": [{"role": "user", "content": "Hello"}] }' ``` ### Routing strategy Traffic is routed using **weighted replica** selection: each request is randomly assigned to a deployment, weighted by its replica count. A deployment with more replicas receives proportionally more traffic. ## Managing routers ### Creating a router A router requires at least one deployment. ```bash theme={null} firectl router create \ --deployments=, ``` Optional flags: | Flag | Description | | ---------------- | -------------------------------------------------------------- | | `--router-id` | Set a specific router ID. If omitted, a random ID is generated | | `--display-name` | Human-readable name for the router | | `--model` | The model to route traffic to | | `--strategy` | Routing strategy. Default: `weighted-random` | | `--public` | Make the router accessible to other accounts | ### Listing routers ```bash theme={null} firectl router list ``` ### Getting router details ```bash theme={null} firectl router get ``` You can also use the full resource name: ```bash theme={null} firectl router get accounts//routers/ ``` ### Updating a router Update the deployments, strategy, or other properties of an existing router: ```bash theme={null} firectl router update \ --deployments=,, ``` ### Deleting a router ```bash theme={null} firectl router delete ``` Deleting a router takes effect immediately. Any traffic sent to the router's alias will fail. Make sure all clients have switched to a different route before deleting. ## Example: traffic migration This example walks through migrating traffic from an existing deployment to a new one with zero downtime. **Step 1** — Create a router for your existing deployment and point your application at the router alias: ```bash theme={null} firectl router create \ --router-id=my-router \ --deployments=current-deployment ``` Your application sends traffic to `accounts//routers/my-router`. All traffic goes to `current-deployment`. **Step 2** — Create the new deployment and add it to the router: ```bash theme={null} firectl deployment create accounts//models/ \ --deployment-id=new-deployment ``` ```bash theme={null} firectl router update my-router \ --deployments=current-deployment,new-deployment ``` A new deployment starts with 1 replica by default, so if `current-deployment` has 4 replicas, the split is immediately 80%/20%. **Step 3** — Shift more traffic by increasing replicas on the new deployment and decreasing the old: ```bash theme={null} firectl deployment update new-deployment \ --min-replica-count=4 \ --max-replica-count=4 firectl deployment update current-deployment \ --min-replica-count=1 \ --max-replica-count=1 ``` Traffic split is now 20% old / 80% new. **Step 4** — Complete the migration by scaling the old deployment to zero: ```bash theme={null} firectl deployment update current-deployment \ --min-replica-count=0 \ --max-replica-count=0 ``` All traffic now flows to `new-deployment`. Clean up by removing the old deployment from the router: ```bash theme={null} firectl router update my-router --deployments=new-deployment ``` Monitor your new deployment's latency and error rates at each step before shifting more traffic. This lets you catch issues early and roll back by increasing replicas on the old deployment. # Speculative Decoding Source: https://docs.fireworks.ai/deployments/speculative-decoding Speed up generation with draft models and n-gram speculation Speculative decoding reduces generation latency by proposing multiple tokens and letting the target model verify them in parallel. The target model still verifies every accepted token; the drafter does not replace the target model. The benefit depends on both the cost of producing draft tokens and how often the target model accepts them. A poorly matched drafter can make generation slower, so benchmark with representative traffic before overriding Fireworks defaults. The deployment flags on this page apply to [dedicated deployments](/guides/ondemand-deployments). Fireworks manages the serving configuration for Serverless models. ## Start with the default **For most supported models, a default drafter and draft-token count are already configured.** A new deployment inherits those settings, so you usually do not need to pass any speculative-decoding flags. Create the deployment normally, then benchmark it before changing the drafter: ```bash theme={null} firectl deployment create accounts/fireworks/models/ --wait ``` If the base model does not define a default drafter, the deployment runs without model-based speculative decoding. To explicitly disable an inherited default when creating a comparison deployment, use: ```bash theme={null} firectl deployment create accounts/fireworks/models/ \ --disable-speculative-decoding \ --wait ``` ## Choose a method | Method | Best starting point | Configuration | | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | Default model-based speculation | General chat, reasoning, and coding traffic | No flags; inherit the model's default | | Custom draft model | A validated drafter for your model or traffic distribution | `--draft-model` and `--draft-token-count` | | N-gram speculation | Repetitive output, code editing, and structured generation where output often repeats the prompt or prior context | `--ngram-speculation-length` and `--draft-token-count` | | [Predicted Outputs](/guides/predicted-outputs) | The caller already knows most of the expected response, such as regenerating a file with a small edit | Request-level `prediction` or `speculation` input | Predicted Outputs can be used in addition to a deployment's model-based speculative decoding. ## Configuration options | Flag | Description | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--draft-model` | Resource name of a Fireworks or custom draft model. If omitted, the deployment inherits the base model's default drafter. | | `--draft-token-count` | Number of candidate tokens proposed per step. It is required with an explicitly selected draft model or N-gram speculation. Start with `4`, then benchmark nearby values. | | `--ngram-speculation-length` | Length of the previous input sequence used for N-gram matching. This does not require a separate draft model. | | `--disable-speculative-decoding` | Disables inherited speculative-decoding settings when creating a deployment. | `--draft-model` and `--ngram-speculation-length` are alternative deployment strategies and cannot be used together. ## Custom draft models For self-service configuration, use a small base model that is compatible with the target model. In practice, this means using the same model family and tokenizer. A model that is merely smaller is not necessarily a useful drafter; its acceptance rate and execution cost both matter. ### Fallback draft models If the target model has no default drafter, the following small base models are reasonable starting points for an experiment. A purpose-built drafter generally performs better. | Draft model | Use with | | -------------------------------------------------- | --------------------- | | `accounts/fireworks/models/llama-v3p2-1b-instruct` | All Llama models > 3B | | `accounts/fireworks/models/qwen2p5-0p5b-instruct` | All Qwen models > 3B | Fireworks also supports compatible EAGLE, DFlash, DSpark, and Medusa draft addons. These formats are architecture-specific and require a checkpoint and configuration prepared for the exact target model; they are not drop-in replacements for a small base-model drafter. [Contact Fireworks](https://fireworks.ai/company/contact-us) to validate an existing checkpoint or discuss a drafter adapted to your traffic. ## Examples Create a deployment with an explicit small base-model drafter: ```bash theme={null} firectl deployment create accounts/fireworks/models/llama-v3p3-70b-instruct \ --draft-model="accounts/fireworks/models/llama-v3p2-1b-instruct" \ --draft-token-count=4 ``` Use N-gram speculation without a separate draft model: ```bash theme={null} firectl deployment create accounts/fireworks/models/llama-v3p3-70b-instruct \ --ngram-speculation-length=3 \ --draft-token-count=4 ``` You can change the explicit drafter and draft-token count on an existing deployment: ```bash theme={null} firectl deployment update \ --draft-model="accounts//models/" \ --draft-token-count=4 ``` ## Benchmark and tune Compare at least three configurations on the same target model and deployment shape: 1. The inherited Fireworks default. 2. Your candidate drafter or N-gram settings. 3. A deployment created with `--disable-speculative-decoding`. Use production-like prompts, output lengths, sampling parameters, and concurrency. Measure time to first token, inter-token latency, p50/p95 request latency, and maximum sustainable throughput. A high acceptance rate alone does not guarantee a speedup because the drafter also consumes compute. To inspect per-request metrics, set `perf_metrics_in_response` to `true` in the completion request. For dedicated deployments, the final response or final streaming chunk includes: * `speculation-generated-tokens`: number of tokens generated through speculation * `speculation-acceptance`: acceptance rate by proposed-token position Acceptance normally falls at later positions. Increase `--draft-token-count` only while the additional accepted tokens outweigh the extra drafting and verification work. Re-run the benchmark when the traffic mix, prompt format, model, quantization, or deployment shape changes. # Claude Code Source: https://docs.fireworks.ai/ecosystem/fireconnect/claude-code Use Fireworks AI models in Claude Code with the FireConnect CLI [FireConnect](https://github.com/fw-ai/fireconnect) routes [Claude Code](https://claude.ai/code) through Fireworks AI models. See the [FireConnect overview](/ecosystem/fireconnect/overview) for install and CLI basics. **Change models:** `fireconnect claude on --model ` (or `--opus` / `--sonnet` / …). See [Models](/ecosystem/fireconnect/models). ## Prerequisites * [Claude Code](https://claude.ai/code) installed * A [Fireworks API key](https://app.fireworks.ai/settings/users/api-keys) (`fw_...`) or a [Fire Pass](/firepass) key (`fpk_...`) * FireConnect CLI v0.9.5+ (see [Install](/ecosystem/fireconnect/overview#install)) **Azure routing not implemented yet for Claude Code.** `fireconnect claude on` always configures direct Fireworks, even when global config has `--provider azure` or you pass `--azure`. See [Microsoft Foundry in FireConnect](/ecosystem/fireconnect/microsoft-foundry#supported-harnesses). ## Enable Fireworks routing ```bash theme={null} fireconnect login fireconnect claude on ``` Or pass the key once: ```bash theme={null} fireconnect claude on --api-key fw_... ``` Restart Claude Code after enabling, then test with a simple prompt. After `fireconnect claude on`, start a new Claude Code session or run `/model` to pick up model changes. To use a new model in the same session, start a new session or `/exit` and resume with `claude --resume `. ## Change models ```bash theme={null} fireconnect model list --search glm fireconnect claude on --model firerouter # main only fireconnect claude on --interactive # model mapping wizard fireconnect claude on --opus glm-fast-latest --sonnet auto-instant fireconnect claude status ``` Model flags directly override the named slot. Set every slot you want to control explicitly. Use `native` as a slot value to leave a slot unpinned so Claude Code chooses its default for that role. Re-running `on` without flags preserves your current mapping when FireConnect is already active (including `/model` changes made inside Claude Code). Reopen the wizard anytime: ```bash theme={null} fireconnect claude on --interactive ``` Use `--non-interactive` to skip the wizard and apply saved preferences or the current profile. `--interactive` cannot be combined with model flags like `--model` or `--opus`. Use the wizard to choose aliases, or use explicit model flags for a reproducible configuration. ### Smart router mixes Pin Fireworks' open-model mixes on any slot: ```bash theme={null} fireconnect claude on --sonnet auto # default open-model mix fireconnect claude on --sonnet auto-instant # latency-first mix ``` `auto` appears on every slot in the picker; `auto-instant` is available on Sonnet. These route among Fireworks open models only — unlike FireRouter, they do not pass through to Claude Opus 5. ## What gets written FireConnect writes the selected mapping to `~/.claude/settings.json`. Claude Code authenticates via the `X-Fireworks-Api-Key` custom header (not `apiKeyHelper`). The Fireworks key is written to the file with mode `0600`. **Why the custom header?** The gateway authenticates via `X-Fireworks-Api-Key`, which wins over any stray `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` — so a leftover Anthropic key can't silently break routing. **Model IDs and `[1m]`.** Short slugs are accepted everywhere. FireConnect adds a `[1m]` suffix on 1M-context models for every slot — subagent included — so Claude Code sizes the context window correctly. The gateway still sees the bare model ID; Claude Code strips the tag before sending. `on` also: * Denies Anthropic **server-side** `WebSearch` / `WebFetch` tools the gateway can't run, and installs the Fireworks [WebSearch MCP](/ecosystem/fireconnect/websearch-mcp) when your account is eligible * Installs a **status line** showing routed models and estimated session cost (see [Status line](#status-line)). Your own `statusLine` is never replaced * Sends privacy-safe attribution headers (`X-Title`, `HTTP-Referer`) where supported FireConnect saves a backup of your previous provider settings to `~/.fireconnect/claude/`. When that backup is available, `fireconnect claude off` restores it byte-for-byte; otherwise it removes FireConnect-managed settings. Legacy pins like `deepseek-v4-flash` migrate to `deepseek-flash-latest` on the next `on`. ## Status line When you don't already have a custom `statusLine`, `on` installs one that shows which models actually served the session and their estimated cost: ```text theme={null} ━━━━━━━━━━━━ ━ ━ · $70.39 ━ Claude Opus 5 $62.91 98% cache · ━ GLM 5.2 $7.35 96% cache · ━ DeepSeek V4 Flash $0.13 87% cache ``` The first line is a **multi-color bar** sized by each backend model's share of session spend, followed by the session total. The second line names each model with its cost and cache hit rate. FireRouter sessions show the whole mix at a glance — not just the latest model. The cost uses Fireworks serverless rates for Fireworks models and Anthropic list rates for Anthropic models. Calls without a matched rate remain in usage totals but are not assigned a dollar cost. `off` removes the status line. **If you already have a `statusLine`, FireConnect leaves it alone** — delete yours and re-run `fireconnect claude` to opt in. ## Web search MCP When you run `fireconnect claude on`, FireConnect can install the Fireworks [WebSearch MCP](/ecosystem/fireconnect/websearch-mcp) for eligible accounts. FireConnect WebSearch integration is **Claude Code only today**; other harnesses can add the HTTP MCP manually. When installation succeeds, `fireconnect claude on` prints `Web search → fireworks-websearch (installed)`. Restart Claude Code, then run `/mcp` and connect to `fireworks-websearch`. `fireconnect claude off` removes the managed MCP entry and restores your previous `~/.claude/settings.json`. ## Browsing and picking models ```bash theme={null} fireconnect model list --search glm fireconnect model list --refresh fireconnect claude on --sonnet kimi-latest ``` `fireconnect model list` shows serverless endpoints and pricing (cached for one hour; works offline). `fireconnect claude status` shows your current mapping, every slot including defaults, and available rates per slot. Fire Pass keys only list Fire Pass routers. FireConnect rejects `--model firerouter` with Fire Pass (`fpk_...`) on every harness; use an `fw_...` key. ## FireRouter Route requests through [FireRouter](/ecosystem/firerouter/overview). The default `firerouter` model ID is more likely to use **GLM 5.3** for lower-complexity work and **Claude Opus 5** for harder work. See [current routing pair](/ecosystem/firerouter/overview#current-routing-pair). ### Choose where FireRouter is used Use `--model` for Main or a slot-specific flag for an alias: ```bash theme={null} fireconnect claude on --model firerouter fireconnect claude on --opus firerouter ``` On first setup, FireConnect assigns models to slots you do not specify. Use `--interactive` to choose alias slots. To control the complete mapping including Main, set every slot explicitly. Use `native` to leave a slot unpinned. ```bash theme={null} fireconnect claude on --interactive # FireRouter on Main; leave every alias unpinned fireconnect claude on --model firerouter \ --opus native --sonnet native --haiku native \ --fable native --subagent native ``` ### Custom routing pairs ```bash theme={null} fireconnect claude on --sonnet firerouter/claude-opus-5/glm-5p3-fast # custom pair ``` Use a [slash-delimited FireRouter slug](/ecosystem/firerouter/overview#choose-different-models) on any slot (`firerouter//`, …) to change which models FireRouter can pick. Anthropic credentials are needed only when the slug includes a Claude model (including bare `firerouter`). A Fireworks-only slug such as `firerouter/kimi-k3/glm-5p2-fast` needs only the Fireworks API key. ### Anthropic auth for pass-through The default bare `firerouter` route's Claude Opus 5 leg needs Anthropic credentials. With FireConnect you usually **do not** pass a new key: * **Claude subscription or browser OAuth** — Claude Code already attaches Anthropic auth on each request; Fireworks forwards it for pass-through. * **Anthropic API key** — if Claude Code is configured with `ANTHROPIC_API_KEY`, that works too. * **Explicit BYOK** — pass `--anthropic-api-key sk-ant-...` on `on`, or store once with `fireconnect configure --anthropic-api-key sk-ant-...`. * **Workspace BYOK** — when enabled on your Fireworks account, no local Anthropic key is required. ### See which models served the session After assistant messages run, check: 1. **Status line** (installed by `on` unless you already have a custom `statusLine`) — lists backend models that served the session (for example `Claude Opus 5` or `GLM 5.3`) and estimated session cost. Before a billed response, it may show `FireRouter` rather than a resolved backend. See [Status line](#status-line). 2. **`fireconnect claude status`** — shows the configured slot mapping and which slots use FireRouter. It does not show per-request routing decisions. ### Tune cost vs quality Set routing preference with `--routing-preference` on `on` (`1`–`5` or a named level): ```bash theme={null} fireconnect claude on --model firerouter --routing-preference 4 # max-intelligence (1) · more-intelligence (2) · balanced (3) · more-savings (4) · max-savings (5) ``` See [Routing preferences](/ecosystem/firerouter/routing-preferences). Omit the flag to use FireRouter's default. Re-running `on` without `--routing-preference` clears a preference that FireConnect previously wrote. ## Usage and live meter Claude Code's `/model` picker shows Anthropic list prices. Use `fireconnect claude usage` to estimate session cost from Fireworks serverless rates and Anthropic list rates. On a TTY, `usage` opens a session picker (last 3 days by default), then a live cost meter. Tab: agents pane. Esc: session list. q: quit. ```bash theme={null} fireconnect claude usage # picker → live meter fireconnect claude usage --days 7 # picker lookback only (1–365) fireconnect claude usage --session # start on one session fireconnect claude usage --last-n 5 # snapshot, no picker (--days ignored) fireconnect claude usage --plain # plain text fireconnect claude usage --json # JSON fireconnect claude usage --verbose # request-level rows and rate details ``` For a tmux split (Claude Code left, meter right): ```bash theme={null} fireconnect claude live fireconnect claude live --session ``` Requires `tmux`. Neither command changes harness settings. Scripting: ```bash theme={null} fireconnect claude status --json fireconnect claude usage --last-n 5 --json ``` ## Troubleshooting ### Text-only models and images Claude Code cannot mark a model as non-vision. Pasting an image on a **text-only** slot (for example `glm-fast-latest` or `deepseek-flash-latest`) can break the session. **Recover with `/rewind`**, then avoid images on that slot or map it to a vision model: ```bash theme={null} fireconnect claude on --sonnet kimi-fast-latest ``` `fireconnect claude on` warns when your mapping includes text-only models. `fireconnect claude status` labels each slot `vision` or `text-only`. ### Pricing estimates Claude Code's session cost uses **Anthropic list prices**, while Fireworks bills at **serverless rates**. Use `fireconnect claude status`, `fireconnect model list`, and the [billing dashboard](https://app.fireworks.ai/account/billing) for actual spend. ## CLI reference ```bash theme={null} fireconnect claude on # Route Claude Code through Fireworks fireconnect claude off # Restore your previous provider fireconnect claude status # Provider, auth, and model mapping fireconnect claude usage # Session cost meter fireconnect claude live # tmux split with live meter fireconnect claude demo # Race two models on a prompt fireconnect claude help # Harness-specific help ``` Run `fireconnect claude help` for all options. ### Turn off Fireworks routing ```bash theme={null} fireconnect claude off ``` This restores your previous `~/.claude/settings.json` from the backup saved in `~/.fireconnect/claude/`. ## Uninstall To remove FireConnect from your machine entirely (all harnesses): ```bash theme={null} fireconnect uninstall ``` ## Source FireConnect is open source: [github.com/fw-ai/fireconnect](https://github.com/fw-ai/fireconnect) # CLI reference Source: https://docs.fireworks.ai/ecosystem/fireconnect/cli-reference FireConnect global commands, providers, authentication, and migration FireConnect uses **harness-first** syntax: `fireconnect `. Bare harness names run `on` (for example, `fireconnect claude` is the same as `fireconnect claude on`). To pick or switch models, see **[Models](/ecosystem/fireconnect/models)**. This page is the command and auth reference. ## Global commands ```bash theme={null} fireconnect login # Sign in: browser (creates a key) or paste a key you have fireconnect logout # Clear the stored key (keychain entry + config ref) fireconnect status # Sign-in state, machine environment, key storage, harness state fireconnect configure # Set the provider (Azure/Foundry) and Anthropic key for FireRouter fireconnect model list # Browse the global Fireworks coding model catalog fireconnect claude demo # Race two models in live Claude Code sessions fireconnect upgrade # Update FireConnect (curl/git install only) fireconnect uninstall # Disable all harnesses, restore configs, remove CLI fireconnect help # Show help fireconnect --version # Print the installed CLI version (-V also works; --json for machine-readable) ``` Global options for `model list`: ```bash theme={null} fireconnect model list --search glm # filter by name fireconnect model list --refresh # bypass the 1-hour cache fireconnect model list --json # machine-readable output ``` Run `fireconnect help` for the overview, or `fireconnect claude help` (and similarly for other harnesses) for harness-level options. ## Sign in options | Flag | Use when | | ------------------ | -------------------------------------------------------------------------------------------------- | | `--paste` | Skip the browser chooser and paste a key at the prompt | | `--api-key fw_...` | Sign in with a key directly (no prompt) | | `--with-token` | Read a key from stdin (handy in CI): `echo "$FIREWORKS_API_KEY" \| fireconnect login --with-token` | | `--account ` | Enterprise SSO sign-in (same account id as `firectl signin`) | | `--force` | Replace an existing stored key without a confirmation prompt | | `logout --revoke` | Clear local credentials **and** revoke the machine key on Fireworks | ```bash theme={null} fireconnect status --json # machine-readable sign-in and key-storage details ``` For direct Fireworks routing, `~/.fireconnect/config.json` normally stores a keychain or environment reference such as `{keychain:fireworks-api-key}` or `{env:FIREWORKS_API_KEY}`. Explicit Anthropic keys and Azure keys passed with `--api-key` may be stored literally. FireConnect writes the file with mode `0600` when it contains a literal key. ## Global configuration `fireconnect configure` sets provider defaults and shared keys. It does **not** sign you in. Use `login` for your Fireworks API key. ```bash theme={null} fireconnect configure \ --provider azure \ --base-url "https://YOUR_RESOURCE.services.ai.azure.com" \ --api-key $AZURE_API_KEY fireconnect configure --anthropic-api-key sk-ant-... fireconnect configure --provider fireworks ``` In `configure`, `--api-key` is the **Azure** endpoint key and requires `--provider azure`. For Fireworks keys, use `fireconnect login`. ## Providers | Provider flag | Where inference runs | API key | Supported harnesses | | --------------------- | ------------------------------ | ------------------------------------------------- | ----------------------------------------------------- | | `fireworks` (default) | Fireworks gateway | `fw_...` (all harnesses) or `fpk_...` (not Codex) | All harnesses with a supported key | | `azure` | Fireworks on Microsoft Foundry | Azure API key | All harnesses except Claude Code and DeepSeek Harness | Set the default with `fireconnect configure --provider fireworks` or `--provider azure`. Harness `on` commands use the configured provider unless you pass `--azure` or per-command `--base-url` / `--api-key` overrides. ## Per-harness commands ```bash theme={null} fireconnect model list --search glm fireconnect claude on --model glm-fast-latest --sonnet kimi-latest fireconnect opencode on --model glm-fast-latest ``` Each CLI harness (`claude`, `opencode`, `codex`, `chatgpt`, `pi`, `deepseek`) supports: * `fireconnect on`: route through the configured provider * `fireconnect off`: restore your previous config * `fireconnect status`: show provider, auth, and models * `fireconnect help`: harness-specific help Claude Code also has `usage`, `live`, and `demo`. See [Usage and live meter](/ecosystem/fireconnect/claude-code#usage-and-live-meter) and the [side-by-side demo](/ecosystem/fireconnect/demo). Each IDE harness (`cursor`, `vscode`) supports `on`, `off`, `status`, and `help`. Commands that write settings require quitting the IDE first; `status` is read-only. ### Model flags Use `--model ` for the primary model. Claude Code also supports slot flags: `--opus`, `--sonnet`, `--haiku`, `--fable`, `--subagent`. See **[Models](/ecosystem/fireconnect/models)** for a cross-harness quick reference, restart requirements, and common mistakes. Claude Code-only flags: * `--interactive`: open the model mapping wizard (cannot combine with model flags) * `--non-interactive`: skip first-run onboarding and use saved preferences or automatic setup On the Foundry path, pass your model with `--model` (for example, `--model FW-GLM-5.2`). `--main` is a retired alias for `--model` in v0.9.0+. Prefer `--model` in new scripts. FireRouter flags (when a slot uses `firerouter`): * `--model firerouter`: sets **main** to FireRouter. On first setup, FireConnect assigns models to unspecified aliases; on later runs, saved or active alias mappings are preserved * `--opus firerouter` (Claude Code): sets Opus to FireRouter. Set `--sonnet` explicitly when you need a specific Sonnet mapping * `native`: leave a Claude slot unpinned (CLI spelling; the wizard shows **Claude default**). This removes the model pin; it does not change the configured provider endpoint * `--anthropic-api-key sk-ant-...`: optional BYOK for Claude Opus 5 pass-through (where the harness supports it). Usually unnecessary in Claude Code when you already have subscription, OAuth, or API-key auth * `--routing-preference `: `1`–`5` or `max-intelligence`, `more-intelligence`, `balanced`, `more-savings`, or `max-savings` — CLI flag only, no in-app slider (Claude Code, OpenCode, Pi, VS Code). See [Routing preferences](/ecosystem/firerouter/routing-preferences) ## API key resolution **Direct Fireworks routing** (`--provider fireworks`) 1. Explicit `--api-key` 2. OS keychain (via `fireconnect login`) 3. Global `~/.fireconnect/config.json` reference 4. `FIREWORKS_API_KEY` environment variable When `FIREWORKS_API_KEY` is set, `login` uses it without storing a copy. Unset it before `login --api-key`, `--with-token`, or browser sign-in. Claude Code additionally reads harness-local keys from `~/.claude/settings.json` when FireConnect is already enabled there. **Fireworks on Microsoft Foundry** (`--provider azure`) 1. Explicit `--api-key` 2. Global `~/.fireconnect/config.json` 3. `AZURE_API_KEY` environment variable ## Migration from earlier syntax Only needed if you still have old scripts or muscle memory. Day-to-day use is `fireconnect on --model `. | Before | After | | ----------------------------------- | --------------------------------------------------------------------------------------------- | | `fireconnect on` | `fireconnect claude on` | | `fireconnect off` | `fireconnect claude off` | | `fireconnect status` | `fireconnect claude status` | | `fireconnect list` | `fireconnect claude status` | | `fireconnect set --main ` | `fireconnect claude on --model ` | | `fireconnect reset` | `fireconnect claude on` (preserves the saved or active mapping; use model flags to change it) | | `fireconnect on --harness opencode` | `fireconnect opencode on` | | Feature | Details | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Status line | Session cost bar in Claude Code showing per-model estimated cost and cache rates. Your own `statusLine` is preserved. | | ChatGPT app | `fireconnect chatgpt` is an alias for `codex` — routes both Codex CLI and ChatGPT desktop from one config. Quit the app before `on`. | | Smart routers | Pin `auto` or `auto-instant` on Claude slots for open-model mixes (preview). | | Model list cache | Catalog cached for 1 hour, works offline, `--refresh` refetches. Lists `auto`, `auto-instant`, and FireRouter. | | `claude status` | Shows every resolved slot, including slots you never explicitly set. | | GLM 5.3 | `glm-5p3` and `glm-5p3-flash` added; US-only `glm-5p3-flash-us` pricing corrected. | | Feature | Details | | -------------- | ----------------------------------------------------------------------------- | | `claude demo` | Improved side-by-side race cost calculation and terminal experience | | Cursor restore | More robust `on` / `off`; uninstall waits for Cursor to quit before restoring | | `uninstall` | Guided harness-by-harness restore that waits for running IDEs | | Feature | Details | | -------------------- | --------------------------------------------------------------------------------------------------- | | Deprecated Flash pin | Existing Claude `deepseek-v4-flash` pins migrate to `deepseek-flash-latest` on the next `claude on` | | Mixed models | Claude Code can mix Anthropic and Fireworks models while routed through FireConnect | | Harness replacement | `fireconnect deepseek` for DeepSeek Harness replaces `fireconnect deepagents` | | Demo command | Use `fireconnect claude demo`; the old top-level `fireconnect demo` form is deprecated | | Feature | Details | | --------------------- | -------------------------------------------------------- | | `claude live` | tmux split with live usage meter | | `claude usage --days` | Wider session picker lookback (interactive mode only) | | VS Code | Uses `chat-completions` API (auto-migrated) | | Cursor | Hides built-in models; preserves native IDs on re-enable | | Feature | Details | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fireconnect upgrade` | In-place upgrade for curl/git installs; interactive terminals may prompt **Upgrade now?** | | Seamless upgrade | From 0.9.0 on, harness settings (including Claude Code) are preserved across upgrade/reinstall | | Upgrade from before 0.9.0 | With Claude connected, FireConnect restores original Claude settings before updating; run `fireconnect claude on` afterward. In CI, set `FIRECONNECT_AUTO_OFF_CLAUDE=1` | | Before | After | | ------------------------------------ | ------------------------------------------------------------------------------------------------ | | `fireconnect model list` | `fireconnect model list` | | `fireconnect model select` | `fireconnect on --model ` or slot flags | | `fireconnect model reset` | `fireconnect on` (preserves the saved or active mapping; use model flags to change it) | | `--main ` on `on` | `--model ` | | Claude `apiKeyHelper` auth | `X-Fireworks-Api-Key` custom header in `settings.json` | ## See also * [FireConnect overview](/ecosystem/fireconnect/overview) * [Models](/ecosystem/fireconnect/models) * [Upgrade FireConnect](/ecosystem/fireconnect/overview#upgrade-fireconnect) # Codex Source: https://docs.fireworks.ai/ecosystem/fireconnect/codex Use Fireworks AI models in OpenAI Codex CLI with the FireConnect CLI [FireConnect](https://github.com/fw-ai/fireconnect) routes the [OpenAI Codex CLI](https://developers.openai.com/codex) through Fireworks AI models via the Responses API. See the [FireConnect overview](/ecosystem/fireconnect/overview) for install and CLI basics. **Change models:** `fireconnect codex on --model `. See [Models](/ecosystem/fireconnect/models). ## Prerequisites * [OpenAI Codex CLI](https://developers.openai.com/codex) installed (0.134+) * A standard [Fireworks API key](https://app.fireworks.ai/settings/users/api-keys) (`fw_...`) * FireConnect **v0.9.5+** (see [Install](/ecosystem/fireconnect/overview#install)) Fire Pass keys (`fpk_...`) are not supported for Codex yet. The `/responses` endpoint requires a standard Fireworks API key. ## Enable Fireworks routing `fireconnect codex` and `fireconnect chatgpt` share one config — both the [Codex CLI](https://developers.openai.com/codex) and the **ChatGPT desktop app** route through Fireworks with a single command. **Quit the ChatGPT app** before `on` or `off` so its model list refreshes. Same quit rules as Cursor and VS Code. ```bash theme={null} fireconnect login fireconnect codex on ``` Or pass the key once: ```bash theme={null} fireconnect codex on --api-key fw_... ``` After `fireconnect codex on` or `off`, `config.toml` is updated immediately. To use updated routing, exit Codex and resume with `codex resume `, or start a new session. ## Default model Codex routes a single default model. The default is `kimi-fast-latest`. ```bash theme={null} fireconnect codex status ``` ## What gets written FireConnect edits `~/.codex/config.toml`: * Sets root `model_provider` / `model` for Codex 0.134+ (stored as a short slug) * Adds a `[model_providers.fireworks-ai]` block with `wire_api = "responses"` and a **baked** `experimental_bearer_token` literal (file mode `0600`). Codex reads the key from config; no shell hook is required. FireConnect snapshots your original `~/.codex/config.toml` before the first change. The snapshot lives in `~/.fireconnect/codex/`. Running `fireconnect codex off` restores it byte-for-byte. Unrelated Codex settings (for example `[[mcp_servers]]`) are preserved via surgical TOML edits. ## Codex model catalog When you run `fireconnect codex on`, FireConnect fetches your account's serverless catalog and writes Codex-compatible model metadata to `~/.codex/fireworks-model-catalog.json`. It links that file from `config.toml` via `model_catalog_json` so Codex knows display names, context windows, reasoning levels, and tool-calling support for each model. ```bash theme={null} fireconnect codex status # shows whether the catalog is linked and on disk ``` The catalog includes serverless models that support tool calling with a non-zero context window, plus curated aliases such as `glm-fast-latest`. Deprecated models are excluded. If catalog generation fails (for example, due to an invalid API key), routing still works but Codex may show limited model metadata until you re-run `fireconnect codex on`. Browse available models globally: ```bash theme={null} fireconnect model list --search glm fireconnect model list --json # includes IN / OUT pricing where known ``` ## FireRouter Route requests through [FireRouter](/ecosystem/firerouter/overview): ```bash theme={null} fireconnect codex on --model firerouter export ANTHROPIC_API_KEY=sk-ant-... # optional BYOK for pass-through to Claude Opus 5 fireconnect codex on --model firerouter --anthropic-api-key sk-ant-... ``` FireConnect rejects `--model firerouter` with Fire Pass (`fpk_...`) on every harness; use an `fw_...` key. Codex also does not support Fire Pass for direct routing. Export `ANTHROPIC_API_KEY` yourself, or pass `--anthropic-api-key` and FireConnect will export it for Codex. Codex does not support `--routing-preference`. **MiniMax models are not supported in Codex.** Codex uses the Fireworks Responses API and may insert assistant messages between `tool_calls` and `tool_results`. MiniMax chat templates require `tool_results` to follow `tool_calls` directly. Use Chat Completions harnesses (for example Claude Code or OpenCode) for MiniMax. ## CLI reference ```bash theme={null} fireconnect codex on # Enable Fireworks routing fireconnect chatgpt on # Alias — same config as codex (includes ChatGPT desktop app) fireconnect codex off # Restore original config fireconnect codex status # Check current provider and model fireconnect codex help # Show harness-specific help ``` Run `fireconnect codex help` for all options. ### Switch models ```bash theme={null} fireconnect codex on --model glm-5p2 fireconnect codex on --model deepseek-flash-latest ``` Some models expose multiple reasoning levels in the Codex catalog (for example, `glm-5p2` supports `high` and `max`). Pick the model in Codex with `/model` after switching. ### Turn off Fireworks routing ```bash theme={null} fireconnect codex off ``` This restores your previous `config.toml` from the backup in `~/.fireconnect/codex/`. ### Use a non-default config file ```bash theme={null} fireconnect codex on --config-path /path/to/config.toml ``` ## Fireworks on Microsoft Foundry Codex supports **Fireworks on Microsoft Foundry** (CLI: `--provider azure` or `on --azure`). FireRouter is not available on the Foundry path; run `fireconnect configure --provider fireworks` before using `--model firerouter`. See the [FireConnect overview](/ecosystem/fireconnect/microsoft-foundry) and [Microsoft Foundry integration guide](/ecosystem/integrations/azure-foundry) for portal setup. Foundry routing requires a standard Azure API key. Fire Pass keys (`fpk_...`) are not supported. FireConnect does not write a Fireworks model catalog on the Foundry path. Set your deployment with `--model`. ### Configure and enable ```bash theme={null} export AZURE_API_KEY="YOUR_AZURE_API_KEY" fireconnect configure \ --provider azure \ --base-url "https://YOUR_RESOURCE.services.ai.azure.com" \ --api-key $AZURE_API_KEY fireconnect codex on --model FW-GLM-5.2 ``` One-off routing: ```bash theme={null} fireconnect codex on --azure --base-url "https://YOUR_RESOURCE.services.ai.azure.com" --model FW-MiniMax-M2.5 ``` ### What gets written FireConnect sets `model_provider = "fireworks-azure"` in `config.toml` with a **Fireworks on Microsoft Foundry** provider block pointed at your Foundry endpoint. The Azure API key is baked as a literal when passed with `--api-key`, or referenced via `env_key = "AZURE_API_KEY"` when resolved from the environment. Pass your Foundry model with `--model` (for example, `FW-GLM-5.2`). Use `fireconnect model list` only for browsing Fireworks serverless models on the direct gateway path. ### Turn off Foundry routing To switch back to the Fireworks gateway: ```bash theme={null} fireconnect configure --provider fireworks fireconnect codex on ``` To remove FireConnect entirely and restore your original `config.toml`: ```bash theme={null} fireconnect codex off ``` See [Turn off Foundry routing](/ecosystem/fireconnect/microsoft-foundry#turn-off-foundry-routing) for details on global config behavior and `uninstall`. ## Source FireConnect is open source: [github.com/fw-ai/fireconnect](https://github.com/fw-ai/fireconnect) # Cursor Source: https://docs.fireworks.ai/ecosystem/fireconnect/cursor Use Fireworks AI models in Cursor IDE with the FireConnect CLI [FireConnect](https://github.com/fw-ai/fireconnect) routes [Cursor](https://cursor.com) through Fireworks AI models via Cursor's OpenAI-compatible BYOK path. See the [FireConnect overview](/ecosystem/fireconnect/overview) for install and CLI basics. **Change models:** quit Cursor → `fireconnect cursor on --model `. See [Models](/ecosystem/fireconnect/models). ## Prerequisites * [Cursor](https://cursor.com) installed * A [Fireworks API key](https://app.fireworks.ai/settings/users/api-keys) (`fw_...`) or a [Fire Pass](/firepass) key (`fpk_...`) * FireConnect **v0.9.1+** (see [Install](/ecosystem/fireconnect/overview#install)) **Quit Cursor before `on` or `off`.** FireConnect writes Cursor's SQLite settings database; the IDE must be fully closed. `status` is read-only while Cursor is running. **FireRouter on Cursor needs workspace BYOK** (no local Anthropic key). FireConnect rejects `--model firerouter` with Fire Pass (`fpk_...`) on every harness; use an `fw_...` key, then `fireconnect cursor on --model firerouter`. See [FireRouter](/ecosystem/firerouter/overview). ## Enable Fireworks routing Cursor stores AI settings in a SQLite database (`state.vscdb`). **Fully quit Cursor** before running commands that write to it (for example, **Cmd+Q** on macOS or close all Cursor windows on Linux). Otherwise Cursor's in-memory state can overwrite FireConnect's changes. In an interactive terminal, if Cursor is still running FireConnect asks you to quit it and press Enter to continue. Pass `--force` to write anyway without waiting. ```bash theme={null} fireconnect login fireconnect cursor on ``` Or pass the key once: ```bash theme={null} fireconnect cursor on --api-key fw_... ``` `cursor on` sets **every mode that already exists** in `modelConfig` to the default Fireworks model (non-destructive: it won't create mode entries that aren't already there) and registers the preferred serverless catalog in the picker. Quit and reopen Cursor for the change to take effect, then open the model picker and choose a Fireworks model. ```bash theme={null} fireconnect cursor status # read-only; works while Cursor is running ``` ## Browse and pick models Browse the global catalog, then switch models with `on`: ```bash theme={null} fireconnect model list --search glm fireconnect cursor on --model glm-fast-latest ``` `fireconnect model list` and `status` are read-only and work while Cursor is running. Commands that write to `state.vscdb` (`on`, `off`) require Cursor to be quit first. Short model IDs are expanded to full Fireworks paths automatically. Cursor modes include `composer` (default), `cmd-k`, `background-composer`, `composer-ensemble`, `plan-execution`, `spec`, `deep-search`, and `quick-agent`. Run `fireconnect cursor status` to see the current model for each mode. Cursor enforces an allowlist on the server side. Not every Fireworks model appears in the picker even after you add it. Models such as GLM 5.2 and Kimi K2.6 are known to work; if a model is blocked, Cursor shows an error when you select it. **While FireConnect is on, only Fireworks models work.** Built-in Cursor models are hidden. `fireconnect cursor off` restores them. v0.9.2+ preserves your native model IDs (for example `auto-smart`) on re-enable. ## What gets written FireConnect writes Cursor's BYOK OpenAI settings in the local SQLite state database at `state.vscdb`: | Setting | Location | | ---------------- | -------------------------------------------------------------------------------------------- | | API key | `cursorAuth/openAIKey` (plaintext) | | Base URL | `openAIBaseUrl` on the `applicationUser` blob: `https://api.fireworks.ai/inference/v1` | | Custom models | `aiSettings.userAddedModels` + `aiSettings.fireconnectAddedModels` (tracked for clean `off`) | | Hidden built-ins | `aiSettings.modelOverrideDisabled` (Cursor subscription and built-in models) | | Per-mode model | `aiSettings.modelConfig[]` | Platform paths for `state.vscdb`: | Platform | Path | | -------- | --------------------------------------------------------------------- | | Linux | `~/.config/Cursor/User/globalStorage/state.vscdb` | | macOS | `~/Library/Application Support/Cursor/User/globalStorage/state.vscdb` | | Windows | `%APPDATA%\Cursor\User\globalStorage\state.vscdb` | FireConnect snapshots your previous Cursor auth state under `~/.fireconnect/cursor/` before the first change. Running `fireconnect cursor off` restores it. `off` only removes models FireConnect registered; your own custom models are preserved. ## Cursor feature coverage FireConnect configures Cursor's OpenAI BYOK path. Features that route through that path can use Fireworks models. Some Cursor features (for example, Composer, inline edit, and autocomplete) may still use Cursor's own backend depending on your plan and Cursor version. Test the workflows you care about after enabling. ## Using Fire Pass Use your `fpk_...` key during `login` or with `--api-key`: ```bash theme={null} fireconnect cursor on --api-key fpk_... ``` Fire Pass keys default to `kimi-fast-latest`. ## CLI reference ```bash theme={null} fireconnect cursor on # Enable Fireworks routing (quit Cursor first) fireconnect cursor off # Restore your previous Cursor auth state fireconnect cursor status # Show provider, auth, modes, and per-mode models fireconnect cursor help # Show harness-specific help ``` Run `fireconnect cursor help` for all options, including `--db-path` (explicit `state.vscdb` path) and `--force` (write even if Cursor appears to be running; not recommended). ### Turn off Fireworks routing Quit Cursor, then run: ```bash theme={null} fireconnect cursor off ``` This restores your previous Cursor auth state from the backup in `~/.fireconnect/cursor/`. Quit and reopen Cursor for full effect. ## Manual setup You can also configure Cursor without FireConnect: 1. In Cursor settings, add a **Custom Model** with a Fireworks model ID (for example, `accounts/fireworks/models/glm-5p2` or a short alias like `glm-fast-latest`). 2. Set **Override OpenAI Base URL** to `https://api.fireworks.ai/inference/v1`. 3. Paste your Fireworks or Fire Pass API key. FireConnect automates these steps and makes it easy to swap models from the terminal. ## Fireworks on Microsoft Foundry Cursor supports **Fireworks on Microsoft Foundry** (CLI: `--provider azure` or `on --azure`). FireRouter is not available on the Foundry path; run `fireconnect configure --provider fireworks` before using `--model firerouter`. See [Microsoft Foundry in FireConnect](/ecosystem/fireconnect/microsoft-foundry) and the [portal setup guide](/ecosystem/integrations/azure-foundry). Foundry routing requires a standard Azure API key. Fire Pass keys (`fpk_...`) are not supported. **Quit Cursor** before `on` or `off`. ```bash theme={null} export AZURE_API_KEY="YOUR_AZURE_API_KEY" fireconnect configure \ --provider azure \ --base-url "https://YOUR_RESOURCE.services.ai.azure.com" \ --api-key $AZURE_API_KEY fireconnect cursor on --model FW-GLM-5.2 ``` One-off routing without changing global config: ```bash theme={null} fireconnect cursor on \ --azure \ --base-url "https://YOUR_RESOURCE.services.ai.azure.com" \ --model FW-MiniMax-M2.5 ``` Pass your Foundry model with `--model` (for example, `FW-GLM-5.2`), not a Fireworks serverless short ID. FireConnect points Cursor's OpenAI BYOK override at your Foundry OpenAI-compatible endpoint and registers the deployment in the model picker. `fireconnect model list` only browses the Fireworks serverless catalog on the direct gateway path. To switch back to the Fireworks gateway: ```bash theme={null} fireconnect configure --provider fireworks fireconnect cursor on ``` See [Turn off Foundry routing](/ecosystem/fireconnect/microsoft-foundry#turn-off-foundry-routing) for `off` and global config behavior. ## Source FireConnect is open source: [github.com/fw-ai/fireconnect](https://github.com/fw-ai/fireconnect) # DeepSeek Harness Source: https://docs.fireworks.ai/ecosystem/fireconnect/deepseek Use Fireworks AI models in DeepSeek Harness with the FireConnect CLI [FireConnect](https://github.com/fw-ai/fireconnect) routes [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`) through Fireworks AI models. See the [FireConnect overview](/ecosystem/fireconnect/overview) for install and CLI basics. **Change models:** `fireconnect deepseek on --model `. See [Models](/ecosystem/fireconnect/models). ## Prerequisites * [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`) installed * A [Fireworks API key](https://app.fireworks.ai/settings/users/api-keys) (`fw_...`) or a [Fire Pass](/firepass) key (`fpk_...`) * FireConnect **v0.9.3+** (see [Install](/ecosystem/fireconnect/overview#install)) ## Enable Fireworks routing ```bash theme={null} fireconnect login fireconnect deepseek on ``` Or pass the key once: ```bash theme={null} fireconnect deepseek on --api-key fw_... ``` Restart `dsh` after `on` or `off` if it is already running. ```bash theme={null} fireconnect deepseek status ``` ## Default model DeepSeek Harness routes a single default model. The default is `kimi-fast-latest`. ## What gets written FireConnect updates two files under `$DSH_HOME` (default `~/.dsh`): * Adds a custom `fireworks` provider under `llm-pi-ai.providers` in `settings.yaml`, using the OpenAI-compatible endpoint at `https://api.fireworks.ai/inference/v1` * Sets `agent-default-model` to the selected Fireworks model * Stores the key as `FIREWORKS_API_KEY` in `.credentials.yaml` with file mode `0600` FireConnect snapshots both files under `~/.fireconnect/deepseek/` before the first change. Running `fireconnect deepseek off` restores them. ## Browsing and picking models ```bash theme={null} fireconnect model list --search glm fireconnect deepseek on --model glm-5p2 ``` Fire Pass keys only list Fire Pass routers. FireConnect rejects `--model firerouter` with Fire Pass (`fpk_...`) on every harness; use an `fw_...` key. ## FireRouter ```bash theme={null} fireconnect deepseek on --model firerouter ``` DeepSeek Harness cannot attach a local Anthropic key, so Anthropic pass-through requires workspace BYOK. ## CLI reference ```bash theme={null} fireconnect deepseek on # Enable Fireworks routing fireconnect deepseek off # Restore original settings and credentials fireconnect deepseek status # Check current provider and model fireconnect deepseek help # Show harness-specific help ``` Run `fireconnect deepseek help` for all options. ### Switch models ```bash theme={null} fireconnect deepseek on --model deepseek-flash-latest ``` ### Turn off Fireworks routing ```bash theme={null} fireconnect deepseek off ``` This restores the previous `settings.yaml` and `.credentials.yaml` snapshots. ### Use a non-default config file ```bash theme={null} fireconnect deepseek on --config-path /path/to/settings.yaml ``` The credentials file remains beside the selected settings file. Fireworks on Microsoft Foundry is not supported for DeepSeek Harness. `fireconnect deepseek on` uses the direct Fireworks gateway. ## Source FireConnect is open source: [github.com/fw-ai/fireconnect](https://github.com/fw-ai/fireconnect) # Side-by-side demo Source: https://docs.fireworks.ai/ecosystem/fireconnect/demo Race two models through Claude Code on the same prompt with fireconnect claude demo **`fireconnect claude demo`** runs the same code-generation prompt through two models using your current FireConnect Claude profile. It then puts the results next to each other so you can judge speed, cost, and output quality yourself. The demo reads your active FireConnect Claude profile but does not modify `~/.claude/settings.json`. Each side runs in a separate temporary working directory. ## What you get 1. **Live terminal race**: both models stream code in a split-pane TUI with real token counts and wall-clock timers. 2. **Browser comparison**: both generated apps run side by side, with measured speed and cost at the bottom. 3. **Shareable artifacts**: outputs land in `./fireconnect-demo/` (`compare.html`, `result.json`, stream logs). ### Browser comparison Side-by-side runnable apps with measured speed and cost: FireConnect demo browser comparison page with two Tetris apps side by side and speed and cost metrics ### Terminal race Split-pane TUI while both models stream the same prompt: Animated capture of a FireConnect split-pane terminal race between Claude Sonnet and GLM 5.2 Fast on a Tetris prompt ## Prerequisites * FireConnect installed ([overview](/ecosystem/fireconnect/overview#install)) * [Claude Code](https://claude.ai/code) CLI (`claude`) on your `PATH` * Claude Code already connected with `fireconnect claude` Both sides use the same authentication and routing as your existing FireConnect Claude setup. The demo only supports **Claude Code** today. ## Run the demo ```bash theme={null} fireconnect claude demo ``` That runs the default **Tetris** preset: both sides get the same prompt to build a playable game in a single HTML file. The old top-level `fireconnect demo` form is deprecated. Use `fireconnect claude demo`. ### Try other presets ```bash theme={null} fireconnect claude demo --prompt snake fireconnect claude demo --prompt clock fireconnect claude demo --prompt "Build a todo app in one HTML file" fireconnect claude demo --prompt-file ./task.txt ``` Presets: `tetris` (default), `snake`, or `clock`. You can also pass custom task text or use `--prompt-file`. ### Pick the models ```bash theme={null} fireconnect claude demo --left-model opus --right-model glm-fast-latest ``` The defaults are `opus` on the left and `glm-fast-latest` on the right. Pass any available model or Claude alias from your connected profile. ### Non-interactive / CI-friendly ```bash theme={null} fireconnect claude demo --yes --no-open --json ``` | Flag | What it does | | --------------------------- | ---------------------------------------------------------------------- | | `--yes` | Skip the setup form | | `--no-open` | Do not open a browser; write outputs to disk only | | `--json` | Print a machine-readable result to stdout (skips the TUI) | | `--out ` | Output directory (default: `./fireconnect-demo/`) | | `--prompt-file ` | Read a custom task from a file (overrides the preset) | | `--left-model ` | Left model (default: `opus`) | | `--right-model ` | Right model (default: `glm-fast-latest`) | | `--challenger ` | Alias for `--right-model` | | `--anthropic-model ` | Alias for `--left-model` (`opus`, `sonnet`, `haiku`, or `fable`) | | `--api-key ` | Override the Fireworks key from your environment or FireConnect config | ## Clean up ```bash theme={null} fireconnect claude demo clean # prompts before deleting ./fireconnect-demo/ fireconnect claude demo clean --yes # delete without prompting fireconnect claude demo clean --out /path/to/output ``` `demo clean` only removes directories that contain demo markers (`result.json`, `compare.html`, etc.), so it will not delete an unrelated folder you pointed `--out` at by mistake. ## After the demo Liked one of the models? Set it as your daily driver: ```bash theme={null} fireconnect claude on --model glm-5p2-fast ``` More IDs and latest vs fast guidance: [Models](/ecosystem/fireconnect/models). Want automatic cost routing instead of a fixed model? Try [FireRouter](/ecosystem/firerouter/overview): ```bash theme={null} fireconnect claude on --model firerouter ``` ## How it works * Each side runs real `claude -p` in a separate temporary working directory, using your active FireConnect Claude profile with only the model changed. * Numbers in the comparison strip are **measured from the run**, not list-price estimates. * If one side fails to finish, the page says so instead of fabricating a winner. * Open `compare.html` from the output folder anytime. It inlines both apps and works offline. ## Source The demo ships with FireConnect: [github.com/fw-ai/fireconnect](https://github.com/fw-ai/fireconnect) ## See also * [FireConnect overview](/ecosystem/fireconnect/overview) * [Models](/ecosystem/fireconnect/models) * [CLI reference](/ecosystem/fireconnect/cli-reference) # Microsoft Foundry Source: https://docs.fireworks.ai/ecosystem/fireconnect/microsoft-foundry Route FireConnect harnesses through Fireworks models deployed in your Azure subscription FireConnect can route supported harnesses through [Fireworks on Microsoft Foundry](/ecosystem/integrations/azure-foundry) instead of the Fireworks gateway. Usage is billed through Azure and counts toward your Microsoft Azure Consumption Commitment (MACC) where applicable. Enable Fireworks on Foundry, create a deployment, and find your project endpoint. Start here if you have not set up a Foundry resource yet. **CLI terminology:** The Foundry provider is `--provider azure` (or `on --azure`). Harness configs display the label **Fireworks on Microsoft Foundry**. With Foundry, `--model` is the model you deployed in Azure (for example, `FW-GLM-5.2`), not a Fireworks serverless short ID like `glm-fast-latest`. ## Supported harnesses | Harness | Azure in FireConnect | Notes | | ---------------- | -------------------- | ------------------------------------------------------------- | | OpenCode | Yes | `fireworks-azure` provider in `opencode.json` | | Codex | Yes | `fireworks-azure` block in `config.toml` | | Pi | Yes | `fireworks-azure` provider in `models.json` | | Cursor | Yes | OpenAI BYOK override pointed at Foundry | | VS Code | Yes | Custom chat-completions endpoint in `chatLanguageModels.json` | | DeepSeek Harness | No | `deepseek on` always uses the direct Fireworks gateway | | Claude Code | Not yet | `claude on` always wires direct Fireworks today | OpenCode, Codex, Pi, Cursor, and VS Code support Foundry routing in FireConnect v0.9.0+. Claude Code and DeepSeek Harness do not. ## Prerequisites * A Microsoft Foundry resource with at least one Fireworks model deployment (for example, `FW-GLM-5.2` or `FW-MiniMax-M2.5`) * Your Foundry resource endpoint and Azure API key from the [Microsoft Foundry portal](https://ai.azure.com/) * A supported harness installed locally * FireConnect v0.9.0+ (see [Overview: Install](/ecosystem/fireconnect/overview#install)) Use an **Azure API key** from Foundry, not a Fireworks key (`fw_...`) or Fire Pass key (`fpk_...`). Fire Pass is not supported on the Foundry path. FireRouter is also not available on the Foundry path. To use `--model firerouter`, first switch to the direct Fireworks gateway with `fireconnect configure --provider fireworks`. ## Configure once, then enable harnesses `fireconnect configure` sets the **Foundry provider and endpoint**. It does **not** set your Fireworks API key. Use `fireconnect login` for that when routing through the Fireworks gateway. ```bash theme={null} export AZURE_API_KEY="YOUR_AZURE_API_KEY" fireconnect configure \ --provider azure \ --base-url "https://YOUR_RESOURCE.services.ai.azure.com" ``` If no Azure key is already configured, this stores an `{env:AZURE_API_KEY}` reference. Otherwise, FireConnect keeps the existing configured key. To store the current environment value literally instead, pass it explicitly: ```bash theme={null} fireconnect configure \ --provider azure \ --base-url "https://YOUR_RESOURCE.services.ai.azure.com" \ --api-key "$AZURE_API_KEY" ``` FireConnect stores a top-level `provider` and `azure` block in `~/.fireconnect/config.json`. After configuring, enable harnesses normally: ```bash theme={null} fireconnect opencode on --model FW-GLM-5.2 fireconnect codex on --model FW-GLM-5.2 fireconnect pi on --model FW-GLM-5.2 fireconnect cursor on --model FW-GLM-5.2 fireconnect vscode on --model FW-GLM-5.2 ``` If you omit `--model`, FireConnect defaults to `FW-GLM-5.2`. **Cursor and VS Code:** fully quit the IDE before `on` or `off`. FireConnect writes SQLite state. In an interactive terminal it waits for you to quit; pass `--force` to write anyway. ### Endpoint normalization Pass your Foundry endpoint to `--base-url`. FireConnect normalizes whatever you paste to the correct OpenAI-compatible base at `https://.services.ai.azure.com/openai/v1`: * Bare resource root (`https://.services.ai.azure.com`) * Portal **project endpoint** (`.../api/projects/`) * Foundry **Models** route (`.../models`) * An already-correct base (`.../openai/v1`) Find the endpoint in the Microsoft Foundry portal under **Project settings**. ### API key storage * Export `AZURE_API_KEY` and omit `--api-key` to store an environment reference when no Azure key is already configured * Pass `--api-key` to write the Azure key literally into `~/.fireconnect/config.json` ## One-off Foundry routing Route a single harness through Foundry without changing global config: ```bash theme={null} fireconnect opencode on \ --azure \ --base-url "https://YOUR_RESOURCE.services.ai.azure.com" \ --api-key $AZURE_API_KEY \ --model FW-MiniMax-M2.5 ``` If global config already has a Foundry endpoint, `--azure` alone reuses it: ```bash theme={null} fireconnect cursor on --azure --model FW-GLM-5.2 ``` ## What each harness writes Each harness writes a dedicated Foundry config distinct from the Fireworks gateway. `off` restores your original config byte-for-byte. | Harness | Config file | Provider ID | Notes | | -------- | ------------------------------------------- | ---------------------------- | -------------------------------------------------------------------------------- | | OpenCode | `~/.config/opencode/opencode.json` | `fireworks-azure/FW-GLM-5.2` | `@ai-sdk/openai-compatible` adapter; `options.baseURL` + `options.apiKey` | | Codex | `~/.codex/config.toml` | `fireworks-azure` | `wire_api = "chat"`; bearer or `env_key = "AZURE_API_KEY"` | | Pi | `~/.pi/agent/models.json` + `settings.json` | `fireworks-azure` | `openai-completions` provider; key as literal or `$AZURE_API_KEY` in `auth.json` | | Cursor | `state.vscdb` | Foundry deployment name | OpenAI BYOK base URL + Azure key; one deployment in the picker | | VS Code | `chatLanguageModels.json` + `state.vscdb` | Foundry deployment name | Chat-completions endpoint; Azure key in secret storage | `fireconnect status` reports `azure` as the provider along with the endpoint and model. `fireconnect model list` browses the **Fireworks serverless catalog** only. It does not list Foundry deployments. With `--provider azure`, set your model with `--model` on `on`. ## Turn off Foundry routing There are two ways to stop using Microsoft Foundry, depending on what you want next. ### Switch back to direct Fireworks Use this when you want to keep FireConnect enabled but route through the Fireworks gateway again instead of your Foundry deployment. While `~/.fireconnect/config.json` has `provider: azure`, running `fireconnect on` **without** `--azure` still routes through Foundry. Change the global provider first. ```bash theme={null} fireconnect configure --provider fireworks fireconnect login # if you have not signed in yet fireconnect opencode on fireconnect codex on fireconnect pi on fireconnect cursor on fireconnect vscode on ``` Re-running `on` replaces the Foundry config with the normal Fireworks gateway config. You do **not** need to run `off` first. The Azure endpoint and key remain stored in `~/.fireconnect/config.json` but are unused while `provider` is `fireworks`. They are used again if you run `configure --provider azure` later. ### Remove FireConnect from a harness entirely Use `off` to remove FireConnect from a harness. When a pre-FireConnect backup is available, `off` restores it; otherwise it removes FireConnect-managed settings: ```bash theme={null} fireconnect pi off fireconnect opencode off fireconnect codex off fireconnect cursor off fireconnect vscode off ``` `off` removes Foundry wiring from harness config files. It does **not** change the global `provider` field in `~/.fireconnect/config.json`. If `provider` is still `azure`, the next `on` will route through Foundry again unless you run `configure --provider fireworks` first. Restart the harness after `off` if it is already running. For Cursor and VS Code, quit the IDE before `off`. ### Remove FireConnect everywhere ```bash theme={null} fireconnect uninstall ``` Disables all harnesses, restores every backup, and removes the CLI. | Goal | Commands | | ------------------------------------------- | ---------------------------------------------------------------------------- | | Stop Foundry, keep FireConnect on Fireworks | `fireconnect configure --provider fireworks` then `fireconnect on` | | Undo FireConnect for one harness | `fireconnect off` | | Undo FireConnect on all harnesses | `fireconnect uninstall` | ## Verify routing ```bash theme={null} fireconnect opencode status # provider=azure, base URL, model fireconnect codex status fireconnect pi status fireconnect cursor status fireconnect vscode status ``` ## Per-harness guides * [OpenCode](/ecosystem/fireconnect/opencode#fireworks-on-microsoft-foundry) * [Codex](/ecosystem/fireconnect/codex#fireworks-on-microsoft-foundry) * [Pi](/ecosystem/fireconnect/pi#fireworks-on-microsoft-foundry) * [Cursor](/ecosystem/fireconnect/cursor#fireworks-on-microsoft-foundry) * [VS Code](/ecosystem/fireconnect/vscode#fireworks-on-microsoft-foundry) ## Source FireConnect is open source: [github.com/fw-ai/fireconnect](https://github.com/fw-ai/fireconnect) # Models Source: https://docs.fireworks.ai/ecosystem/fireconnect/models Switch models in FireConnect harnesses: latest vs fast, smart routers, and US-only endpoints ```bash theme={null} fireconnect model list --search kimi fireconnect model list --refresh # bypass the 1-hour cache fireconnect on --model # Cursor / VS Code: quit the IDE before on, then reopen # Other harnesses: restart after on ``` `` is one of: `claude`, `opencode`, `codex`, `chatgpt`, `pi`, `cursor`, `vscode`, `deepseek`. There is no `model select` command. Always use `on --model`. ```bash theme={null} fireconnect opencode on --model kimi-fast-latest fireconnect claude on --model firerouter fireconnect claude on --interactive # Claude model mapping wizard fireconnect claude on --opus glm-fast-latest --sonnet auto-instant ``` Claude Code: `--model` sets **main** only; use slot flags or `--interactive` for the rest. Claude adds `[1m]` on 1M-context models for every slot. Re-running `on` without flags keeps your current mapping. | Harness | Apply the change | | ------------------------------------- | --------------------------------------------------- | | Cursor, VS Code | **Quit the IDE**, run `on --model`, then reopen | | Claude Code | New session, or `/exit` then `claude --resume ` | | OpenCode, Codex, Pi, DeepSeek Harness | Restart the CLI after `on` | ## Browse the catalog ```bash theme={null} fireconnect model list fireconnect model list --search glm fireconnect model list --json fireconnect model list --refresh ``` FireConnect fetches coding-tagged serverless models, merges version-tracking aliases (`glm-latest`, `kimi-fast-latest`, …), and lists smart routers (`auto`, `auto-instant`, `firerouter`). Results are **cached for one hour** and work offline — `--refresh` refetches when you need the latest. ## Latest vs Fast FireConnect short IDs follow the same [Serverless serving paths](/serverless/serving-paths) as the API: | Kind | Example IDs | When to use | | -------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | **Latest** (standard path) | `kimi-latest`, `glm-latest`, `deepseek-pro-latest`, `deepseek-flash-latest` | Best price/quality; tracks current model versions | | **Fast** | `kimi-fast-latest`, `glm-fast-latest` | Interactive coding where token speed matters. Same model quality as latest, higher \$/token, aims for **100+ tok/s**. | | **Pinned** | `kimi-k3`, `glm-5p2`, `kimi-k3-fast` | Stable ID that does not track new versions. | Prefer `*-latest` / `*-fast-latest` unless you need a pin. ## Which model when | ID | Use when | Notes | | ----------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `kimi-fast-latest` | Interactive coding; screenshots / UI | Vision. | | `kimi-latest` | Strong agentic coding with vision, lower \$/token than Fast | Vision. Standard path. | | `deepseek-pro-latest` | Strong text-only coding and reasoning | Text-only. | | `deepseek-flash-latest` | Haiku / subagent / high-volume background work | Text-only. | | `glm-flash-latest` | Vision-capable GLM for Fable / image tasks | Vision. | | `glm-fast-latest` | Fast text-only agent loops | Text-only. 1M context. | | `glm-latest` | Cheaper text-only coding / long context | Text-only. | | `firerouter` | Auto-route easy work to open models, hard work to Claude Opus 5 | See [FireRouter](/ecosystem/firerouter/overview). Use `--model firerouter` for Main, a slot flag for one alias, or `--interactive` to choose aliases. Use `native` to leave a slot unpinned. | | `auto` | Fireworks default open-model mix | Preview. Available on every Claude slot. | | `auto-instant` | Latency-first open-model mix | Preview. Available on Claude Sonnet. | Also useful from `fireconnect model list`: `minimax-latest` / `qwen-plus-latest` (cheaper vision), `kimi-k2p7-code` / `kimi-k2p7-code-fast` (code-focused Kimi), `glm-5p3` / `glm-5p3-flash`. The pinned `deepseek-v4-flash` serverless model is deprecated. FireConnect v0.9.3+ migrates existing Claude pins to `deepseek-flash-latest` on the next `claude on`. Prefer `-latest` aliases so future model upgrades don't require another config change. `glm-latest`, `glm-fast-latest`, and DeepSeek Flash/Pro are **text-only**. Pasting images on those slots in Claude Code can break the session. Recover with `/rewind`, or use a Kimi, `glm-flash-latest`, or GLM 5.3 Flash model. See [Claude Code troubleshooting](/ecosystem/fireconnect/claude-code#troubleshooting). ## US-only For US-only inference (compliance), pass the short US router slug with `on --model`: | Model | Short ID | | ------------------ | ------------------ | | Kimi K3 (US) | `kimi-k3-us` | | GLM 5.2 Fast (US) | `glm-5p2-fast-us` | | GLM 5.3 Flash (US) | `glm-5p3-flash-us` | ```bash theme={null} fireconnect claude on --model kimi-k3-us fireconnect opencode on --model glm-5p2-fast-us fireconnect claude on --model glm-5p3-flash-us ``` Beginning September 1, 2026, US-only endpoints launched from that date are priced at a **50% premium** over the matching global row (`glm-5p3-flash-us`). Earlier routers keep their launch rates: `kimi-k3-us` at a 10% premium, `glm-5p2-fast-us` at parity with global GLM 5.2 Fast. Details: [US-only Serverless](/serverless/us-only-serverless). ## Limits * **Fire Pass** (`fpk_...`): Catalog is limited. Not on Codex. FireConnect rejects `--model firerouter` with a Fire Pass key on **every** harness; use an `fw_...` account key for FireRouter. * **Foundry**: pass the Azure deployment name (`FW-GLM-5.2`), not a short Fireworks ID. FireRouter is not available on the Foundry path. Claude Code and DeepSeek Harness do not support Foundry. * **FireRouter**: standard key only (`fw_...`), not Fire Pass. Cursor / DeepSeek Harness need workspace BYOK for Anthropic pass-through. ## Troubleshooting Restart the harness. For Cursor and VS Code, fully quit the IDE **before** running `on`. FireConnect rejects `--model firerouter` when your stored key is Fire Pass (`fpk_...`), on every harness. Switch to an `fw_...` account key, then run `fireconnect on --model firerouter` and restart the harness. Pass the Azure **deployment name** (for example `FW-GLM-5.2`), not a serverless short ID. Run `fireconnect model list --refresh`. Without network, FireConnect keeps showing the last cached catalog instead of clearing it. ## See also * [FireConnect overview](/ecosystem/fireconnect/overview) * [CLI reference](/ecosystem/fireconnect/cli-reference) * [Claude Code](/ecosystem/fireconnect/claude-code) # OpenCode Source: https://docs.fireworks.ai/ecosystem/fireconnect/opencode Use Fireworks AI models in OpenCode with the FireConnect CLI [FireConnect](https://github.com/fw-ai/fireconnect) routes [OpenCode](https://opencode.ai) through Fireworks AI models. See the [FireConnect overview](/ecosystem/fireconnect/overview) for install and CLI basics. **Change models:** `fireconnect opencode on --model `. See [Models](/ecosystem/fireconnect/models). ## Prerequisites * [OpenCode](https://opencode.ai) installed * A [Fireworks API key](https://app.fireworks.ai/settings/users/api-keys) (`fw_...`) or a [Fire Pass](/firepass) key (`fpk_...`) * FireConnect **v0.9.1+** (see [Install](/ecosystem/fireconnect/overview#install)) ## Enable Fireworks routing ```bash theme={null} fireconnect login fireconnect opencode on ``` Restart OpenCode after enabling, then confirm routing: ```bash theme={null} fireconnect opencode status ``` ## Using Fire Pass Use your `fpk_...` key during `login` or with `--api-key`: ```bash theme={null} fireconnect opencode on --api-key fpk_... ``` FireConnect detects Fire Pass keys and defaults OpenCode to `kimi-fast-latest`. ## Default model OpenCode routes a single default model (no opus/sonnet/haiku alias slots). The default is `kimi-fast-latest`, written to config as `fireworks-ai/kimi-fast-latest`. Short model IDs like `glm-5p2` are expanded to full Fireworks paths (for example, `accounts/fireworks/models/glm-5p2`). ## What gets written FireConnect merges a `fireworks-ai` provider block into `~/.config/opencode/opencode.json`: * An OpenAI-compatible adapter pointed at `https://api.fireworks.ai/inference/v1` * A default `model` set to `fireworks-ai/` (for example, `fireworks-ai/glm-fast-latest`) * `options.apiKey` as a **baked plaintext literal** (file mode `0600`) * The **preferred serverless catalog** registered in the provider's `models` for OpenCode's `/model` picker FireConnect snapshots your original `opencode.json` before the first change. The snapshot lives in `~/.fireconnect/opencode/`. Running `fireconnect opencode off` restores the file byte-for-byte. OpenCode's `auth.json` is never touched. ## Browsing and picking models ```bash theme={null} fireconnect model list --search glm fireconnect opencode on --model glm-5p2 ``` `fireconnect model list` uses your stored key (keychain, config, or `FIREWORKS_API_KEY`). Fire Pass keys only list Fire Pass routers. FireConnect rejects `--model firerouter` with Fire Pass (`fpk_...`) on every harness; use an `fw_...` key. ## FireRouter ```bash theme={null} fireconnect opencode on --model firerouter ``` Pass `--anthropic-api-key sk-ant-...` when your workspace does not have Anthropic BYOK provisioned server-side. ## CLI reference ```bash theme={null} fireconnect opencode on # Enable Fireworks routing fireconnect opencode off # Restore original config fireconnect opencode status # Check current provider and model fireconnect opencode help # Show harness-specific help ``` Run `fireconnect opencode help` for all options. ### Switch models ```bash theme={null} fireconnect opencode on --model glm-5p2 ``` ### Turn off Fireworks routing ```bash theme={null} fireconnect opencode off ``` This restores your previous `opencode.json` from the backup in `~/.fireconnect/opencode/`. ### Use a non-default config file ```bash theme={null} fireconnect opencode on --config-path /path/to/opencode.json ``` ## Fireworks on Microsoft Foundry OpenCode supports **Fireworks on Microsoft Foundry** (CLI: `--provider azure` or `on --azure`). FireRouter is not available on the Foundry path; run `fireconnect configure --provider fireworks` before using `--model firerouter`. See the [FireConnect overview](/ecosystem/fireconnect/microsoft-foundry) and [Microsoft Foundry integration guide](/ecosystem/integrations/azure-foundry) for portal setup. ### Configure and enable ```bash theme={null} export AZURE_API_KEY="YOUR_AZURE_API_KEY" fireconnect configure \ --provider azure \ --base-url "https://YOUR_RESOURCE.services.ai.azure.com" \ --api-key $AZURE_API_KEY fireconnect opencode on --model FW-GLM-5.2 ``` One-off routing without changing global config: ```bash theme={null} fireconnect opencode on \ --azure \ --base-url "https://YOUR_RESOURCE.services.ai.azure.com" \ --model FW-MiniMax-M2.5 ``` Pass your Foundry model with `--model` (for example, `FW-GLM-5.2`), not a Fireworks serverless short ID like `glm-latest`. ### What gets written FireConnect adds a `fireworks-azure` provider labeled **Fireworks on Microsoft Foundry** to `opencode.json`, pointed at your Foundry OpenAI-compatible endpoint (`.../openai/v1`). The default model reference becomes `fireworks-azure/FW-GLM-5.2`. Use `fireconnect model list` only for browsing Fireworks serverless models on the direct gateway path. With Foundry, switch models with `on --model FW-GLM-5.2`. ### Turn off Foundry routing To switch back to the Fireworks gateway, change the global provider and re-enable: ```bash theme={null} fireconnect configure --provider fireworks fireconnect opencode on ``` To remove FireConnect entirely and restore your original `opencode.json`: ```bash theme={null} fireconnect opencode off ``` See [Turn off Foundry routing](/ecosystem/fireconnect/microsoft-foundry#turn-off-foundry-routing) for details on global config behavior and `uninstall`. ## Built-in provider connection OpenCode also supports connecting to Fireworks directly without FireConnect: 1. Type `/connect` in OpenCode and search for **fireworks.ai** 2. Paste your Fireworks API key and press Enter 3. Type `/models` and select a model (for Fire Pass, choose a supported model such as **GLM Fast Latest**) ## Source FireConnect is open source: [github.com/fw-ai/fireconnect](https://github.com/fw-ai/fireconnect) # Overview Source: https://docs.fireworks.ai/ecosystem/fireconnect/overview Route coding harnesses through Fireworks AI, with Microsoft Foundry support for compatible tools [FireConnect](https://github.com/fw-ai/fireconnect) is an open-source CLI that routes agentic coding harnesses through Fireworks models. Install once, sign in once, then flip any supported harness on or off — no proxy to run, no wrapper to launch. `on` updates the harness config. `off` restores saved pre-FireConnect settings when a backup is available; otherwise it removes FireConnect-managed settings. Choose where inference runs: * **Direct Fireworks routing** (default): the [Fireworks gateway](https://fireworks.ai). Sign in with `fireconnect login` or use a Fireworks API key (`fw_...`) or [Fire Pass](/firepass) key (`fpk_...`). * **Fireworks on Microsoft Foundry**: models in your Azure subscription, billed through Azure. See [Microsoft Foundry](/ecosystem/fireconnect/microsoft-foundry). New here? Follow [Quick start](#quick-start) below, then open the [harness guide](#choose-your-harness) for your tool. Try the [side-by-side demo](/ecosystem/fireconnect/demo) to compare models before switching. ## Quick start ### Install ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/fw-ai/fireconnect/main/install.sh | bash ``` **2. Sign in** ```bash theme={null} fireconnect login # browser sign-in, or paste a fw_… / fpk_… key ``` **3. Connect a harness** ```bash theme={null} fireconnect claude # first run opens the model mapping wizard ``` Use the wizard to choose Claude Code alias slots, or configure them explicitly with `--model`, `--opus`, `--sonnet`, `--haiku`, `--fable`, and `--subagent`. Eligible accounts also get the `fireworks-websearch` MCP (see [WebSearch MCP](/ecosystem/fireconnect/websearch-mcp)). **4. Restart the tool, then verify** ```bash theme={null} fireconnect claude status ``` Swap `claude` for any harness: `opencode`, `codex`, `chatgpt`, `pi`, `cursor`, `vscode`, `deepseek`. Bare harness names run `on` — `fireconnect claude` is the same as `fireconnect claude on`. ## Prerequisites * A [Fireworks API key](https://app.fireworks.ai/settings/users/api-keys) (`fw_...`) or [Fire Pass](/firepass) key (`fpk_...`) for direct routing * For Foundry: Azure resource, API key, and deployment. See [portal setup](/ecosystem/integrations/azure-foundry). * Node.js 18+ * At least one supported harness installed locally ### Install notes * Requires **bash** and **Node.js 18+**. The installer clones the CLI to `~/.fireconnect/cli`, adds `~/.local/bin/fireconnect` to your `PATH`, and runs the same finalize as `fireconnect upgrade`. It does **not** sign you in or touch harness settings. * You can pass `--api-key` or set `FIREWORKS_API_KEY` instead of `login`. **Windows:** run from Git Bash with the same curl command. Piping through PowerShell corrupts line endings (`set: pipefail\r: invalid option name`). ### Upgrade FireConnect ```bash theme={null} fireconnect upgrade ``` Or re-run the install curl above. From v0.9.0 onward, harness settings stay connected across upgrade. Check version with `fireconnect --version`. See [CLI reference: Migration](/ecosystem/fireconnect/cli-reference#migration-from-earlier-syntax) for renames. ## Sign in ```bash theme={null} fireconnect login # browser sign-in or paste a key fireconnect logout # clear stored credentials fireconnect status # sign-in state, key storage, and harness state ``` Fire Pass keys (`fpk_...`) work during `login` or `on`. FireConnect detects the key type and configures supported models. See [CLI reference: Sign in options](/ecosystem/fireconnect/cli-reference#sign-in-options) for `--with-token`, `--account`, `logout --revoke`, and `configure`. ## Choose your harness After install and sign-in, open the guide for the tool you use. Each page covers `on` / `off`, models, and harness-specific notes. Six model slots, usage meter, and session status line OpenAI-compatible adapter in `opencode.json` Codex CLI and ChatGPT desktop app via the Responses API Pi agent settings and auth OpenAI BYOK settings for Cursor IDE GitHub Copilot Chat custom endpoint DeepSeek's coding agent (`dsh`) ## Models ```bash theme={null} fireconnect model list --search glm fireconnect model list --refresh # bypass the 1-hour cache fireconnect on --model glm-fast-latest # Cursor / VS Code: quit before on; others: restart after ``` `` is one of: `claude`, `opencode`, `codex`, `chatgpt`, `pi`, `cursor`, `vscode`, `deepseek`. Full walkthrough: **[Models](/ecosystem/fireconnect/models)**. ## Harness support | Harness | Fireworks gateway | Fire Pass | Microsoft Foundry | [FireRouter](/ecosystem/firerouter/overview) | Guide | | ---------------- | :---------------: | :-------: | :---------------: | :------------------------------------------: | --------------------------------------------------- | | Claude Code | Yes | Yes | No | Yes | [Claude Code](/ecosystem/fireconnect/claude-code) | | OpenCode | Yes | Yes | Yes | Yes | [OpenCode](/ecosystem/fireconnect/opencode) | | Codex / ChatGPT | Yes | No | Yes | Yes | [Codex](/ecosystem/fireconnect/codex) | | Pi | Yes | Yes | Yes | Yes | [Pi](/ecosystem/fireconnect/pi) | | Cursor | Yes | Yes | Yes | Workspace BYOK | [Cursor](/ecosystem/fireconnect/cursor) | | VS Code | Yes | Yes | Yes | Yes | [VS Code](/ecosystem/fireconnect/vscode) | | DeepSeek Harness | Yes | Yes | No | Workspace BYOK | [DeepSeek Harness](/ecosystem/fireconnect/deepseek) | **Notes** * **Foundry**: not on Claude Code or DeepSeek Harness. * **FireRouter + Foundry**: FireRouter requires the direct Fireworks gateway; it is not available on the Microsoft Foundry path, even for harnesses that support both independently. * **Fire Pass**: not on Codex or Foundry. FireConnect rejects `--model firerouter` with a Fire Pass (`fpk_...`) key on **every** harness; use an `fw_...` account key for FireRouter. * **FireRouter**: Cursor and DeepSeek Harness need workspace BYOK for Anthropic pass-through. * **Web search MCP**: Claude Code auto-install only (eligible accounts); other harnesses can add the HTTP MCP manually. See [WebSearch MCP](/ecosystem/fireconnect/websearch-mcp). * **Cursor / VS Code**: quit the IDE before `on` or `off`. `status` is read-only. ## FireRouter and smart routers [FireRouter](/ecosystem/firerouter/overview) routes simple requests to cheaper open models and hard requests to Claude Opus 5. The default pair is **GLM 5.3** (redirect) and **Claude Opus 5** (pass-through). On Claude Code, use `--model firerouter` for Main or a slot flag such as `--opus firerouter` for one alias. Use `--interactive` to choose alias slots, and use `native` to leave a slot unpinned. See [Claude Code — FireRouter](/ecosystem/fireconnect/claude-code#firerouter). ```bash theme={null} fireconnect claude on --model firerouter fireconnect opencode on --model firerouter fireconnect claude on --model firerouter --routing-preference balanced ``` **Smart router mixes** (preview): pin `auto` for Fireworks' default open-model mix, or `auto-instant` for latency-first routing: ```bash theme={null} fireconnect claude on --sonnet auto-instant ``` Requires a standard Fireworks key (`fw_...`), not Fire Pass. See [Models](/ecosystem/fireconnect/models) and the [FireRouter overview](/ecosystem/firerouter/overview#fireconnect). ## Source FireConnect is open source: [github.com/fw-ai/fireconnect](https://github.com/fw-ai/fireconnect) ## See also * [CLI reference](/ecosystem/fireconnect/cli-reference) * [Microsoft Foundry](/ecosystem/fireconnect/microsoft-foundry) * [WebSearch MCP](/ecosystem/fireconnect/websearch-mcp) * [Side-by-side demo](/ecosystem/fireconnect/demo) # Pi Source: https://docs.fireworks.ai/ecosystem/fireconnect/pi Use Fireworks AI models in Pi with the FireConnect CLI [FireConnect](https://github.com/fw-ai/fireconnect) routes [Pi](https://pi.dev) through Fireworks AI models. See the [FireConnect overview](/ecosystem/fireconnect/overview) for install and CLI basics. **Change models:** `fireconnect pi on --model `. See [Models](/ecosystem/fireconnect/models). ## Prerequisites * [Pi](https://pi.dev) installed * A [Fireworks API key](https://app.fireworks.ai/settings/users/api-keys) (`fw_...`) or a [Fire Pass](/firepass) key (`fpk_...`) * FireConnect **v0.9.1+** (see [Install](/ecosystem/fireconnect/overview#install)) ## Enable Fireworks routing ```bash theme={null} fireconnect login fireconnect pi on ``` Restart Pi after enabling if it is already running. ```bash theme={null} fireconnect pi status ``` ## Using Fire Pass Use your `fpk_...` key during `login` or with `--api-key`: ```bash theme={null} fireconnect pi on --api-key fpk_... ``` FireConnect detects Fire Pass keys and defaults Pi to `kimi-fast-latest`. ## Default model Pi routes a single default model. The default is `kimi-fast-latest`. ## What gets written FireConnect: * Sets `defaultProvider` / `defaultModel` in `~/.pi/agent/settings.json` * Stores a **baked plaintext literal** in `fireworks.key` in `~/.pi/agent/auth.json` (mode `0600`) * Registers the **preferred serverless catalog** in `~/.pi/agent/models.json` for Pi's `/model` picker FireConnect snapshots `settings.json`, `auth.json`, and `models.json` under `~/.fireconnect/pi/` before the first change. Running `fireconnect pi off` restores them. ## Browsing and picking models ```bash theme={null} fireconnect model list --search glm fireconnect pi on --model glm-5p2 ``` Fire Pass keys only list Fire Pass routers. FireConnect rejects `--model firerouter` with Fire Pass (`fpk_...`) on every harness; use an `fw_...` key. ## FireRouter ```bash theme={null} fireconnect pi on --model firerouter fireconnect pi on --model firerouter --anthropic-api-key sk-ant-... ``` ## CLI reference ```bash theme={null} fireconnect pi on # Enable Fireworks routing fireconnect pi off # Restore original settings, auth, and model catalog fireconnect pi status # Check current provider and model fireconnect pi help # Show harness-specific help ``` Run `fireconnect pi help` for all options. ### Switch models ```bash theme={null} fireconnect pi on --model glm-5p2 ``` ### Turn off Fireworks routing ```bash theme={null} fireconnect pi off ``` This restores your previous `settings.json`, `auth.json`, and `models.json` from the backup in `~/.fireconnect/pi/`. ### Use a non-default settings file ```bash theme={null} fireconnect pi on --settings-path /path/to/settings.json ``` ## Fireworks on Microsoft Foundry Pi supports **Fireworks on Microsoft Foundry** (CLI: `--provider azure` or `on --azure`). FireRouter is not available on the Foundry path; run `fireconnect configure --provider fireworks` before using `--model firerouter`. See the [FireConnect overview](/ecosystem/fireconnect/microsoft-foundry) and [Microsoft Foundry integration guide](/ecosystem/integrations/azure-foundry) for portal setup. ### Configure and enable ```bash theme={null} export AZURE_API_KEY="YOUR_AZURE_API_KEY" fireconnect configure \ --provider azure \ --base-url "https://YOUR_RESOURCE.services.ai.azure.com" \ --api-key $AZURE_API_KEY fireconnect pi on --model FW-GLM-5.2 ``` One-off routing: ```bash theme={null} fireconnect pi on --azure --base-url "https://YOUR_RESOURCE.services.ai.azure.com" --model FW-MiniMax-M2.5 ``` ### What gets written FireConnect registers a `fireworks-azure` **openai-completions** provider in Pi's `models.json` (labeled **Fireworks on Microsoft Foundry**) and sets `defaultProvider` / `defaultModel` in `settings.json`. The Azure API key is stored in `auth.json` as a literal when passed with `--api-key`, or as `$AZURE_API_KEY` when resolved from the environment. Pass your Foundry model with `--model` (for example, `FW-GLM-5.2`). Use `fireconnect model list` only for browsing Fireworks serverless models on the direct gateway path. ### Turn off Foundry routing To switch back to the Fireworks gateway: ```bash theme={null} fireconnect configure --provider fireworks fireconnect pi on ``` To remove FireConnect entirely and restore your original `settings.json`, `auth.json`, and `models.json`: ```bash theme={null} fireconnect pi off ``` Restart Pi after switching or running `off`. See [Turn off Foundry routing](/ecosystem/fireconnect/microsoft-foundry#turn-off-foundry-routing) for details on global config behavior and `uninstall`. ## Source FireConnect is open source: [github.com/fw-ai/fireconnect](https://github.com/fw-ai/fireconnect) # VS Code Source: https://docs.fireworks.ai/ecosystem/fireconnect/vscode Use Fireworks AI models in GitHub Copilot Chat with the FireConnect CLI [FireConnect](https://github.com/fw-ai/fireconnect) adds Fireworks AI models to **[GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) Chat** in [Visual Studio Code](https://code.visualstudio.com) by writing a custom language-model endpoint. See the [FireConnect overview](/ecosystem/fireconnect/overview) for install and CLI basics. **Change models:** quit VS Code → `fireconnect vscode on --model `. See [Models](/ecosystem/fireconnect/models). Step-by-step UI walkthrough with screenshots. Add a Fireworks custom endpoint without the FireConnect CLI ## Prerequisites * [Visual Studio Code](https://code.visualstudio.com) with the [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) extension * GitHub Copilot **Pro** or **Enterprise** (the free tier only supports the Auto model) * A [Fireworks API key](https://app.fireworks.ai/settings/users/api-keys) (`fw_...`) or a [Fire Pass](/firepass) key (`fpk_...`) * FireConnect **v0.9.2+** (see [Install](/ecosystem/fireconnect/overview#install)) ## Enable Fireworks routing VS Code stores custom-endpoint API keys (encrypted) in `state.vscdb`. **Quit VS Code** before running `on` or `off`. In an interactive terminal, FireConnect waits for you to quit (or pass `--force` to write anyway). ```bash theme={null} fireconnect login fireconnect vscode on ``` Or pass the key once: ```bash theme={null} fireconnect vscode on --api-key fw_... ``` Start or restart VS Code, then open Copilot Chat and pick a Fireworks model from the model picker. ```bash theme={null} fireconnect vscode status # read-only; works while VS Code is running ``` ## Browse and switch models Direct Fireworks routing uses the **chat-completions** API. Kimi models support vision. Standard and Fast GLM models such as `glm-latest` and `glm-fast-latest` are text-only; `glm-flash-latest` and GLM 5.3 Flash support vision. ```bash theme={null} fireconnect model list --search glm fireconnect vscode on --model deepseek-flash-latest fireconnect vscode on --model firerouter ``` `on` registers the preferred serverless catalog in the VS Code Chat model picker. Pick models under **Other Models → Fireworks** in Copilot Chat. ## FireRouter ```bash theme={null} fireconnect vscode on --model firerouter --anthropic-api-key sk-ant-... ``` The Fireworks key stays encrypted in `state.vscdb`. An Anthropic BYOK key is optional for pass-through to Claude Opus 5. ## What gets written FireConnect merges a **Fireworks** custom endpoint into VS Code's language-model config and stores the API key in VS Code's secret storage: | What | Where | | ----------------- | ----------------------------------------------------------------- | | Provider + models | `chatLanguageModels.json` | | Encrypted API key | `state.vscdb` (`ItemTable`, key `secret://chat.lm.secret.fw-...`) | Platform paths: | Platform | `chatLanguageModels.json` | `state.vscdb` | | -------- | ----------------------------------------------------------------- | ------------------------------------------------------------------- | | Linux | `~/.config/Code/User/chatLanguageModels.json` | `~/.config/Code/User/globalStorage/state.vscdb` | | macOS | `~/Library/Application Support/Code/User/chatLanguageModels.json` | `~/Library/Application Support/Code/User/globalStorage/state.vscdb` | | Windows | `%APPDATA%\Code\User\chatLanguageModels.json` | `%APPDATA%\Code\User\globalStorage\state.vscdb` | The endpoint URL is `https://api.fireworks.ai/inference` (VS Code appends `/v1/chat/completions`). The API key lives in `state.vscdb`, not the JSON. On macOS, `safeStorage` encrypts with a master key VS Code stores in the login Keychain. On Linux, `safeStorage` needs `libsecret` (`secret-tool`) for real encryption. Without it, Chromium falls back to a hardcoded password (obfuscated, not encrypted), which FireConnect still writes but warns about. FireConnect snapshots the original `chatLanguageModels.json` under `~/.fireconnect/vscode/` before the first change. Running `fireconnect vscode off` restores it byte-for-byte and deletes the `chat.lm.secret.fw-*` secret row from `state.vscdb`. ## CLI reference ```bash theme={null} fireconnect vscode on # Add the Fireworks provider (quit VS Code first) fireconnect vscode off # Restore config and remove the stored key fireconnect vscode status # Show provider, auth, and registered models fireconnect vscode help # Show harness-specific help ``` Run `fireconnect vscode help` for all options, including `--vscode-path` (explicit `chatLanguageModels.json` path) and `--force`. ### Turn off Fireworks routing Quit VS Code, then run: ```bash theme={null} fireconnect vscode off ``` This restores your previous `chatLanguageModels.json` from the backup in `~/.fireconnect/vscode/` and removes the FireConnect secret from `state.vscdb`. Restart VS Code for the change to take effect. ## Fireworks on Microsoft Foundry VS Code supports **Fireworks on Microsoft Foundry** (CLI: `--provider azure` or `on --azure`). FireRouter is not available on the Foundry path; run `fireconnect configure --provider fireworks` before using `--model firerouter`. See [Microsoft Foundry in FireConnect](/ecosystem/fireconnect/microsoft-foundry) and the [portal setup guide](/ecosystem/integrations/azure-foundry). Foundry routing requires a standard Azure API key. Fire Pass keys (`fpk_...`) are not supported. **Quit VS Code** before `on` or `off`. ```bash theme={null} export AZURE_API_KEY="YOUR_AZURE_API_KEY" fireconnect configure \ --provider azure \ --base-url "https://YOUR_RESOURCE.services.ai.azure.com" \ --api-key $AZURE_API_KEY fireconnect vscode on --model FW-GLM-5.2 ``` One-off routing without changing global config: ```bash theme={null} fireconnect vscode on \ --azure \ --base-url "https://YOUR_RESOURCE.services.ai.azure.com" \ --model FW-MiniMax-M2.5 ``` Pass your Foundry model with `--model` (for example, `FW-GLM-5.2`), not a Fireworks serverless short ID. FireConnect adds a chat-completions custom endpoint pointed at Foundry and stores the Azure key in VS Code secret storage. `fireconnect model list` only browses the Fireworks serverless catalog on the direct gateway path. To switch back to the Fireworks gateway: ```bash theme={null} fireconnect configure --provider fireworks fireconnect vscode on ``` See [Turn off Foundry routing](/ecosystem/fireconnect/microsoft-foundry#turn-off-foundry-routing) for `off` and global config behavior. ## Related * [GitHub Copilot integration guide](/ecosystem/integrations/github-copilot): manual custom-endpoint setup with screenshots * [Cursor](/ecosystem/fireconnect/cursor): use Fireworks models in Cursor IDE * [FireRouter](/ecosystem/firerouter/overview): automatic cost routing via `--model firerouter` ## Source FireConnect is open source: [github.com/fw-ai/fireconnect](https://github.com/fw-ai/fireconnect) # WebSearch MCP Source: https://docs.fireworks.ai/ecosystem/fireconnect/websearch-mcp Fireworks-hosted live web search for coding harnesses via HTTP MCP WebSearch MCP provides live internet search through Fireworks. It works from **any harness that supports HTTP MCP** once you add the server URL and authenticate with a Fireworks API key. This is separate from the [Fireworks Docs MCP](/ecosystem/integrations/development-setup), which searches Fireworks documentation only. ## Access Web search MCP is not enabled on every account. [Contact the Fireworks team](https://fireworks.ai/contact) to request access, then use a standard [Fireworks API key](https://app.fireworks.ai/settings/users/api-keys) (`fw_...`) as the bearer token below. ### Check eligibility There is no self-serve toggle in the Fireworks dashboard yet. After access is granted: | Method | Eligible | Not eligible | | -------------------------------------- | ----------------------------------------------------- | ---------------------------------------------- | | Connect the MCP server in your harness | Server connects; search tools respond | Auth or connection errors | | `fireconnect claude on` | Prints `Web search → fireworks-websearch (installed)` | Skips MCP setup; Fireworks routing still works | If you see auth errors, [contact the Fireworks team](https://fireworks.ai/contact) to confirm web search is enabled on your account. ## MCP endpoint Use this HTTP MCP server in any harness that supports remote MCP: | Field | Value | | -------- | ---------------------------------------------- | | **URL** | `https://mcp.fireworks.ai/work/mcp` | | **Auth** | `Authorization: Bearer YOUR_FIREWORKS_API_KEY` | Example JSON (exact file and shape depend on your harness): ```json theme={null} { "mcpServers": { "fireworks-websearch": { "type": "http", "url": "https://mcp.fireworks.ai/work/mcp", "headers": { "Authorization": "Bearer YOUR_FIREWORKS_API_KEY" } } } } ``` Replace `YOUR_FIREWORKS_API_KEY` with your Fireworks API key. Wire this into your harness MCP config the same way you would any other HTTP MCP server. ## FireConnect integration FireConnect can install and wire WebSearch MCP automatically. **Today this is integrated for Claude Code only.** OpenCode, Codex, Pi, Cursor, VS Code, and other harnesses are coming soon. For Claude Code with FireConnect: ```bash theme={null} fireconnect claude on ``` For eligible accounts, FireConnect installs `fireworks-websearch`, adds Claude Code-specific `permissions.deny` entries for built-in web tools, and writes a literal Bearer token into the MCP config (refreshed on `fireconnect upgrade` or `fireconnect login`). Look for `Web search → fireworks-websearch (installed)` in the CLI output. On other harnesses, add the [MCP endpoint](#mcp-endpoint) manually until FireConnect support ships. ## Claude Code manual setup Claude Code is the most common path today. You can configure the MCP yourself or use FireConnect above. **Prerequisites** * [Claude Code](https://claude.ai/code) installed * A Fireworks API key with web search access * Claude Code routed through Fireworks ([FireConnect](/ecosystem/fireconnect/claude-code) or [manual settings](/ecosystem/firerouter/claude-code)) ### 1. Add the MCP server Add the [MCP endpoint](#mcp-endpoint) to `~/.claude.json` (merge with any existing `mcpServers` entries). Or add it from the CLI: ```bash theme={null} claude mcp add --transport http fireworks-websearch https://mcp.fireworks.ai/work/mcp \ --header "Authorization: Bearer YOUR_FIREWORKS_API_KEY" ``` ### 2. Deny Claude Code's built-in web tools Claude Code's built-in `WebSearch` and `WebFetch` tools are Anthropic server-side tools. They do not run when inference is routed through Fireworks. Deny them in `~/.claude/settings.json`: ```json theme={null} { "permissions": { "deny": ["WebSearch", "WebFetch"] } } ``` Merge this with your existing `permissions` rules if you already have them. ### 3. Connect in Claude Code 1. Restart Claude Code. 2. Run `/mcp` and connect to `fireworks-websearch`. `fireconnect claude off` removes the FireConnect-managed MCP entry and restores your previous settings. ## See also * [FireConnect overview](/ecosystem/fireconnect/overview) * [Claude Code](/ecosystem/fireconnect/claude-code) # Authentication Source: https://docs.fireworks.ai/ecosystem/firerouter/authentication BYOK headers and API keys for FireRouter Every request is authenticated with a Fireworks API key. Provider credentials sent on individual requests are forwarded only to the selected provider and are not persisted by FireRouter. If workspace BYOK is provisioned on your Fireworks account, Fireworks stores the provider credential in your workspace and supplies it server-side. Contact the Fireworks team to enable workspace BYOK. ## Credentials | Credential | Header or env | When it is needed | | ---------------------------- | -------------------------------------------------- | -------------------------------------------------- | | Fireworks API key (`fw_...`) | `Authorization: Bearer` or `X-Fireworks-Api-Key` | FireRouter auth and redirected Fireworks inference | | Anthropic credential | `x-anthropic-api-key`, or auth sent by Claude Code | To make Claude models eligible | | OpenAI API key (`sk-...`) | `x-openai-api-key` | To make OpenAI models eligible | FireRouter requires a standard Fireworks API key (`fw_...`). Fire Pass keys (`fpk_...`) are not supported. The default `firerouter` model uses **Claude Opus 5** as its primary model. Anthropic credentials make that pass-through leg eligible. Without them, FireRouter removes Claude Opus 5 from the candidate pool and can still serve an eligible Fireworks-hosted model such as GLM 5.3. For a model-specific [FireRouter slug](/ecosystem/firerouter/overview#choose-different-models), each provider-hosted member is eligible only when its credential is available. A request pinned directly to a provider-hosted model fails with `no_credential` when that credential is unavailable. Slugs containing only Fireworks-hosted models need no additional provider key. ## Claude Code with FireConnect When Claude Code is routed through [FireConnect](/ecosystem/fireconnect/claude-code#firerouter), Anthropic auth usually comes from **Claude Code itself**, not a separate FireConnect prompt: | Source | Works for FireRouter pass-through? | | ---------------------------------------------------- | ------------------------------------------------------------------- | | Claude subscription login | Yes | | Browser OAuth (`/login` in Claude Code) | Yes | | `ANTHROPIC_API_KEY` in Claude Code settings or env | Yes | | `--anthropic-api-key` on `fireconnect claude on` | Yes | | `fireconnect configure --anthropic-api-key` | Yes | | Workspace BYOK provisioned on your Fireworks account | Yes (server-side; requires Fireworks team enablement; no local key) | FireConnect does not prompt for Anthropic credentials during Claude Code setup. Claude Code attaches its existing Anthropic login at request time. For direct HTTP calls, send `x-anthropic-api-key` when you want Claude models to be eligible; omit it to route only among eligible Fireworks-hosted members. ## Fireworks key header Send your Fireworks API key with either header: ```text theme={null} -H "Authorization: Bearer $FIREWORKS_API_KEY" # or -H "X-Fireworks-Api-Key: $FIREWORKS_API_KEY" ``` ## Anthropic provider key The canonical header for Anthropic pass-through is: ```text theme={null} -H "x-anthropic-api-key: $ANTHROPIC_API_KEY" ``` `x-api-key` and `Authorization: Bearer` are also accepted as Anthropic credentials. If either carries the Anthropic credential, send the Fireworks key separately as `X-Fireworks-Api-Key`; one `Authorization` header cannot carry both credentials. New integrations should prefer `x-anthropic-api-key`. Example: ```bash theme={null} curl https://api.fireworks.ai/inference/v1/chat/completions \ -H "Authorization: Bearer $FIREWORKS_API_KEY" \ -H "x-anthropic-api-key: $ANTHROPIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"firerouter","messages":[{"role":"user","content":"Say pong."}]}' ``` ## OpenAI provider key When the selected FireRouter slug includes an OpenAI model, send your OpenAI API key as: ```text theme={null} -H "x-openai-api-key: $OPENAI_API_KEY" ``` Do not put the OpenAI provider key in the OpenAI client's `api_key` field. That field supplies the `Authorization` header used to authenticate to the Fireworks gateway, so it must contain your Fireworks API key. Pass the OpenAI provider key as a custom header: ```python theme={null} import os from openai import OpenAI client = OpenAI( api_key=os.environ["FIREWORKS_API_KEY"], base_url="https://api.fireworks.ai/inference/v1", default_headers={"x-openai-api-key": os.environ["OPENAI_API_KEY"]}, ) ``` ## Common errors | Response | Cause | Fix | | ------------------------------------------------ | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `401` with `You must provide an API key` | Fireworks key header missing or empty | Send `Authorization: Bearer $FIREWORKS_API_KEY` or `X-Fireworks-Api-Key` | | `401` with `The API key you provided is invalid` | Gateway rejected the key | Confirm a valid `fw_...` key in the [dashboard](https://app.fireworks.ai/settings/users/api-keys) | | `403` with Fire Pass authorization error | A Fire Pass key (`fpk_...`) was used | Use a standard Fireworks API key (`fw_...`) | | `403` with data residency error | Data residency is enabled on the Fireworks account | Use a residency-compatible pinned serverless model | | `404` with `Model id not found` | Unknown model ID, FireRouter access denial, or model entitlement denial | Confirm the model ID and account access; contact Fireworks if you expect access | | `400` with `no_credential` | A pinned provider model or preference `1` requires an unavailable provider credential | Send the provider credential, choose a route with another eligible member, or use preference `2`–`5` | | Provider `401` | Provider key is invalid | Check the key sent as `x-anthropic-api-key` or `x-openai-api-key` | ## Related * [Quickstart](/ecosystem/firerouter/quickstart): API call examples * [Claude Code (manual setup)](/ecosystem/firerouter/claude-code): `settings.json` setup * [Overview](/ecosystem/firerouter/overview): routing model and model ID # Claude Code (manual setup) Source: https://docs.fireworks.ai/ecosystem/firerouter/claude-code Configure FireRouter in Claude Code by editing settings.json **Prefer FireConnect.** Use `--model firerouter` for Main, a slot flag such as `--opus firerouter` for one alias, or `--interactive` to choose aliases. See [Claude Code — FireRouter](/ecosystem/fireconnect/claude-code#choose-where-firerouter-is-used). This page is only for manual `~/.claude/settings.json` setup when you cannot use FireConnect. ## Prerequisites * [Claude Code](https://claude.ai/code) installed * A [Fireworks API key](https://app.fireworks.ai/settings/users/api-keys) (`fw_...`) * Optional Anthropic credentials to make Claude Opus 5 eligible — usually your existing Claude Code login (subscription, OAuth, or API key). Without them, FireRouter can still use eligible Fireworks-hosted models. See [Authentication](/ecosystem/firerouter/authentication#claude-code-with-fireconnect). Merge the `env` keys from one configuration below into your existing `~/.claude/settings.json` (on Windows: `%USERPROFILE%\.claude\settings.json`). Do not replace unrelated settings. Then restart Claude Code. ## With a Claude subscription You do not need to add an Anthropic token to this file. Use `ANTHROPIC_CUSTOM_HEADERS` to pass your Fireworks API key. Claude Code sends your existing login with each request. **Route Main through FireRouter without adding or changing other alias pins.** All Claude Code requests still use the Fireworks base URL: ```json theme={null} { "env": { "ANTHROPIC_BASE_URL": "https://api.fireworks.ai/inference", "ANTHROPIC_MODEL": "firerouter[1m]", "ANTHROPIC_CUSTOM_HEADERS": "x-fireworks-api-key: YOUR_FIREWORKS_API_KEY" } } ``` **Route the Opus alias through FireRouter.** Select Opus from `/model`; this does not add or change other alias pins, and all requests still use the Fireworks base URL: ```json theme={null} { "env": { "ANTHROPIC_BASE_URL": "https://api.fireworks.ai/inference", "ANTHROPIC_DEFAULT_OPUS_MODEL": "firerouter[1m]", "ANTHROPIC_CUSTOM_HEADERS": "x-fireworks-api-key: YOUR_FIREWORKS_API_KEY" } } ``` ## With an Anthropic API key Add `ANTHROPIC_API_KEY` to make Claude Opus 5 eligible. You still need `ANTHROPIC_CUSTOM_HEADERS` for your Fireworks API key. This example routes Main through FireRouter without adding or changing other alias pins: ```json theme={null} { "env": { "ANTHROPIC_BASE_URL": "https://api.fireworks.ai/inference", "ANTHROPIC_MODEL": "firerouter[1m]", "ANTHROPIC_CUSTOM_HEADERS": "x-fireworks-api-key: YOUR_FIREWORKS_API_KEY", "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY" } } ``` # LiteLLM Source: https://docs.fireworks.ai/ecosystem/firerouter/litellm Add FireRouter to a LiteLLM Proxy deployment Add FireRouter to an existing [LiteLLM Proxy](/ecosystem/integrations/litellm) deployment so developers request one model instead of choosing between open and closed-source models on every call. Your Fireworks API key authenticates FireRouter and pays for Fireworks-hosted calls. An Anthropic credential makes Claude Opus 5 eligible and pays for that provider's calls. Provider keys sent on individual requests are not persisted by FireRouter. See [Authentication](/ecosystem/firerouter/authentication). ## Prerequisites * A running LiteLLM Proxy on **v1.98.0** configured for Fireworks (see [LiteLLM integration](/ecosystem/integrations/litellm)) * A [Fireworks API key](https://app.fireworks.ai/settings/users/api-keys) (`fw_...`) * Optional: an **Anthropic API key** (`sk-ant-...`) to make Claude Opus 5 eligible for the default `firerouter` slug. It is not needed for a Fireworks-only slug or when workspace BYOK is provisioned. ## Add FireRouter to `config.yaml` ```yaml theme={null} model_list: - model_name: accounts/fireworks/routers/firerouter litellm_params: model: fireworks_ai/accounts/fireworks/routers/firerouter api_key: os.environ/FIREWORKS_AI_API_KEY extra_headers: x-anthropic-api-key: os.environ/ANTHROPIC_API_KEY ``` Use a router-qualified ID in `litellm_params.model`, such as `fireworks_ai/routers/firerouter` or the full `fireworks_ai/accounts/fireworks/routers/firerouter` shown above. Do not use bare `fireworks_ai/firerouter`, which LiteLLM interprets as a model rather than a router. Set `ANTHROPIC_API_KEY` on the LiteLLM server when you want pass-through requests to include `x-anthropic-api-key` automatically. Developers do not need to send the Anthropic key on each request when it is configured here. Omit `extra_headers` for Fireworks-only routing or workspace BYOK. A server-side Anthropic key is shared across all callers of that proxy deployment. If each developer should bring their own Anthropic key, omit `extra_headers` and have clients send `x-anthropic-api-key` on each request instead (see below). For server-managed Anthropic credentials, start or restart the proxy with both keys exported: ```bash theme={null} export FIREWORKS_AI_API_KEY="fw_..." export ANTHROPIC_API_KEY="sk-ant-..." litellm --config config.yaml ``` ## Call FireRouter If LiteLLM virtual keys are configured, clients authenticate to LiteLLM with a virtual key: ```bash theme={null} curl http://localhost:4000/chat/completions \ -H "Authorization: Bearer $LITELLM_VIRTUAL_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "accounts/fireworks/routers/firerouter", "messages": [{"role": "user", "content": "Say pong in one word."}] }' ``` Optional routing preference: ```yaml theme={null} litellm_settings: model_group_settings: forward_client_headers_to_llm_api: - accounts/fireworks/routers/firerouter ``` ```text theme={null} -H "x-routing-preference: 4" ``` See [Routing preferences](/ecosystem/firerouter/routing-preferences) for values `1`–`5`. ## Per-developer Anthropic keys If each caller should use their own Anthropic key, omit `extra_headers` from the model config, enable the header-forwarding configuration above, and have clients send the header on every request: ```bash theme={null} curl http://localhost:4000/chat/completions \ -H "Authorization: Bearer $LITELLM_VIRTUAL_KEY" \ -H "x-anthropic-api-key: $ANTHROPIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "accounts/fireworks/routers/firerouter", "messages": [{"role": "user", "content": "Say pong in one word."}] }' ``` See [client header forwarding](https://docs.litellm.ai/docs/proxy/forward_client_headers) for configuration details. ## API key layout | Key | Who holds it | Used for | | ----------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------- | | Fireworks API key (`fw_...`) | LiteLLM server | FireRouter auth and redirected inference | | LiteLLM virtual key (if configured) | Each developer or service | Proxy authentication and spend tracking | | Anthropic API key (`sk-ant-...`) | Optional: LiteLLM server (`extra_headers`) or each caller (request header) | Makes Claude models eligible and pays for Claude pass-through | ## Related * [LiteLLM integration](/ecosystem/integrations/litellm): configure Fireworks models in LiteLLM Proxy * [Quickstart](/ecosystem/firerouter/quickstart): direct API call examples * [Authentication](/ecosystem/firerouter/authentication): header reference * [Routing preferences](/ecosystem/firerouter/routing-preferences): tune cost vs. quality # Overview Source: https://docs.fireworks.ai/ecosystem/firerouter/overview Route LLM requests between closed-source and open models with FireRouter FireRouter is a managed routing service for supported text-generation workloads. Request a FireRouter virtual model through the [Fireworks inference API](/tools-sdks/openai-compatibility), and FireRouter selects an eligible backend according to the configured route. By default, it routes between a Fireworks open model and a closed-source model. The goal is to reduce cost on simpler requests while retaining access to a closed-source model for harder ones. ## When to use FireRouter Use FireRouter when you want **automatic cost optimization** without picking a different model per request: * You want closed-source quality (for example Claude Opus) on hard prompts but do not need it on every call. * Many of your requests are straightforward (summaries, formatting, simple Q\&A) and can be served by a Fireworks open model. * You want to select the models available to the router without choosing a target for every request. * For the default configuration, Anthropic credentials make Claude Opus 5 eligible. Without them, FireRouter can still use eligible Fireworks-hosted models. Direct API clients send `x-anthropic-api-key`; Claude Code can send its existing login on each request. ## How it works During ranked decisions, the default `firerouter` configuration compares two paths: | Path | When | What runs | Billing | | ---------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------ | --------------------------------- | | **Redirect** | More likely when the open model's predicted success and cost produce the better value | A Fireworks open model (by default GLM 5.3) | Your Fireworks API key | | **Pass-through** | More likely when the closed-source model's predicted success justifies its cost | A closed-source model (by default Claude Opus 5) | Your provider API key (Anthropic) | FireRouter uses a bring-your-own-key (BYOK) model: * Your **Fireworks API key** authenticates to FireRouter and pays for calls to Fireworks models. * A third-party **provider API key** pays for calls to that provider's models. Provider keys sent on individual requests are not persisted by FireRouter. If workspace BYOK is provisioned on your Fireworks account, Fireworks stores the credential in your workspace and supplies it server-side. Contact the Fireworks team to enable workspace BYOK. ## FireConnect The easiest way to use FireRouter in coding harnesses is [FireConnect](/ecosystem/fireconnect/overview). As of FireConnect **v0.9.0**, select FireRouter like any other model. **Claude Code.** Use `--model firerouter` for Main or a slot flag such as `--opus firerouter` for one alias. Use `--interactive` to choose alias slots, and use `native` to leave a slot unpinned. On first setup, specify every slot you want to control. See [Claude Code — FireRouter](/ecosystem/fireconnect/claude-code#firerouter). ```bash theme={null} fireconnect login fireconnect claude on --model firerouter ``` **Other harnesses:** ```bash theme={null} fireconnect opencode on --model firerouter ``` See [FireConnect Models](/ecosystem/fireconnect/models) for how `firerouter` fits next to other short IDs, and [Harness support](/ecosystem/fireconnect/overview#harness-support) for which harnesses support FireRouter. Per-harness details (Claude slot flags, Codex Anthropic env, routing preference) live on each harness page. Upgrade FireConnect before enabling FireRouter on an older install. See [Upgrade FireConnect](/ecosystem/fireconnect/overview#upgrade-fireconnect). ### Anthropic credentials with FireConnect The default `firerouter` needs Anthropic credentials to make **Claude Opus 5** eligible. With **Claude Code**, you usually do not add a new key: Claude Code sends its subscription login, browser OAuth token, or configured `ANTHROPIC_API_KEY` with each request. You can also pass `--anthropic-api-key sk-ant-...` on `on`, store one with `fireconnect configure --anthropic-api-key sk-ant-...`, or use workspace BYOK provisioned by the Fireworks team. Direct API clients send `x-anthropic-api-key` to enable Claude pass-through. Without Anthropic credentials, the default router can still serve eligible Fireworks-hosted models. See [Authentication](/ecosystem/firerouter/authentication). Cursor and DeepSeek Harness need workspace BYOK for Anthropic pass-through because they cannot attach a local Anthropic key. ### See which model served a request After assistant messages run, FireConnect's Claude Code **status line** lists backend models that served the session — for example `Claude Opus 5` or `GLM 5.3`. Before a billed response, it may show `FireRouter` rather than a resolved backend. ## Endpoint FireRouter is available through the Fireworks inference API: ```text theme={null} https://api.fireworks.ai/inference/v1 ``` Common API paths: | Wire format | Path | | ------------------ | -------------------------------------------------------- | | Chat Completions | `https://api.fireworks.ai/inference/v1/chat/completions` | | Completions | `https://api.fireworks.ai/inference/v1/completions` | | OpenAI Responses | `https://api.fireworks.ai/inference/v1/responses` | | Anthropic Messages | `https://api.fireworks.ai/inference/v1/messages` | ### Availability limitations * FireRouter requires a standard Fireworks API key (`fw_...`); Fire Pass keys (`fpk_...`) are not supported. * FireRouter is not available for Fireworks accounts with data residency enabled. Requests return `403`; use a residency-compatible pinned serverless model. * Microsoft Foundry Responses requests are not supported through FireRouter. ## Model ID FireRouter is a first-party model on the Fireworks provider. Use `firerouter` in the `model` field: ```text theme={null} firerouter ``` These longer forms are also accepted: ```text theme={null} fireworks/firerouter accounts/fireworks/routers/firerouter ``` For [LiteLLM](/ecosystem/firerouter/litellm), use the full router path in `litellm_params.model`. For ranked decisions, FireRouter compares eligible models using predicted success and cost. The model ID selects the configured route. Use `firerouter` or a `firerouter/...` slug when you want automatic routing. A bare model ID such as `claude-opus-5` or `gpt-5.6-sol` is treated as a pin and is not ranked against route members. Normal same-model retry and configured deployment-fallback behavior may still apply. ### Current routing pair The short `firerouter` model ID currently routes between: | Role | Model | | ---------------------------- | ----------------------------------- | | Pass-through (closed-source) | **Claude Opus 5** (`claude-opus-5`) | | Redirect (open) | **GLM 5.3** (`glm-5p3`) | These models are subject to change as FireRouter is updated. This page reflects the current configuration. Because the default pass-through target is Claude Opus 5, supply Anthropic credentials to use that path. With FireConnect + Claude Code, your existing Claude login is usually enough. Direct API callers send `x-anthropic-api-key`. See [Authentication](/ecosystem/firerouter/authentication). The response can name a different Fireworks-hosted model when a configured member is ineligible for the request or a provider attempt needs an operational fallback. The pair above describes the default ranked choices, not the fallback chain. ### Choose different models Use a slash-delimited FireRouter slug to change the models available to the router. The first model is the primary; the remaining models are alternatives considered during ranked decisions. Each member must be an exact deployed model ID or a unique model alias. Examples: | Model ID | Models | | -------------------------------------------------------- | --------------------------------------------------- | | `firerouter/kimi-k3/glm-5p2-fast` | Kimi K3 and GLM 5.2 Fast | | `firerouter/kimi-k3/deepseek-v4-flash-0731` | Kimi K3 and DeepSeek V4 Flash (0731) | | `firerouter/kimi-k3/glm-5p2-fast/deepseek-v4-flash-0731` | Kimi K3, GLM 5.2 Fast, and DeepSeek V4 Flash (0731) | | `firerouter/claude-opus-5/kimi-k3/glm-5p2-fast` | Claude Opus 5, Kimi K3, and GLM 5.2 Fast | | `firerouter/gpt-5.6-sol/glm-5p2-fast` | GPT 5.6 Sol and GLM 5.2 Fast | Set the selected slug in the `model` field just as you would use `firerouter`. The slug defines the route's candidate set. Each provider-hosted member is eligible only when its credential is available. A missing credential removes that member from the candidate pool; eligible Fireworks-hosted members can still serve the request. A slug containing only Fireworks-hosted models needs only the Fireworks API key. Use `x-anthropic-api-key` for Claude models and `x-openai-api-key` for OpenAI models. See [Authentication](/ecosystem/firerouter/authentication). ## Client integrations | Integration | When to use | | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [FireConnect](/ecosystem/fireconnect/overview) | One-command setup for coding harnesses (recommended). Use `--model firerouter` on single-model harnesses; on Claude Code, see [slot mapping behavior](/ecosystem/fireconnect/claude-code#firerouter). | | [Quickstart](/ecosystem/firerouter/quickstart) | Direct HTTP calls (curl, OpenAI SDK, any OpenAI-compatible client) | | [Claude Code (manual setup)](/ecosystem/firerouter/claude-code) | Manual `settings.json` setup without FireConnect | | [LiteLLM](/ecosystem/firerouter/litellm) | Add FireRouter to a LiteLLM Proxy deployment | ## What FireRouter is not * **Not a deployment router.** FireRouter is different from [deployment routers](/deployments/routers), which load-balance traffic across your own Fireworks deployments. ## Next steps Enable FireRouter with one command Make your first API call Edit settings.json for FireRouter in Claude Code BYOK headers and API key requirements Tune cost vs. quality with `x-routing-preference` Add FireRouter to LiteLLM Proxy # Quickstart Source: https://docs.fireworks.ai/ecosystem/firerouter/quickstart Make your first FireRouter API call This guide shows how to call FireRouter directly through the Fireworks inference API. See the [overview](/ecosystem/firerouter/overview) for how routing works and the [authentication](/ecosystem/firerouter/authentication) page for header details. For coding harnesses, use [FireConnect](/ecosystem/fireconnect/overview): `fireconnect on --model firerouter`. Claude Code supports Main plus named aliases; see [Claude Code — FireRouter](/ecosystem/fireconnect/claude-code#choose-where-firerouter-is-used) to configure each slot explicitly. For manual `settings.json` setup, see [Claude Code (manual setup)](/ecosystem/firerouter/claude-code). ## Prerequisites * A [Fireworks API key](https://app.fireworks.ai/settings/users/api-keys) (`fw_...`) * Optional **Anthropic credentials** to make Claude Opus 5 eligible — an API key (`sk-ant-...`) for direct HTTP calls, or your existing Claude Code login when using [FireConnect](/ecosystem/fireconnect/claude-code#firerouter). Without them, FireRouter can still use eligible Fireworks-hosted models. Fire Pass keys (`fpk_...`) and accounts with data residency enabled cannot use FireRouter. See [Availability limitations](/ecosystem/firerouter/overview#availability-limitations). ## Chat Completions Send a request to the [Chat Completions](/tools-sdks/openai-compatibility) endpoint with the FireRouter model ID: ```bash theme={null} curl https://api.fireworks.ai/inference/v1/chat/completions \ -H "Authorization: Bearer $FIREWORKS_API_KEY" \ -H "x-anthropic-api-key: $ANTHROPIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "firerouter", "messages": [{"role": "user", "content": "Say pong in one word."}] }' ``` With the default `firerouter` model ID, simple prompts are more likely to use GLM 5.3 (`glm-5p3`) on Fireworks. Harder prompts are more likely to use Claude Opus 5 (`claude-opus-5`) when Anthropic credentials are available. Routing is policy-driven; prompt difficulty alone does not guarantee either result for an individual request. To use a different model combination, replace `firerouter` with one of the [model-specific FireRouter slugs](/ecosystem/firerouter/overview#choose-different-models). If the selected slug includes an OpenAI model, send its key as `-H "x-openai-api-key: $OPENAI_API_KEY"`. See [Authentication](/ecosystem/firerouter/authentication). ## Anthropic Messages For clients that speak the Anthropic Messages API: ```bash theme={null} curl https://api.fireworks.ai/inference/v1/messages \ -H "Authorization: Bearer $FIREWORKS_API_KEY" \ -H "x-anthropic-api-key: $ANTHROPIC_API_KEY" \ -H "Content-Type: application/json" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "firerouter", "max_tokens": 1024, "messages": [{"role": "user", "content": "Say pong in one word."}] }' ``` ## Observe routing Send both a simple prompt and a harder reasoning prompt, then inspect the `model` field in each response. It names the backend that served the request (for example `glm-5p3` or `claude-opus-5`), not `firerouter`. Simple prompts are more likely to use the Fireworks model and harder prompts are more likely to use the primary model, but neither result is guaranteed for an individual request. Use `x-routing-preference` to bias the decision. See [Routing preferences](/ecosystem/firerouter/routing-preferences). You can also send the Fireworks key as `X-Fireworks-Api-Key` instead of `Authorization: Bearer`. See [Authentication](/ecosystem/firerouter/authentication) for the full header reference. ## Related * [Overview](/ecosystem/firerouter/overview): model ID and routing pair * [Authentication](/ecosystem/firerouter/authentication): header reference * [Routing preferences](/ecosystem/firerouter/routing-preferences): tune cost vs. quality * [LiteLLM](/ecosystem/firerouter/litellm): add FireRouter to LiteLLM Proxy * [Claude Code (manual setup)](/ecosystem/firerouter/claude-code): edit `settings.json` directly # Routing preferences Source: https://docs.fireworks.ai/ecosystem/firerouter/routing-preferences Tune FireRouter between closed-source quality and open-model savings FireRouter routes each new user turn sent to `firerouter` to either a closed-source model (pass-through) or a Fireworks open model (redirect). The **`x-routing-preference`** request header controls the quality-versus-cost tradeoff. Set the preference per request with the HTTP header below, or pass `--routing-preference` when you run `fireconnect on`. ## Preference levels Send an integer from **1** (most quality-protective) to **5** (most savings-focused): | Value | Name | Behavior | | ----- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `1` | `max-intelligence` | For ranked routes, force the route's primary with no cross-model fallback. Retryable failures may receive one same-model retry | | `2` | `more-intelligence` | Increase intelligence weighting relative to balanced | | `3` | `balanced` | Default when the header is omitted. FireRouter's standard tradeoff | | `4` | `more-savings` | Increase cost weighting relative to balanced | | `5` | `max-savings` | For ranked routes, rank eligible models by cost | In-order routes keep their configured model order instead of using this ranking. ## HTTP header Set the header on each request: ```text theme={null} -H "x-routing-preference: 4" ``` The HTTP header accepts only the integers `1`–`5`. Names such as `balanced` are FireConnect CLI values, not HTTP header values. Example with curl: ```bash theme={null} curl https://api.fireworks.ai/inference/v1/chat/completions \ -H "Authorization: Bearer $FIREWORKS_API_KEY" \ -H "x-anthropic-api-key: $ANTHROPIC_API_KEY" \ -H "x-routing-preference: 4" \ -H "Content-Type: application/json" \ -d '{ "model": "firerouter", "messages": [{"role": "user", "content": "Add a docstring to this function."}] }' ``` If the header is missing, invalid, or out of range, FireRouter uses the balanced default (`3`). ## FireConnect When you enable FireRouter through FireConnect, pass `--routing-preference` on `on` instead of setting a header yourself: ```bash theme={null} fireconnect claude on --model firerouter --routing-preference 4 fireconnect opencode on --model firerouter --routing-preference 2 fireconnect pi on --model firerouter --routing-preference 5 ``` On Claude Code, `--routing-preference` requires at least one slot set to `firerouter`. See [Choose where FireRouter is used](/ecosystem/fireconnect/claude-code#choose-where-firerouter-is-used). Supported on Claude Code, OpenCode, Pi, and VS Code. Values are `1`–`5` or the level names (`max-intelligence`, `balanced`, `max-savings`, etc.). The flag applies when at least one configured slot uses `firerouter`. Codex, Cursor, and DeepSeek Harness do not support `--routing-preference`. You can also store a global Anthropic BYOK key once: ```bash theme={null} fireconnect configure --anthropic-api-key sk-ant-... ``` ## When to adjust * **High-volume workloads with many simple requests**: try `4` or `5` to redirect summaries, formatting, and straightforward Q\&A. * **Tasks where quality is critical** (security review, complex reasoning, nuanced writing): try `1` or `2` to keep closed-source models on harder prompts. * **Evaluating routing**: start at `3` (balanced), then move one step at a time and compare cost and output quality. For eligible tool-call continuations, modes `2`–`4` may reuse the model selected for the same user turn when route caching is available. Modes `1` and `5` do not use this route cache. ## Related * [Overview](/ecosystem/firerouter/overview): how redirect vs. pass-through works * [FireConnect overview](/ecosystem/fireconnect/overview#firerouter-and-smart-routers): enable FireRouter in coding harnesses * [Quickstart](/ecosystem/firerouter/quickstart): API call examples * [LiteLLM](/ecosystem/firerouter/litellm): add FireRouter to LiteLLM Proxy # Agent Frameworks Source: https://docs.fireworks.ai/ecosystem/integrations/agent-frameworks Build production-ready AI agents with Fireworks and leading open-source frameworks Fireworks AI seamlessly integrates with the best open-source agent frameworks, enabling you to build magical, production-ready applications powered by state-of-the-art language models. ## Supported Frameworks Build LLM applications with powerful orchestration and tool integration Efficient data retrieval and document indexing for LLM-based agents Orchestrate collaborative multi-agent systems for complex tasks Type-safe AI agent development with Pydantic validation Modern agent orchestration with seamless OpenAI-compatible integration Build and deploy production AI agents with Fireworks models on AgentCore Runtime ## Need Help? For assistance with agent framework integrations, [contact our team](https://fireworks.ai/contact) or join our [Discord community](https://discord.gg/fireworks-ai). # Microsoft Foundry Source: https://docs.fireworks.ai/ecosystem/integrations/azure-foundry Deploy frontier open models inside your Azure subscription, billed through Azure. Fireworks AI is a first-party inference provider inside Microsoft Foundry. You can access frontier open models through your existing Azure account, with usage billed through Azure and counting toward your Microsoft Azure Consumption Commitment (MACC). This page covers the Fireworks side of the integration. For Azure portal setup steps, see the [Microsoft Learn guide](https://learn.microsoft.com/en-us/azure/foundry/how-to/fireworks/enable-fireworks-models). **New to Fireworks?** Foundry users get the same OpenAI-compatible API and model catalog as direct Fireworks customers. Start with the [PayGo quickstart](#paygo-quickstart) below. You can be making requests in about 10 minutes. ## Prerequisites * An active Azure subscription * The Fireworks integration enabled at the subscription level (see below) * A Microsoft Foundry project with the **Azure AI Developer** role assigned ### Opt-in Fireworks on Foundry requires a one-time opt-in per Azure subscription before you can create deployments. Follow the steps in the [Microsoft Learn guide](https://learn.microsoft.com/en-us/azure/foundry/how-to/fireworks/enable-fireworks-models#enable-fireworks-on-foundry). ## Deployment modes Fireworks on Foundry supports three deployment modes. | Mode | Also called | Pricing | Regions | Right for | | ----------------- | ------------------------------ | --------------------------------- | -------------------- | -------------------------------------------- | | **PayGo** | Serverless, Data Zone Standard | Per token, MACC-eligible | US Data Zone only | Prototyping, low-volume workloads | | **PTU** | Provisioned Throughput | Per PTU-hour, ACD + MACC eligible | Global | Production workloads with consistent traffic | | **Custom Models** | Bring Your Own Model | PTU pricing | Global (PTU regions) | Trained model deployment | PTU deployments can be created directly in the Azure portal. For help with PTU sizing on Fireworks models, contact [sales@fireworks.ai](mailto:sales@fireworks.ai). ## Available models All models use the OpenAI-compatible chat completions API and are added to the catalog on a rolling basis. For the current list of available models, see the [Microsoft Learn catalog](https://learn.microsoft.com/en-us/azure/foundry/how-to/fireworks/enable-fireworks-models#available-catalog-models). Chat completions only. Embeddings, image generation, and audio modalities are not available through Foundry. ## PayGo quickstart PayGo (Data Zone Standard) is available in: East US, East US 2, Central US, North Central US, West US, West US 3. The throughput limit for PayGo deployments is **500,000 tokens per minute (TPM)**. For higher limits, submit a limit increase request on [aka.ms/fireworks-quota](https://aka.ms/fireworks-quota) and contact [sales@fireworks.ai](mailto:sales@fireworks.ai). ### Make your first request Foundry deployments use an OpenAI-compatible endpoint. Use your Foundry project endpoint and Azure API key. ```python theme={null} from openai import OpenAI client = OpenAI( base_url="https://.services.ai.azure.com/models", api_key="", ) response = client.chat.completions.create( model="fireworks-ai/FW-GLM-5.2", messages=[{"role": "user", "content": "Hello"}], ) print(response.choices[0].message.content) ``` Find your project endpoint in the Microsoft Foundry portal under **Project settings**. ## PTU (Provisioned Throughput) PTU deployments provide dedicated GPU capacity reserved for your workload, with consistent throughput and global region availability. * Dedicated capacity, not shared with other tenants * Available globally, not limited to US Data Zone * ACD-eligible and MACC-eligible You can create a PTU deployment directly in the Azure portal. For more on provisioned throughput, see the [Microsoft Learn guide](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/concepts/provisioned-throughput). For help with PTU sizing on Fireworks models, contact [sales@fireworks.ai](mailto:sales@fireworks.ai). ## Custom Models Train on Fireworks and deploy on Foundry, or bring your own weights from wherever you post-train to deploy on Foundry. Your model is served on Fireworks infrastructure within Azure, billed through your Azure account. ### Supported base architectures For the list of supported custom model architectures, see the [Microsoft Learn guide](https://learn.microsoft.com/en-us/azure/foundry/how-to/fireworks/enable-fireworks-models#supported-model-architectures). ### Deployment To import and deploy a custom model, follow the [Import custom models into Foundry guide](https://learn.microsoft.com/en-us/azure/foundry/how-to/fireworks/import-custom-models?tabs=rest-api). ## Billing All Fireworks on Foundry usage is billed through Azure. You do not need a separate Fireworks billing account or contract. * PayGo and PTU usage is MACC-eligible * PTU deployments are ACD-eligible and qualify for quota retirement * Direct Fireworks usage at [fireworks.ai](https://fireworks.ai) is billed separately and does not count toward MACC ## Troubleshooting | Issue | Resolution | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Quota exceeded error | Request a limit increase at [aka.ms/fireworks-quota](https://aka.ms/fireworks-quota) | | Access denied on deployment | Verify you have the **Azure AI Developer** role on the project | | Opt-in not propagating | Allow up to 30 minutes after registering `Fireworks.EnableDeploy` | | Custom Model deployment failing | Confirm weights are full-weight (not LoRA adapters) and the architecture is in the [supported list](https://learn.microsoft.com/en-us/azure/foundry/how-to/fireworks/enable-fireworks-models#supported-model-architectures) | | PTU provisioning questions | Contact [sales@fireworks.ai](mailto:sales@fireworks.ai) | ## FireConnect Use FireConnect to route local coding harnesses through your Foundry deployments without hand-editing config files. Configure `--provider azure`, then run `fireconnect opencode on`, `fireconnect codex on`, `fireconnect cursor on`, `fireconnect vscode on`, or `fireconnect pi on --model FW-GLM-5.2` FireConnect implements Azure routing for **OpenCode**, **Codex**, **Pi**, **Cursor**, and **VS Code** in v0.9.0+. **Claude Code** and **DeepSeek Harness** do not. Running `fireconnect claude on` or `fireconnect deepseek on` always wires direct Fireworks, regardless of global `--provider azure`. ```bash theme={null} export AZURE_API_KEY= fireconnect configure \ --provider azure \ --base-url https://.services.ai.azure.com \ --api-key $AZURE_API_KEY fireconnect opencode on --model FW-GLM-5.2 ``` See [FireConnect + Microsoft Foundry](/ecosystem/fireconnect/microsoft-foundry) for Foundry models, per-harness config details, one-off `--azure` routing, [turning Foundry off](/ecosystem/fireconnect/microsoft-foundry#turn-off-foundry-routing), and switching back to direct Fireworks. ## Additional resources * [Enable Fireworks on Foundry (Microsoft Learn)](https://learn.microsoft.com/en-us/azure/foundry/how-to/fireworks/enable-fireworks-models) * [Microsoft Foundry portal](https://ai.azure.com/) * [Fireworks training docs](/fine-tuning/finetuning-intro) * [Fireworks Trust Center](https://fireworks.ai/trust) * [sales@fireworks.ai](mailto:sales@fireworks.ai) for PTU provisioning and Custom Model support # How Setup Works Source: https://docs.fireworks.ai/ecosystem/integrations/byoc/how-setup-works Understand the high-level onboarding flow for Bring Your Own Cluster. This page describes the high-level setup flow for Enterprise customers onboarding to Bring Your Own Cluster (BYOC). Bring Your Own Cluster is in Private Preview for Enterprise customers. Contact [sales@fireworks.ai](mailto:sales@fireworks.ai) to participate in the preview and confirm the onboarding path for your environment. ## Prerequisites Before installation, Fireworks works with your team to confirm that the target environment can support BYOC. At a high level, you need: * A Kubernetes cluster with NVIDIA GPU nodes * Network configuration that allows Fireworks to manage the cluster * A customer-approved endpoint and DNS plan * An administrative credential for the setup phase Fireworks supports BYOC on major cloud providers and their managed Kubernetes offerings, select GPU cloud providers, and on-premises environments that provide a reachable Kubernetes endpoint, supported NVIDIA GPU nodes, and the required network setup. Fireworks confirms provider, environment, GPU capacity, and networking support during preview onboarding. Training is not supported in BYOC during Private Preview. ## Setup flow Your team provisions the Kubernetes cluster with NVIDIA GPU nodes, or provisions it jointly with Fireworks during onboarding. You retain ownership of the cloud account or data center environment, cluster, GPU nodes, and networking. You grant Fireworks an administrative credential to the cluster for setup. Fireworks recommends a dedicated, clearly named, revocable credential so your team can audit and manage access through your normal governance process. Fireworks installs the serving stack using managed deployment tooling such as Helm or GitOps. During installation, Fireworks creates scoped-down Kubernetes identities and roles for the components that run in the cluster. Fireworks works with your team to configure networking and DNS so your customer endpoint is reachable through the Fireworks API experience while inference request and response handling runs in your environment. Fireworks validates the cluster, then deploys inference workloads into the environment. After validation, your applications use the same Fireworks APIs and SDKs used across the rest of the platform. ## Access model during setup Installation requires an administrative Kubernetes credential because the platform must create cluster-scoped resources, namespaces, standard dependency resources, and node-level scheduling configuration. This is a Kubernetes permission requirement for installing and operating a platform inside a cluster. After installation, day-to-day workloads run under scoped service identities created for each component. ## Validation Before the cluster is used for production traffic, Fireworks validates the environment with your team. Validation typically covers: * GPU node readiness and scheduling behavior * Endpoint reachability * Routing and load balancing behavior * Autoscaling behavior within the available GPU capacity * Observability signals used for ongoing operations ## After onboarding Once validation is complete, Fireworks operates the serving stack and model lifecycle in the cluster. Your team continues to own the cloud account or data center environment, network policy, GPU capacity, and any customer-side approval processes. For ongoing responsibilities, see [Operational Model](/ecosystem/integrations/byoc/operational-model). # Operational Model Source: https://docs.fireworks.ai/ecosystem/integrations/byoc/operational-model Learn how Fireworks operates Bring Your Own Cluster environments day to day. Bring Your Own Cluster (BYOC) is designed so your team keeps ownership of the cloud or hardware environment while Fireworks operates the model serving stack inside it. Bring Your Own Cluster is in Private Preview for Enterprise customers. Contact [sales@fireworks.ai](mailto:sales@fireworks.ai) to participate in the preview and confirm operational support terms for your deployment. ## Responsibilities In steady state, your team owns the cloud account or data center environment, Kubernetes cluster, GPU nodes, networking, and customer-side governance. Fireworks owns the serving software stack, model deployment lifecycle, scaling behavior, performance optimization, observability, upgrades, and operational support for the Fireworks-managed components. ## Shared responsibility model BYOC is a shared operational model. | Area | Customer owns | Fireworks owns | | ---------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | Cloud / hardware environment | Cloud account or data center environment, Kubernetes cluster, GPU nodes, and networking | Guidance during onboarding and validation | | Setup access | A dedicated, clearly named, revocable administrative credential during setup | Installation of the serving stack and creation of scoped runtime identities | | Model serving | Available GPU capacity and required customer-side dependencies | Model deployment lifecycle, routing, autoscaling, performance optimization, and upgrades | | Reliability | Underlying hardware capacity | GPU and node health monitoring, automated remediation workflows, observability, and operational support | ## Model lifecycle Fireworks deploys, updates, and version-manages inference deployments in the cluster. Customers request model or deployment changes through Fireworks, and Fireworks applies those changes through the managed BYOC operating process. Training is not supported in BYOC during Private Preview. ## Autoscaling Serving capacity scales with demand within the GPU capacity available in your cluster. Where appropriate for the workload, Fireworks can scale deployments down when idle and scale them back up when traffic returns. Autoscaling behavior depends on model size, traffic shape, GPU availability, and customer-defined capacity constraints. ## Hybrid capacity For customers who elect a hybrid BYOC model, Fireworks can help coordinate overflow scheduling onto Fireworks-managed capacity for eligible workloads. This is useful when traffic exceeds available BYOC capacity, customer-owned hardware is temporarily constrained, or some workloads do not need to remain in the BYOC environment. Hybrid capacity is configured during onboarding. Fireworks works with your team to define which workloads are eligible, when overflow may be used, how routing is handled, and what data handling or compliance constraints apply. ## GPU fleet reliability Fireworks continuously monitors GPU and node health for the serving stack. When a node or GPU becomes unhealthy, Fireworks automation detects the condition and safely remediates it, such as by removing traffic from the affected node and replacing capacity when available. This minimizes the operational burden on your team while preserving your ownership of the underlying environment and GPU capacity. ## Capacity efficiency Fireworks optimizes placement of workloads across the available GPUs to improve utilization. This includes consolidating compatible workloads where appropriate and balancing efficiency with reliability and performance. ## Observability and incident response Fireworks operates the stack using metrics, logs, and dashboards for the managed serving components. Fireworks monitors the environment, investigates service-impacting issues, and coordinates with your team when an incident requires customer-side action, such as hardware capacity, cloud account or data center, networking, or policy changes. Detailed Enterprise BYOC support terms are coming soon. During Private Preview, Fireworks confirms support channels, escalation paths, and any deployment-specific operational expectations during onboarding. ## Upgrades Fireworks updates the serving stack using managed rolling updates. Keeping the operator credential in place after setup helps Fireworks deploy upgrades, roll out model changes, and respond to incidents without requiring a new approval for every routine operational action. Customers with strict access policies can discuss a hardened onboarding variant with Fireworks, where customer teams pre-create required cluster-scoped access structures. ## Customer coordination BYOC operations work best when Fireworks and the customer agree on: * Approved GPU capacity and scaling boundaries * Whether any workloads are eligible for hybrid overflow onto Fireworks-managed capacity * Customer-side change windows or approval requirements * Contacts for networking, cloud account or data center, and capacity issues * Support and escalation expectations * Any environment-specific compliance requirements # Bring Your Own Cluster Source: https://docs.fireworks.ai/ecosystem/integrations/byoc/overview Run Fireworks inference in your own Kubernetes cluster, cloud account or data center, and network boundary. Bring Your Own Cluster (BYOC) lets Enterprise customers run Fireworks inference inside their own Kubernetes cluster. Your inference compute runs in your cloud account or data center boundary, while Fireworks installs and operates the serving stack for you. Bring Your Own Cluster is in Private Preview for Enterprise customers. Contact [sales@fireworks.ai](mailto:sales@fireworks.ai) to discuss whether BYOC is a fit and to participate in the preview. ## What BYOC provides With BYOC, Fireworks deploys the managed serving software stack into Kubernetes infrastructure that you own. Fireworks operates model deployment, performance optimization, autoscaling, GPU node health and reliability, load balancing and routing, and observability for the cluster. You continue using the Fireworks product surface: the same APIs, SDKs, model deployment workflows, and performance work available across the Fireworks platform. The main difference is where inference runs: the model serving workload runs in your environment instead of Fireworks-managed cloud infrastructure. Architecture diagram coming soon. During Private Preview, Fireworks reviews the exact deployment architecture, networking boundaries, and request flow with each customer during onboarding. ## Why choose BYOC BYOC is designed for organizations that need more control over where inference runs without taking on the operational burden of self-hosting raw open-source serving infrastructure. Common reasons to consider BYOC include: * **Data residency and compliance:** Inference request and response handling runs within your Kubernetes environment, aligned to your cloud account, data center, and network requirements. * **Existing GPU capacity:** Use GPU capacity you already own or procure in your preferred cloud or data center environment. * **Network boundary control:** Keep inference workloads inside your cloud account or data center network architecture. * **Managed Fireworks experience:** Fireworks runs the serving stack, applies performance optimizations, manages model deployment, and operates the cluster day to day. * **Consistent developer interface:** Use Fireworks APIs and SDKs across serverless, dedicated Fireworks-hosted deployments, and BYOC deployments. ## When BYOC fits BYOC is usually a fit when you need Fireworks-managed inference but have requirements that place compute or data in your own environment: * You have data residency, compliance, or internal policy requirements for inference traffic. * You want Fireworks to operate model serving on GPU capacity in your cloud account or data center. * You need the same Fireworks API and managed operations model across multiple deployment environments. * You are an Enterprise customer planning a production deployment with Fireworks support. For workloads where Fireworks-managed infrastructure already satisfies your compliance and operational needs, serverless or dedicated deployments on Fireworks cloud may be simpler to start with. ## Benefits of Fireworks-managed operations BYOC is not a raw self-hosting kit. Fireworks brings the managed serving experience to infrastructure you own, so your team can focus on applications instead of rebuilding model serving operations. Fireworks continuously optimizes serving performance across model configuration, deployment shape, scheduling, quantization, speculative decoding, and workload-specific tuning such as FireOptimizer where enabled. Fireworks handles serving-stack installation, rollout, maintenance, upgrades, and day-to-day operations so your team does not have to rebuild a self-hosted inference platform. Fireworks monitors GPU and node health, detects unhealthy capacity, and safely remediates issues to reduce the operational burden of running inference on large GPU fleets. Fireworks tracks new model releases and new GPU generations, including day-0 enablement for supported models and kernel-level optimizations for supported hardware, so your BYOC environment can adopt supported updates without your team rebuilding the serving stack. ## Hybrid BYOC and Fireworks-managed capacity Some Enterprise customers want BYOC for their primary environment, but still want the option to use Fireworks-managed capacity for specific workloads or traffic spikes. During Private Preview, Fireworks can review hybrid BYOC patterns with your team, including overflow scheduling onto Fireworks-managed capacity when elected during onboarding and supported for the workload. Hybrid operation can help when: * Traffic occasionally exceeds the GPU capacity available in your cluster * You want a fallback path while customer-owned GPU capacity is being expanded or remediated * Some workloads can run outside the BYOC environment while others must remain within your network boundary * Your team wants a consistent Fireworks API surface across BYOC and Fireworks-managed deployments Hybrid BYOC is optional and must be reviewed during onboarding. Fireworks works with your team to confirm routing behavior, workload eligibility, data handling expectations, and any compliance constraints before enabling overflow onto Fireworks-managed capacity. ## Known gaps during Private Preview Training is not supported in BYOC during Private Preview. If you need training and BYOC together, contact [sales@fireworks.ai](mailto:sales@fireworks.ai) so the team can review your requirements and roadmap fit. ## Supported environments Fireworks supports BYOC on major cloud providers and their managed Kubernetes offerings, select GPU cloud providers, and on-premises environments that provide a reachable Kubernetes endpoint, supported NVIDIA GPU nodes, and the required network setup. During preview onboarding, Fireworks confirms whether your target environment, GPU capacity, and networking model are supported. At a high level, BYOC requires: * A Kubernetes cluster with NVIDIA GPU nodes * Outbound network access that allows Fireworks to manage the cluster * A deployment and support plan agreed with Fireworks during Enterprise onboarding ## Next steps If BYOC may be a fit, contact [sales@fireworks.ai](mailto:sales@fireworks.ai) to review your requirements and preview eligibility. Understand prerequisites, setup access, installation, and validation. Learn how Fireworks operates BYOC clusters after onboarding. # Development Setup with Fireworks Docs MCP Source: https://docs.fireworks.ai/ecosystem/integrations/development-setup Configure the Fireworks AI Docs MCP server for Claude Code and Cursor ## Claude Code Add the MCP server via the CLI: ```bash theme={null} claude mcp add --transport http fireworks-docs https://docs.fireworks.ai/mcp ``` Or add it to your project's `mcp.json`: ```json theme={null} { "mcpServers": { "fireworks-docs": { "url": "https://docs.fireworks.ai/mcp" } } } ``` ## Cursor One-click install: [Install Fireworks Docs MCP](https://cursor.com/en/install-mcp?name=fireworks-docs\&config=eyJ1cmwiOiJodHRwczovL2RvY3MuZmlyZXdvcmtzLmFpL21jcCJ9) Or manually add to your workspace's `mcp.json`: ```json theme={null} { "mcpServers": { "fireworks-docs": { "url": "https://docs.fireworks.ai/mcp" } } } ``` ## Using the MCP Server Once configured, your AI coding agent can search the full Fireworks AI documentation. Example queries: * "How do I configure autoscaling for deployments?" * "What parameters does the chat completions endpoint accept?" * "Show me examples of function calling with Fireworks models" * "Find the API reference for batch inference" # LiteLLM Source: https://docs.fireworks.ai/ecosystem/integrations/litellm Configure Fireworks models in LiteLLM Proxy Use [LiteLLM Proxy](https://docs.litellm.ai/docs/proxy/quick_start) as a shared gateway for Fireworks serverless models, router endpoints, and deployments. LiteLLM exposes a single OpenAI-compatible API to your developers while you manage provider credentials and access control on the server. ## Prerequisites * A [Fireworks API key](https://app.fireworks.ai/settings/users/api-keys) (`fw_...`) * LiteLLM v1.98.0 installed (`pip install "litellm[proxy]==1.98.0"`) ## Configure Fireworks models Create a `config.yaml` with one entry per model you want to expose. Use the `fireworks_ai/` provider prefix and a model- or router-qualified Fireworks ID: For FireRouter, use `fireworks_ai/routers/firerouter` or the full `fireworks_ai/accounts/fireworks/routers/firerouter` path. Do not use bare `fireworks_ai/firerouter`, which LiteLLM interprets as a model. ```yaml theme={null} model_list: - model_name: accounts/fireworks/models/glm-5p2 litellm_params: model: fireworks_ai/accounts/fireworks/models/glm-5p2 api_key: os.environ/FIREWORKS_AI_API_KEY - model_name: accounts/fireworks/routers/kimi-k2p6-fast litellm_params: model: fireworks_ai/accounts/fireworks/routers/kimi-k2p6-fast api_key: os.environ/FIREWORKS_AI_API_KEY ``` LiteLLM sends requests to `https://api.fireworks.ai/inference/v1` by default. See the [LiteLLM Fireworks AI provider docs](https://docs.litellm.ai/docs/providers/fireworks_ai) for direct-route deployments and other options. ## Start the proxy ```bash theme={null} export FIREWORKS_AI_API_KEY="fw_..." litellm --config config.yaml ``` ## Call a model If [LiteLLM virtual keys](https://docs.litellm.ai/docs/proxy/virtual_keys) are configured, clients authenticate with a virtual key: ```bash theme={null} curl http://localhost:4000/chat/completions \ -H "Authorization: Bearer $LITELLM_VIRTUAL_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "accounts/fireworks/models/glm-5p2", "messages": [{"role": "user", "content": "Say pong in one word."}] }' ``` ## API key layout | Key | Who holds it | Used for | | ----------------------------------- | ------------------------------------ | --------------------------------------- | | Fireworks API key (`fw_...`) | LiteLLM server (env or secret store) | Upstream Fireworks inference | | LiteLLM virtual key (if configured) | Each developer or service | Proxy authentication and spend tracking | A common pattern is one Fireworks service-account API key on the LiteLLM server, with per-developer virtual keys for access control and attribution. ## FireRouter To add automatic routing between closed-source and open models, register [FireRouter](/ecosystem/firerouter/overview) in the same `model_list`. An Anthropic credential makes Claude models eligible; it is optional for Fireworks-only routes or when workspace BYOK is provisioned. See [FireRouter with LiteLLM](/ecosystem/firerouter/litellm). ## Related * [LiteLLM Proxy quick start](https://docs.litellm.ai/docs/proxy/quick_start) * [LiteLLM Fireworks AI provider](https://docs.litellm.ai/docs/providers/fireworks_ai) * [FireRouter](/ecosystem/firerouter/overview): managed routing between open and closed-source models * [OpenAI compatibility](/tools-sdks/openai-compatibility): Fireworks inference API reference # MLOps & Observability Source: https://docs.fireworks.ai/ecosystem/integrations/mlops-observability Track and monitor your Fireworks AI deployments with leading MLOps and observability platforms Fireworks AI integrates with industry-leading MLOps and observability platforms to help you monitor, track, and optimize your AI applications in production. ## Supported Platforms Track training experiments and visualize training metrics with W\&B Mlflow Tracing to track prompts, outputs, latency etc as your build AI applications with FireworksAI ## Need Help? For assistance with MLOps and observability integrations, [contact our team](https://fireworks.ai/contact) or join our [Discord community](https://discord.gg/fireworks-ai). # Cookbooks Source: https://docs.fireworks.ai/examples/cookbooks Interactive Jupyter notebooks demonstrating advanced use cases and best practices with Fireworks AI Explore our collection of notebooks that showcase real-world applications, best practices, and advanced techniques for building with Fireworks AI. ## Training Transfer large model capabilities to efficient models using a two-stage SFT + RFT approach. **Techniques:** Supervised Fine-Tuning (SFT) + Reinforcement Fine-Tuning (RFT) **Results:** 52% → 70% accuracy on GSM8K mathematical reasoning Beat frontier closed-source models for product catalog cleansing with vision-language model training. **Techniques:** Supervised Fine-Tuning (SFT) **Results:** 48% increase in quality from base model ## Multimodal AI Extract structured data from invoices, forms, and financial documents using state-of-the-art OCR and document understanding. **Use Cases:** Forms, invoices, financial documents, product catalogs **Results:** 90.8% accuracy on invoice extraction (100% on invoice numbers and dates) Real-time audio transcription with streaming support and low latency. **Features:** Streaming support, low-latency transcription, production-ready Analyze video and audio content with Qwen3 Omni, a multimodal model supporting video, audio, and text inputs. **Features:** Video captioning, scene analysis, content understanding, multimodal Q\&A ## Embeddings & RAG Build a retrieval pipeline that recalls candidates with vector search, then reorders them with a reranker for precision. **Techniques:** Voyage embeddings, MongoDB `$vectorSearch`, Voyage ReRank 2.5 **Models:** Voyage AI embedders and rerankers on dedicated deployments ## API Features Leverage Model Context Protocol (MCP) for GitHub repository analysis, code search, and documentation Q\&A. **Features:** Repository analysis, code search, documentation Q\&A, GitMCP integration **Models:** Qwen 3 235B with external tool support # Courses Source: https://docs.fireworks.ai/examples/introduction Standalone end-to-end examples showing how to use Fireworks to solve real-world use cases Learn how to use Fireworks to train a model to convert natural language to SQL queries. Learn how to build reinforcement learning systems that avoid reward hacking. Learn to distill the knowledge of large AI models into efficient, deployable alternatives. # How do I close my Fireworks.ai account? Source: https://docs.fireworks.ai/faq-new/account-access/how-do-i-close-my-fireworksai-account To close your account: 1. Email [inquiries@fireworks.ai](mailto:inquiries@fireworks.ai) 2. Include in your request: * Your account ID * A clear request for account deletion Before closing your account, please ensure: * All outstanding invoices are paid, and any payment issues on prepaid accounts are resolved * Any active deployments are terminated * Important data is backed up if needed # I have multiple Fireworks accounts. When I try to login with Google on Fireworks' web UI, I'm getting signed into the wrong account. How do I fix this? Source: https://docs.fireworks.ai/faq-new/account-access/i-have-multiple-fireworks-accounts-when-i-try-to-login-with-google-on-fireworks If you log in with Google, account management is controlled by Google. You can log in through an incognito mode or create separate Chrome/browser profiles to log in with different Google accounts. You could also follow the steps in this [guide](https://support.google.com/accounts/answer/13533235?hl=en#zippy=%2Csign-in-with-google) to disassociate Fireworks.ai with a particular Google account sign-in. If you have more complex issues please contact us on Discord. # What email does GitHub authentication use? Source: https://docs.fireworks.ai/faq-new/account-access/what-email-does-github-authentication-use When you authenticate with Fireworks using GitHub, we use the **primary email address** associated with your GitHub account for identification and account management. ## How it works Fireworks automatically retrieves your primary email address from your GitHub profile during the authentication process. This email address becomes your Fireworks account identifier. ## Managing your primary email To change your primary email address on GitHub: 1. Go to your [GitHub email settings](https://github.com/settings/emails) 2. Select the email address you want to set as primary in the "Primary email address" section You can also follow the [GitHub documentation](https://docs.github.com/en/enterprise-cloud@latest/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/changing-your-primary-email-address) for detailed instructions on managing email preferences. ## Switching between accounts You can easily switch which Fireworks account your GitHub authentication logs into by changing your primary email address on GitHub before logging in. This allows you to: * Log into different Fireworks accounts using the same GitHub account * Switch between personal and work accounts by updating your GitHub primary email * Maintain separate billing and usage tracking for different email addresses The authentication will use whatever email is set as primary at the time of login, so you can switch accounts by simply updating your GitHub primary email before authenticating. # What email does LinkedIn authentication use? Source: https://docs.fireworks.ai/faq-new/account-access/what-email-does-linkedin-authentication-use When you authenticate with Fireworks using LinkedIn, we use the **primary email address** associated with your LinkedIn account for identification and account management. ## How it works Fireworks automatically retrieves your primary email address from your LinkedIn profile during the authentication process. This email address becomes your Fireworks account identifier. ## Managing your primary email To change your primary email address on LinkedIn: 1. Go to your [LinkedIn email settings](https://www.linkedin.com/mypreferences/d/manage-email-addresses) 2. From there, you can add new email addresses or change your primary email 3. Click **Add email address** to add a new email or select an existing one to make primary You can also follow the [LinkedIn documentation](https://www.linkedin.com/help/linkedin/answer/a519904) for detailed instructions on managing email preferences. ## Switching between accounts You can easily switch which Fireworks account your LinkedIn authentication logs into by changing your primary email address on LinkedIn before logging in. This allows you to: * Log into different Fireworks accounts using the same LinkedIn account * Switch between personal and work accounts by updating your LinkedIn primary email * Maintain separate billing and usage tracking for different email addresses The authentication will use whatever email is set as primary at the time of login, so you can switch accounts by simply updating your LinkedIn primary email before authenticating. # What should I do if I can't access my company account after being invited when I already have a personal account? Source: https://docs.fireworks.ai/faq-new/account-access/what-should-i-do-if-i-cant-access-my-company-account-after-being-invited-when-i This issue can occur when you have multiple accounts associated with the same email address (e.g., a personal account created with Google login and a company account you've been invited to). To resolve this: 1. Email [inquiries@fireworks.ai](mailto:inquiries@fireworks.ai) from the email address associated with both accounts 2. Include in your email: * The account ID you created personally (e.g., username-44ace8) * The company account ID you need access to (e.g., company-a57b2a) * Mention that you're having trouble accessing your company account Note: This is a known scenario that support can resolve once they verify your email ownership. # Are there discounts for bulk usage? Source: https://docs.fireworks.ai/faq-new/billing-pricing/are-there-discounts-for-bulk-usage We offer discounts for bulk or pre-paid purchases. Contact [inquiries@fireworks.ai](mailto:inquiries@fireworks.ai) to discuss volume pricing. # Are there extra fees for serving trained models? Source: https://docs.fireworks.ai/faq-new/billing-pricing/are-there-extra-fees-for-serving-fine-tuned-models Trained (LoRA) models require a dedicated deployment to serve. Here's what you need to know: **What you pay for**: * **Deployment costs** on a per-GPU-second basis for hosting the model * **The training process** itself, if applicable **Deployment options**: * **Live-merge deployment**: Deploy your LoRA model with weights merged into the base model for optimal performance * **Multi-LoRA deployment**: Deploy up to 100 LoRA models as addons on a single base model deployment For more details on deploying trained models, see the [Deploying Trained Models guide](/fine-tuning/deploying-loras). # How does billing and credit usage work? Source: https://docs.fireworks.ai/faq-new/billing-pricing/how-does-billing-and-credit-usage-work Contracted customers may have the option to move to post-paid billing. [Contact our sales team](https://fireworks.ai/company/contact-us) to discuss your options. Fireworks operates on a **pre-paid credits** billing system. You purchase credits to use the platform: * Add a valid payment method and billing address, then purchase credits. * Usage across serverless, on-demand deployments, and training deducts from your credit balance. * If your balance reaches zero and Auto Reload is not enabled, usage pauses until you add credits. * You can configure Auto Reload to purchase credits when your balance is low. * Separately, you can set a monthly spend limit for your usage. Adding credits does not raise this limit. Enterprise accounts do not have the same self-serve limits. Their monthly spend alerts track the cost of Fireworks usage, including usage paid for with credits. Adding credits itself does not count as spend. See [Enterprise quotas](/faq/enterprise/service/quotas) for more information. For details on spend limits and quota controls, see our [Account quotas guide](/guides/quotas_usage/account-quotas#view-and-adjust-your-spend-limit). # How many tokens per image? Source: https://docs.fireworks.ai/faq-new/billing-pricing/how-many-tokens-per-image Learn how to calculate token usage for images in vision models and understand pricing implications Image token consumption varies by model and resolution, typically ranging from 1,000 to 2,500 tokens per image for most common resolutions. ## Common resolution token counts The following table shows the token counts for a single image for Qwen2.5 VL at different image resolutions: | Resolution | Token Count | | ---------- | ----------- | | 336×336 | 144 | | 672×672 | 576 | | 1024×1024 | 1,369 | | 1280×720 | 1,196 | | 1920×1080 | 2,769 | | 2560×1440 | 4,641 | | 3840×2160 | 10,549 | ## Calculating exact token count for your images You can determine exact token usage by processing your images through the model's tokenizer. For instance, for Qwen2.5 VL, you can use the following code: ```bash theme={null} pip install torch torchvision transformers pillow ``` ```python Tokenizing your image theme={null} import requests from PIL import Image from transformers import AutoProcessor import os # Your image source - can be URL or local path IMAGE_URL_OR_PATH = "https://images.unsplash.com/photo-1519125323398-675f0ddb6308" def load_image(source): """Load image from URL or local file path""" if source.startswith(('http://', 'https://')): print(f"Downloading image from URL: {source}") response = requests.get(source) response.raise_for_status() return Image.open(requests.get(source, stream=True).raw) else: print(f"Loading image from path: {source}") if not os.path.exists(source): raise FileNotFoundError(f"Image file not found: {source}") return Image.open(source) def count_image_tokens(image): """Count how many tokens an image takes using Qwen 2.5 VL processor""" processor = AutoProcessor.from_pretrained("Qwen/Qwen2.5-VL-3B-Instruct") messages = [ { "role": "user", "content": [ {"type": "image", "image": image}, {"type": "text", "text": "What's in this image?"}, ], } ] text = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True) inputs = processor(text=text, images=[image], return_tensors="pt") input_ids = inputs["input_ids"][0] # Count the image pad tokens (151655 is Qwen2.5 VL's image token ID) image_tokens = (input_ids == 151655).sum().item() return image_tokens, input_ids def main(): import sys image_source = sys.argv[1] if len(sys.argv) > 1 else IMAGE_URL_OR_PATH print(f"Processing image: {image_source}") image = load_image(image_source) print(f"Image size: {image.size}") print(f"Image mode: {image.mode}") print("\nCalculating tokens...") image_tokens, input_ids = count_image_tokens(image) print(f"Total tokens: {len(input_ids)}") print(f"Image tokens: {image_tokens}") print(f"Text tokens: {len(input_ids) - image_tokens}") if __name__ == "__main__": main() ``` ```bash Usage theme={null} # Calculate tokens for an image URL python token_calculator.py "https://example.com/image.jpg" # Calculate tokens for a local image python token_calculator.py "path/to/your/image.png" ``` # How much does Fireworks cost? Source: https://docs.fireworks.ai/faq-new/billing-pricing/how-much-does-fireworks-cost Contracted customers may have the option to move to post-paid billing. [Contact our sales team](https://fireworks.ai/company/contact-us) to discuss your options. Fireworks AI uses a **usage-based pre-paid** billing system. You purchase credits, then usage is deducted based on: * **Per token** for serverless inference * **Per GPU usage time** for on-demand deployments * **Per training token** for Managed Training For customers needing **enterprise-grade security and reliability**, please reach out to us at [inquiries@fireworks.ai](mailto:inquiries@fireworks.ai) to discuss options. Find out more about our current pricing on our [Pricing page](https://fireworks.ai/pricing). # Is prompt caching billed differently for serverless models? Source: https://docs.fireworks.ai/faq-new/billing-pricing/is-prompt-caching-billed-differently Yes, **cached prompt tokens are discounted compared to uncached tokens for serverless models**. The default discount is 50%, but the exact discount varies by model. Check the [Model Library](https://fireworks.ai/models) for model-specific cached and uncached input token pricing. # How do credits work? Source: https://docs.fireworks.ai/faq-new/billing-pricing/what-happens-when-i-finish-my-1-dollar-credit Contracted customers may have the option to move to post-paid billing. [Contact our sales team](https://fireworks.ai/company/contact-us) to discuss your options. ## How credits are applied Fireworks operates on a **pre-paid credits** billing system. You purchase credits to use the platform: * Credits are used first for all usage. * If credits are exhausted and Auto Reload is disabled, usage pauses until you add credits. * If Auto Reload is enabled, credits are purchased automatically when your balance reaches your configured minimum. * You can separately set a monthly spend limit for your usage. Adding credits does not raise this limit. ## Missing credits after purchase? If you don't see your credits reflected immediately: 1. Visit your **billing dashboard** 2. Review the **"Credits"** section 3. Check your **credit balance** and **Auto Reload settings** **Important**: Usage consumes available credits. If your balance is low, enable Auto Reload to avoid interruptions. ## Why did I receive an invoice after depositing credits? Most accounts on pre-paid billing should not see month-end overage invoices. If you received an invoice, your account may be on a post-paid contract. Contact [community\_billing@fireworks.ai](mailto:community_billing@fireworks.ai) so we can confirm your billing configuration. ## What happens when I finish my \$1 credit? When you finish your \$1 credit, the following occurs: ## Account Status * **Without payment method**: Your account will be **suspended** until you add a payment method. For request-rate behavior, see [Account quotas](/guides/quotas_usage/account-quotas#account-wide-request-limits); for serverless TPM upper bounds, see [Serverless rate limits](/serverless/rate-limits). * **With payment method**: Add credits to continue usage. [Account-wide request limits](/guides/quotas_usage/account-quotas#account-wide-request-limits) increase, and [serverless TPM upper bounds](/serverless/rate-limits) grow as your account spend tier rises. **Payment Method Requirements:** * Adding a payment method is required to continue service after credit depletion * Add credits (or enable Auto Reload) to continue service after credit depletion * As you spend more with Fireworks, your adaptive usage limits and serverless TPM upper bounds can increase ## Where's my receipt for purchased credits? Receipts for purchased credits are sent via Stripe upon purchase. Check your email for receipts from Stripe (not Fireworks). If you can't find your receipt, contact [community\_billing@fireworks.ai](mailto:community_billing@fireworks.ai). For spend limits, tiers, and account-wide request limits, see [Account quotas](/guides/quotas_usage/account-quotas). For adaptive serverless TPM upper bounds, see [Serverless rate limits](/serverless/rate-limits). # Why might my account be suspended even with remaining credits? Source: https://docs.fireworks.ai/faq-new/billing-pricing/why-might-my-account-be-suspended-even-with-remaining-credits Your account may be suspended due to several factors: 1. **Monthly spend limit reached**: * Your monthly spend limit can pause usage even if you still have a credit balance. * Increase your spend limit in Billing to resume usage. Adding credits alone does not raise the limit. 2. **Payment or risk checks**: * Accounts may be temporarily paused if payment verification fails. * In some cases, manual review can temporarily limit usage. 3. **Post-paid contract terms**: * Contracted customers on post-paid billing may have different suspension rules under their agreement. * Enterprise monthly spend alerts are informational and do not pause service. If you're experiencing account suspension issues or need assistance with your spend limit or billing settings, please contact [inquiries@fireworks.ai](mailto:inquiries@fireworks.ai). # Are there any quotas for serverless? Source: https://docs.fireworks.ai/faq-new/deployment-infrastructure/are-there-any-quotas-for-serverless Yes. Standard serverless, Priority tier, and Fast all have serverless rate limits and quotas. For the detailed serverless policy, see our [Serverless rate limits guide](/serverless/rate-limits). # Do you provide notice before removing model availability? Source: https://docs.fireworks.ai/faq-new/deployment-infrastructure/do-you-provide-notice-before-removing-model-availability Yes, we provide advance notice before removing models from the serverless infrastructure: * **Minimum 2 weeks’ notice** before model removal * Longer notice periods may be provided for **popular models**, depending on usage * Higher-usage models may have extended deprecation timelines **Best Practices**: 1. Monitor announcements regularly. 2. Prepare a migration plan in advance. 3. Test alternative models to ensure continuity. 4. Keep your contact information updated for timely notifications. # Do you support Auto Scaling? Source: https://docs.fireworks.ai/faq-new/deployment-infrastructure/do-you-support-auto-scaling Yes, our system supports **auto scaling** with the following features: * **Scaling down to zero** capability for resource efficiency * Controllable **scale-up and scale-down velocity** * **Custom scaling rules and thresholds** to match your specific needs # How does autoscaling affect my costs? Source: https://docs.fireworks.ai/faq-new/deployment-infrastructure/how-does-autoscaling-affect-my-costs * **Scaling from 0**: No minimum cost when scaled to zero * **Scaling up**: Each new replica adds to your total cost proportionally. For example: * Scaling from 1 to 2 replicas doubles your GPU costs * If each replica uses multiple GPUs, costs scale accordingly (e.g., scaling from 1 to 2 replicas with 2 GPUs each means paying for 4 GPUs total) For current pricing details, please visit our [pricing page](https://fireworks.ai/pricing). # How does billing and scaling work for on-demand GPU deployments? Source: https://docs.fireworks.ai/faq-new/deployment-infrastructure/how-does-billing-and-scaling-work-for-on-demand-gpu-deployments On-demand GPU deployments have unique billing and scaling characteristics compared to serverless deployments: **Billing**: * Charges start when the server begins accepting requests * **Billed by GPU-second** for each active instance * Costs accumulate even if there are no active API calls **Scaling options**: * Supports **autoscaling** from 0 to multiple GPUs * Each additional GPU **adds to the billing rate** * Can handle unlimited requests within the GPU’s capacity **Management requirements**: * Not fully serverless; requires some manual management * **Manually delete deployments** when no longer needed * Or configure autoscaling to **scale down to 0** during inactive periods **Cost control tips**: * Regularly **monitor active deployments** * **Delete unused deployments** to avoid unnecessary costs * Consider **serverless options** for intermittent usage * Use **autoscaling to 0** to optimize costs during low-demand times # How does billing work for on-demand deployments? Source: https://docs.fireworks.ai/faq-new/deployment-infrastructure/how-does-billing-work-for-on-demand-deployments On-demand deployments come with automatic cost optimization features: * **Default autoscaling**: Automatically scales to 0 replicas when not in use * **Pay for what you use**: Charged only for GPU time when replicas are active * **Flexible configuration**: Customize autoscaling behavior to match your needs **Best practices for cost management**: 1. **Leverage default autoscaling**: The system automatically scales down deployments when not in use 2. **Customize carefully**: While you can modify autoscaling behavior using our [configuration options](https://docs.fireworks.ai/guides/ondemand-deployments#customizing-autoscaling-behavior), note that preventing scale-to-zero will result in continuous GPU charges 3. **Consider your use case**: For intermittent or low-frequency usage, serverless deployments might be more cost-effective For detailed configuration options, see our [deployment guide](https://docs.fireworks.ai/guides/ondemand-deployments#replica-count-horizontal-scaling). # How does the system scale? Source: https://docs.fireworks.ai/faq-new/deployment-infrastructure/how-does-the-system-scale Our system is **horizontally scalable**, meaning it: * Scales linearly with additional **replicas** of the deployment * **Automatically allocates resources** based on demand * Manages **distributed load handling** efficiently # Are there SLAs for serverless? Source: https://docs.fireworks.ai/faq-new/deployment-infrastructure/is-latency-guaranteed-for-serverless-models Our multi-tenant serverless offering does not currently come with Service Level Agreements (SLAs) for latency or availability. If you have specific performance or availability requirements, we recommend: * **On-demand deployments**: Provides dedicated resources with predictable performance * **Contact sales**: [Reach out to discuss](https://fireworks.ai/company/contact-us) custom solutions and enterprise options # What are the rate limits for on-demand deployments? Source: https://docs.fireworks.ai/faq-new/deployment-infrastructure/what-are-the-rate-limits-for-on-demand-deployments On-demand deployments have GPU quotas that determine your maximum allocation. For detailed information about on-demand deployment quotas and GPU limits, see our [Account quotas guide](/guides/quotas_usage/account-quotas#on-demand-deployment-quotas). Need higher GPU allocations? [Contact us](https://fireworks.ai/company/contact-us) to discuss custom solutions for your use case. # What factors affect the number of simultaneous requests that can be handled? Source: https://docs.fireworks.ai/faq-new/deployment-infrastructure/what-factors-affect-the-number-of-simultaneous-requests-that-can-be-handled The request handling capacity is influenced by multiple factors: * **Model size and type** * **Number of GPUs** allocated to the deployment * **GPU type** (e.g., A100 vs. H100) * **Prompt size** and **generation token length** * **Deployment type** (serverless vs. on-demand) # What is a deployment shape, and why did my deployment fail to create? Source: https://docs.fireworks.ai/faq-new/deployment-infrastructure/what-is-a-deployment-shape A **deployment shape** is a pre-validated, pre-configured deployment template. It bundles a known-good combination of GPU type and count, precision, and serving parameters, optimized for speed (`fast`), cost per token at scale (`throughput`), or lowest cost (`minimal`). A deployment created from a shape starts from a configuration that is known to work for that model. ## Why deployments created without a shape often fail If you create a deployment without a shape — that is, without passing `--deployment-shape` (or `deploymentShape` in the API) — the configuration is not validated ahead of time. Mistakes only surface at creation, where they cause failures. Common examples: * A GPU count that cannot fit the model in memory * An accelerator type the model isn't validated on (for example, requesting H200 for a model whose shapes are all B200) * A context length the configuration can't serve * A quantization or precision the model doesn't support on that hardware Deployments created without a shape fail far more often than deployments created from a shape — they are the most common cause of failed deployment creations on Fireworks. Do not create deployments without a shape; the unshaped path may be deprecated in the future. ## How to find and use a shape The shape list is also the authoritative way to discover which GPU types, GPU counts, and precisions a model supports — a hardware combination with no shape is not a validated configuration. List the shapes available for your model: ```bash theme={null} firectl deployment-shape-version list --base-model accounts/fireworks/models/gpt-oss-120b ``` Then pass the shape's name to `--deployment-shape` when creating the deployment: ```bash theme={null} firectl deployment create accounts/fireworks/models/gpt-oss-120b \ --deployment-shape accounts/fireworks/deploymentShapes/gpt-oss-120b-fast ``` Call [Match Deployment Shape Versions](/api-reference/match-deployment-shape-versions) with a deployment create request for your model. It returns the validated shape versions compatible with that model, with the server-side compatibility rules (PEFT base-model resolution, per-model hardware tiers, addon gating) applied for you: ```bash theme={null} # YOUR_ACCOUNT_ID is the account that will own the deployment, not the # model's publisher. The model in the body can live anywhere you can # deploy it, e.g. accounts/fireworks. curl -X POST "https://api.fireworks.ai/v1/accounts/YOUR_ACCOUNT_ID/deploymentShapeVersions:match" \ -H "Authorization: Bearer $FIREWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "createDeploymentRequest": { "deployment": { "baseModel": "accounts/fireworks/models/gpt-oss-120b" } } }' ``` Then pass one of the returned shape versions as `deploymentShape` in the [Create Deployment](/api-reference/create-deployment) request body: ```bash theme={null} curl -X POST "https://api.fireworks.ai/v1/accounts/YOUR_ACCOUNT_ID/deployments" \ -H "Authorization: Bearer $FIREWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "baseModel": "accounts/fireworks/models/gpt-oss-120b", "deploymentShape": "accounts/fireworks/deploymentShapes/gpt-oss-120b-fast" }' ``` On the model page, choose **Deploy** and pick a shape. ## If no shape fits If you need a configuration that no existing shape covers, [contact us](https://fireworks.ai/contact) — we'll help you find the right shape or add one for your workload. # What’s the supported throughput? Source: https://docs.fireworks.ai/faq-new/deployment-infrastructure/whats-the-supported-throughput Throughput capacity typically depends on several factors: * **Deployment type** (serverless or on-demand) * **Traffic patterns** and **request patterns** * **Hardware configuration** * **Model size and complexity** # Why am I experiencing request timeout errors and slow response times with serverless LLM models? Source: https://docs.fireworks.ai/faq-new/deployment-infrastructure/why-am-i-experiencing-request-timeout-errors-and-slow-response-times-with-server Timeout errors and increased response times can occur due to **server load during high-traffic periods**. With serverless, users are essentially **sharing a pool of GPUs** with models pre-provisioned. The goal of serverless is to allow users and teams to **seamlessly power their generative applications** with the **latest generative models** in **less than 5 lines of code**. Deployment barriers should be **minimal** and **pricing is based on usage**. However there are trade-offs with this approach, namely that in order to ensure users have **consistent access** to the most in-demand models, users are also subject to **minor latency and performance variability** during **high-volume periods**. With **on-demand deployments**, users are reserving GPUs (which are **billed by rented time** instead of usage volume) and don't have to worry about traffic spikes. Which is why our two recommended ways to address timeout and response time issues is: ### Current solution (recommended for production) * **Use on-demand deployments** for more stable performance * **Guaranteed response times** * **Dedicated resources** to ensure availability We are always investing in ways to improve speed and performance. ### Upcoming improvements * Enhanced SLAs for uptime * More consistent generation speeds during peak load times If you experience persistent issues, please include the following details in your support request: 1. Exact **model name** 2. **Timestamp** of errors (in UTC) 3. **Frequency** of timeouts 4. **Average wait times** ### Performance optimization tips * Consider **batch processing** for handling bulk requests * Implement **retry logic with exponential backoff** * Monitor **usage patterns** to identify peak traffic times * Set **appropriate timeout settings** based on model complexity # Does Fireworks support custom base models? Source: https://docs.fireworks.ai/faq-new/models-inference/does-fireworks-support-custom-base-models Yes, custom base models can be deployed via **firectl**. You can learn more about custom model deployment in our [guide on uploading custom models](https://docs.fireworks.ai/models/uploading-custom-models). # Does the API support batching and load balancing? Source: https://docs.fireworks.ai/faq-new/models-inference/does-the-api-support-batching-and-load-balancing Current capabilities include: * **Load balancing**: Yes, supported out of the box * **Continuous batching**: Yes, supported * **Batch inference**: Yes, supported via the [Batch API](/guides/batch-inference) * **Streaming**: Yes, supported For asynchronous batch processing of large volumes of requests, see our [Batch API documentation](/guides/batch-inference). # How do I control output image sizes when using SDXL ControlNet? Source: https://docs.fireworks.ai/faq-new/models-inference/how-do-i-control-output-image-sizes-when-using-sdxl-controlnet When using **SDXL ControlNet** (e.g., canny control), the output image size is determined by the explicit **width** and **height** parameters in your API request: The input control signal image will be automatically: * **Resized** to fit your specified dimensions * **Cropped** to preserve aspect ratio **Example**: To generate a 768x1344 image, explicitly include these parameters in your request: ```json theme={null} { "width": 768, "height": 1344 } ``` *Note*: While these parameters may not appear in the web interface examples, they are supported API parameters that can be included in your requests. # How to check if a model is available on serverless? Source: https://docs.fireworks.ai/faq-new/models-inference/how-to-check-if-a-model-is-available-on-serverless ## Web UI Go to [https://app.fireworks.ai/models?filter=LLM\&serverless=true](https://app.fireworks.ai/models?filter=LLM\&serverless=true) ## API You can programmatically retrieve all serverless models using the [List Models API](/api-reference/list-models) with the `supports_serverless=true` filter. ```python theme={null} from fireworks import Fireworks client = Fireworks() # List all serverless models models = client.models.list(filter="supports_serverless=true") for model in models: print(model.name) ``` You can also combine filters and customize the response: ```python theme={null} # List serverless models with pagination models = client.models.list( filter="supports_serverless=true", page_size=50, ) for model in models: print(f"{model.name}: {model.display_name}") ``` ```bash theme={null} curl "https://api.fireworks.ai/v1/accounts/fireworks/models?filter=supports_serverless%3Dtrue" \ -H "Authorization: Bearer $FIREWORKS_API_KEY" ``` With pagination: ```bash theme={null} curl "https://api.fireworks.ai/v1/accounts/fireworks/models?filter=supports_serverless%3Dtrue&pageSize=50" \ -H "Authorization: Bearer $FIREWORKS_API_KEY" ``` The filter parameter uses the [AIP-160 filter syntax](https://google.aip.dev/160). The `supports_serverless` field indicates whether a model is available on serverless infrastructure. See the [List Models API reference](/api-reference/list-models) for all available parameters including `order_by`, `page_size`, and `read_mask`. # There’s a model I would like to use that isn’t available on Fireworks. Can I request it? Source: https://docs.fireworks.ai/faq-new/models-inference/theres-a-model-i-would-like-to-use-that-isnt-available-on-fireworks-can-i-reques Fireworks supports a wide array of custom models and actively takes feature requests for new, popular models to add to the platform. **To request new models**: 1. **Join our [Discord server](https://discord.gg/fireworks-ai)** 2. Let us know which models you’d like to see 3. Provide **use case details**, if possible, to help us prioritize We regularly evaluate and add new models based on: * **Community requests** * **Popular demand** * **Technical feasibility** * **Licensing requirements** # What factors affect the number of simultaneous requests that can be handled? Source: https://docs.fireworks.ai/faq-new/models-inference/what-factors-affect-the-number-of-simultaneous-requests-that-can-be-handled Request handling capacity depends on several factors: * **Model size and type** * **Number of GPUs allocated** to the deployment * **GPU type** (e.g., A100, H100) * **Prompt size** * **Generation token length** * **Deployment type** (serverless vs. on-demand) # Agent Skills Source: https://docs.fireworks.ai/fine-tuning/agent/use-with-coding-agents Install Fireworks training skills for your coding agent — research, configure, and debug. One installation gives you three entry points. Open a chat and describe your goal in plain language. | Skill | Use it for | | ------------- | ---------------------------------------------------------------------------------------------------------------- | | **research** | Choose method, data, evaluation, and the closest [cookbook](https://github.com/fw-ai/cookbook) entry. Read-only. | | **configure** | Plan, run, monitor, deploy, or resume training. Shows parameters and cost, then waits for approval before spend. | | **debug** | Diagnose a stuck, failed, or low-quality run. Read-only until you approve a retry. | The **fireworks-training** compatibility skill carries shared detailed references that **configure** and **debug** load. Keep it installed with the three entry skills. ## Install ### Claude Code Install the auto-updating cookbook plugin. Here `fireworks-training` is the plugin name rather than a single skill, and the plugin ships all of the skills above: ```bash theme={null} claude plugin marketplace add fw-ai/cookbook claude plugin install fireworks-training@fw-ai-cookbook ``` ### Cursor `npx skills` installs by skill directory, so name each skill you want: ```bash theme={null} npx --yes skills add fw-ai/cookbook -g \ -s fireworks-training research configure debug -a cursor -y ``` ### Codex ```bash theme={null} npx --yes skills add fw-ai/cookbook -g \ -s fireworks-training research configure debug -a codex -y ``` ### Other compatible agents Install to every detected Agent Skills-compatible harness: ```bash theme={null} npx --yes skills add fw-ai/cookbook -g \ -s fireworks-training research configure debug -a '*' -y ``` The commands above install skills globally with `-g`. They do not update automatically. Refresh the global copies with `npx --yes skills update -g -y`. Full post-install walkthrough: [cookbook `skills/GETTING-STARTED.md`](https://github.com/fw-ai/cookbook/blob/main/skills/GETTING-STARTED.md). ## Prerequisites * [Fireworks CLI (`firectl`)](/tools-sdks/firectl/firectl) installed. Authenticate with either `firectl signin` or `FIREWORKS_API_KEY`. * Export `FIREWORKS_API_KEY` for Training API Python workflows. * Prefer a **scoped** service-account key over a personal admin key for agent use. If `firectl` blocks a mutating command inside an AI-agent environment, the skill gives you the exact command to run manually, then resumes read-only monitoring. Use [managed training](/fine-tuning/managed-finetuning-intro) for standard jobs, or the [Training API](/fine-tuning/training-api/introduction) for custom loops on [serverless or dedicated infrastructure](/fine-tuning/training-api/introduction#infrastructure). ## Usage data and privacy Authenticated API calls include `fireworks-training-skill/` and a random session ID for aggregate product analytics. Prompts and datasets are not collected. Before the first structured question, the skills show a one-line privacy notice. With `FIREWORKS_API_KEY` set, aggregate journey events may be recorded through supported `firectl` commands. Say `do not track this session` to keep interaction telemetry local. Training still works. ## See also Post-install guide and first run. Runnable notebooks research routes to. Pick managed training vs the Training API before you install. Drive the same training infra directly when you know your config. Write your own Python training loop on Fireworks GPUs. Automate managed training with `firectl`. # Remote Environment Setup Source: https://docs.fireworks.ai/fine-tuning/connect-environments Implement the /init endpoint to run evaluations in your infrastructure If you already have an agent running in your product, or need to run rollouts on your own infrastructure, you can integrate it with RFT using the `RemoteRolloutProcessor`. This delegates rollout execution to an HTTP service you control. Remote agent are ideal for: * Multi-turn agentic workflows with tool use * Access to private databases, APIs, or internal services * Integration with existing agent codebases * Complex simulations that require your infrastructure New to RFT? Start with [local agent](/fine-tuning/quickstart-math) instead. They're simpler and cover most use cases. Only use remote agent environments when you need access to private infrastructure or have an existing agent to integrate. ## How remote rollouts work Remote rollout processor flow diagram showing the interaction between Eval Protocol, your remote server, and Fireworks Tracing During training, Fireworks calls your service's `POST /init` endpoint with the dataset row and correlation metadata. Your agent executes the task (e.g., multi-turn conversation, tool calls, simulation steps), logging progress via Fireworks tracing. Your service sends structured logs tagged with rollout metadata to Fireworks so the system can track completion. Once Fireworks detects completion, it pulls the full trace and evaluates it using your scoring logic. Everything except implementing your remote server is handled automatically by Eval Protocol. You only need to implement the `/init` endpoint and add Fireworks tracing. ## Implementing the /init endpoint Your remote service must implement a single `/init` endpoint that accepts rollout requests. ### Request schema Model configuration including model name and inference parameters like temperature, max\_tokens, etc. Array of conversation messages to send to the model Array of available tools for the model (for function calling) Base URL for making LLM calls through Fireworks tracing (includes correlation metadata) Rollout execution metadata for correlation (rollout\_id, run\_id, row\_id, etc.) Fireworks API key to use for model calls ### Example request ```json theme={null} { "completion_params": { "model": "accounts/fireworks/models/qwen3-4b", "temperature": 0.7, "max_tokens": 2048 }, "messages": [ { "role": "user", "content": "What is the weather in San Francisco?" } ], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "Get the weather for a city", "parameters": { "type": "object", "properties": { "city": { "type": "string" } } } } } ], "model_base_url": "https://tracing.fireworks.ai/rollout_id/brave-night-42/invocation_id/wise-ocean-15/experiment_id/calm-forest-28/run_id/quick-river-07/row_id/bright-star-91", "metadata": { "invocation_id": "wise-ocean-15", "experiment_id": "calm-forest-28", "rollout_id": "brave-night-42", "run_id": "quick-river-07", "row_id": "bright-star-91" }, "api_key": "fw_your_api_key" } ``` ## Metadata correlation The `metadata` object contains correlation IDs that you must include when logging to Fireworks tracing. This allows Eval Protocol to match logs and traces back to specific evaluation rows. Required metadata fields: * `invocation_id` - Identifies the evaluation invocation * `experiment_id` - Groups related experiments * `rollout_id` - Unique ID for this specific rollout (most important) * `run_id` - Identifies the evaluation run * `row_id` - Links to the dataset row `RemoteRolloutProcessor` automatically generates these IDs and sends them to your server. You don't need to create them yourself—just pass them through to your logging. ## Fireworks tracing integration Your remote server must use Fireworks tracing to report rollout status. Eval Protocol polls these logs to detect when rollouts complete. ### Basic setup ```python theme={null} import logging from eval_protocol import Status, InitRequest, FireworksTracingHttpHandler, RolloutIdFilter # Configure Fireworks tracing handler globally fireworks_handler = FireworksTracingHttpHandler() logging.getLogger().addHandler(fireworks_handler) @app.post("/init") def init(request: InitRequest): # Create rollout-specific logger with filter rollout_logger = logging.getLogger(f"eval_server.{request.metadata.rollout_id}") rollout_logger.addFilter(RolloutIdFilter(request.metadata.rollout_id)) try: # Execute your agent logic here result = execute_agent(request) # Log successful completion with structured status rollout_logger.info( f"Rollout {request.metadata.rollout_id} completed", extra={"status": Status.rollout_finished()} ) return {"status": "success"} except Exception as e: # Log errors with structured status rollout_logger.error( f"Rollout {request.metadata.rollout_id} failed: {e}", extra={"status": Status.rollout_error(str(e))} ) raise ``` ### Key components 1. **FireworksTracingHttpHandler**: Sends logs to Fireworks tracing service 2. **RolloutIdFilter**: Tags logs with the rollout ID for correlation 3. **Status objects**: Structured status reporting that Eval Protocol can parse * `Status.rollout_finished()` - Signals successful completion * `Status.rollout_error(message)` - Signals failure with error details ### Alternative: Environment variable approach For simpler setups, you can use the `EP_ROLLOUT_ID` environment variable instead of manual filters. If your server processes one rollout at a time (e.g., serverless functions, container per request): ```python theme={null} import os import logging from eval_protocol import Status, InitRequest, FireworksTracingHttpHandler # Set rollout ID in environment os.environ["EP_ROLLOUT_ID"] = request.metadata.rollout_id # Configure handler (automatically picks up EP_ROLLOUT_ID) fireworks_handler = FireworksTracingHttpHandler() logging.getLogger().addHandler(fireworks_handler) logger = logging.getLogger(__name__) @app.post("/init") def init(request: InitRequest): # Logs are automatically tagged with rollout_id logger.info("Processing rollout...") # ... execute agent logic ... ``` If your `/init` handler spawns separate Python processes for each rollout: ```python theme={null} import os import logging import multiprocessing from eval_protocol import FireworksTracingHttpHandler, InitRequest def execute_rollout_step_sync(request): # Set EP_ROLLOUT_ID in the child process os.environ["EP_ROLLOUT_ID"] = request.metadata.rollout_id logging.getLogger().addHandler(FireworksTracingHttpHandler()) # Execute your rollout logic here # Logs are automatically tagged @app.post("/init") async def init(request: InitRequest): # Do NOT set EP_ROLLOUT_ID in parent process p = multiprocessing.Process( target=execute_rollout_step_sync, args=(request,) ) p.start() return {"status": "started"} ``` ### How Eval Protocol uses tracing 1. **Your server logs completion**: Uses `Status.rollout_finished()` or `Status.rollout_error()` 2. **Eval Protocol polls**: Searches Fireworks logs by `rollout_id` tag until completion signal found 3. **Status extraction**: Reads structured status fields (`code`, `message`, `details`) to determine outcome 4. **Trace retrieval**: Fetches full trace of model calls and tool use for evaluation ## Complete example Here's a minimal but complete remote server implementation: ```python theme={null} from fastapi import FastAPI from fastapi.responses import JSONResponse from eval_protocol import InitRequest, FireworksTracingHttpHandler, RolloutIdFilter, Status import logging app = FastAPI() # Setup Fireworks tracing fireworks_handler = FireworksTracingHttpHandler() logging.getLogger().addHandler(fireworks_handler) @app.post("/init") async def init(request: InitRequest): # Create rollout-specific logger rollout_logger = logging.getLogger(f"eval_server.{request.metadata.rollout_id}") rollout_logger.addFilter(RolloutIdFilter(request.metadata.rollout_id)) rollout_logger.info(f"Starting rollout {request.metadata.rollout_id}") try: # Your agent logic here # 1. Make model calls using request.model_base_url # 2. Call tools, interact with environment # 3. Collect results result = run_your_agent( messages=request.messages, tools=request.tools, model_config=request.completion_params, api_key=request.api_key ) # Signal completion rollout_logger.info( f"Rollout {request.metadata.rollout_id} completed successfully", extra={"status": Status.rollout_finished()} ) return {"status": "success", "result": result} except Exception as e: # Signal error rollout_logger.error( f"Rollout {request.metadata.rollout_id} failed: {str(e)}", extra={"status": Status.rollout_error(str(e))} ) return JSONResponse( status_code=500, content={"status": "error", "message": str(e)} ) def run_your_agent(messages, tools, model_config, api_key): # Implement your agent logic here # Make model calls, use tools, etc. pass ``` ## Testing locally Before deploying, test your remote server locally: ```bash theme={null} uvicorn main:app --reload --port 8080 ``` In your evaluator test, point to your local server: ```python theme={null} from eval_protocol.pytest import RemoteRolloutProcessor rollout_processor = RemoteRolloutProcessor( remote_base_url="http://localhost:8080" ) ``` ```bash theme={null} pytest my-evaluator-name.py -vs ``` This sends test rollouts to your local server and verifies the integration works. ## Deploying your service Once tested locally, deploy to production: * ✅ Service is publicly accessible (or accessible via VPN/private network) * ✅ HTTPS endpoint with valid SSL certificate (recommended) * ✅ Authentication/authorization configured * ✅ Monitoring and logging set up * ✅ Auto-scaling configured for concurrent rollouts * ✅ Error handling and retry logic implemented * ✅ Service availability SLA meets training requirements **Vercel/Serverless**: * One rollout per function invocation * Use environment variable approach * Configure timeout for long-running evaluations **AWS ECS/Kubernetes**: * Handle concurrent requests with proper worker configuration * Use RolloutIdFilter approach * Set up load balancing **On-premise**: * Ensure network connectivity from Fireworks * Configure firewall rules * Set up VPN if needed for security ## Connecting to RFT Once your remote server is deployed, create an RFT job that uses it: ```bash theme={null} eval-protocol create rft \ --base-model accounts/fireworks/models/qwen3-4b \ --remote-server-url https://your-evaluator.example.com \ --dataset my-dataset ``` The RFT job will send all rollouts to your remote server for evaluation during training. ## Troubleshooting **Symptoms**: Rollouts show as timed out or never complete **Solutions**: * Check that your service is logging `Status.rollout_finished()` correctly * Verify Fireworks tracing handler is configured * Ensure rollout\_id is included in log tags * Check for exceptions being swallowed without logging **Symptoms**: Eval Protocol can't match logs to rollouts **Solutions**: * Verify you're using the exact `rollout_id` from request metadata * Check that RolloutIdFilter or EP\_ROLLOUT\_ID is set correctly * Ensure logs are being sent to Fireworks (check tracing dashboard) **Symptoms**: Training is slow, high rollout latency **Solutions**: * Scale your service to handle concurrent requests * Optimize your agent logic (caching, async operations) * Add more workers or instances * Profile your code to find bottlenecks **Symptoms**: Model calls fail, API errors **Solutions**: * Verify API key is passed correctly from request * Check that your service has network access to Fireworks * Ensure model\_base\_url is used for traced calls ## Example implementations Learn by example: Complete walkthrough using a Vercel TypeScript server for SVG generation Minimal Python implementation showing the basics ## Next steps Launch your RFT job using the CLI Track rollout progress and debug issues Full Remote Rollout Processor tutorial Design effective reward functions ## Agent tracing Remote RFT needs **correlated traces** so the trainer can join rollouts, tool calls, and rewards. Your environment receives `model_base_url` (OpenAI-compatible, on `tracing.fireworks.ai`) and correlation IDs in `/init`. **Minimum wiring:** 1. Use `model_base_url` from `/init` for all model calls (do not override). 2. Add `FireworksTracingHttpHandler` and log `Status.rollout_finished()` or `Status.rollout_error()` when the rollout ends. 3. Tag logs with `rollout_id` via `RolloutIdFilter` or `EP_ROLLOUT_ID`. **Coding agents:** correlation fields, minimal server example, capture checklist, and RemoteRolloutProcessor polling → [RFT agent tracing](https://github.com/fw-ai/cookbook/blob/main/skills/fireworks-training/references/rft-agent-tracing.md) in the Fireworks training skill. ### Next steps Implement `/init`, tracing, and structured status for remote agents Build and deploy a local evaluator in under 10 minutes Launch your RFT job Design effective reward functions for your task # Training cost estimator Source: https://docs.fireworks.ai/fine-tuning/cost-estimator Estimate Managed Training, compare Fireworks Serverless with Dedicated, or compare Fireworks Dedicated with Tinker
  • Managed and Serverless are [priced per token](https://fireworks.ai/pricing#training-pricing).
  • Dedicated is [priced per allocated GPU hour](https://fireworks.ai/pricing#on-demand-pricing).
  • Planning estimates are not quotes.
  • Managed estimates can be low when rendered-token inputs omit multi-turn unrolling. Dedicated compute floors can be low when sequences pack poorly.
  • Dedicated shows a saturated compute floor. Allocated GPU time spent initializing the model, writing checkpoints, or idle can make real jobs cost more. Queue wait and pre-allocation provisioning are not billed.
## Prepare inputs with the Training Skill The [Fireworks Training Skill](/fine-tuning/agent/use-with-coding-agents) prepares inputs and calculates Managed and Serverless estimates from published rates. It can inspect a local dataset or an existing job and identify assumptions. It does not calculate Dedicated numbers. Use this page for Dedicated planning. The Skill does not launch a job or authorize spend while estimating. Training still requires the Skill's complete final plan and your explicit confirmation. ## Reinforcement learning RL cost varies with rollout shape, concurrency, reward or verifier design, training method, and evaluation workload. [Contact the Training team](https://fireworks.ai/contact-training) for a tailored estimate. To compare the rollout inference cost of multi-turn agentic RL, use the separate [rollout cost comparison](/fine-tuning/multi-turn-cost-comparison). That page does not estimate SFT or DPO training cost. # Deploying Trained Models Source: https://docs.fireworks.ai/fine-tuning/deploying-loras Deploy one or multiple LoRA models trained on Fireworks using live merge or multi-LoRA After training your model on Fireworks, deploy it to make it available for inference. Fireworks supports two deployment methods for LoRA trained models: **live merge** and **multi-LoRA**. Each method has different tradeoffs around performance, cost, and flexibility. To run training evals before production serving, see [Evaluating Trained Models](/fine-tuning/evaluating-fine-tuned-models). This page covers production serving. Trained LoRA models, whether created on the Fireworks platform or imported, can **only** be deployed to **on-demand (dedicated) deployments**. Serverless deployment is not supported for LoRA models. You can also upload and deploy LoRA models trained outside of Fireworks. See [importing trained models](/models/uploading-custom-models#importing-trained-models) for details. ## Choosing a deployment method Fireworks offers two ways to deploy LoRA trained models. The right choice depends on how many trained variants you need to serve and your performance requirements. | | **Live merge** | **Multi-LoRA** | | ------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | **How it works** | LoRA weights are merged into the base model at deployment time, creating a single merged model | Base model is deployed with addon support; LoRA adapters are loaded dynamically at request time | | **Number of LoRAs** | One per deployment | Multiple per deployment | | **Inference performance** | Matches the base model (no overhead) | Some overhead per request due to dynamic adapter application | | **Throughput** | Same as base model | Lower maximum throughput under high concurrency | | **Cost efficiency** | One deployment per adapter | Share a single deployment across many adapters | | **Best for** | Production workloads requiring maximum performance | Experimentation, A/B testing, or serving many variants of the same base model | If you only need to serve a single trained model, **live merge is the recommended approach**. It delivers the best performance with the simplest setup. ## Live merge deployment Live merge is the simplest way to deploy a trained model. Fireworks automatically merges the LoRA weights into the base model at deployment time, producing a model that performs identically to a natively trained model with no inference overhead. ### How it works When you deploy a LoRA model directly, Fireworks: 1. Takes your LoRA adapter weights and the base model 2. Merges them into a single set of weights at deployment time 3. Serves the merged model as a standalone deployment The result is a deployment that is indistinguishable from a fully trained model in terms of latency, throughput, and memory usage. ### Deploy with live merge List shapes for the LoRA's base model, then deploy your trained model with one: ```bash theme={null} firectl deployment-shape-version list \ --base-model "accounts//models/" firectl deployment create "accounts//models/" \ --deployment-shape ``` Copy `` from the `SHAPE NAME (version-id)` column (the resource name before the parenthesized version ID). Your deployment will be ready to use once it completes, with performance that matches the base model. ### Sending requests Send inference requests to your live-merge deployment by referencing the deployment directly: ```python theme={null} from fireworks import Fireworks client = Fireworks() response = client.chat.completions.create( model="accounts//models/", messages=[{"role": "user", "content": "Hello!"}] ) print(response.choices[0].message.content) ``` ```bash theme={null} curl https://api.fireworks.ai/inference/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $FIREWORKS_API_KEY" \ -d '{ "model": "accounts//models/", "messages": [ { "role": "user", "content": "Hello!" } ] }' ``` ### When to use live merge * You need maximum inference performance (latency and throughput matching the base model) * You are serving a single trained model in production * You want the simplest possible deployment workflow ## Multi-LoRA deployment Multi-LoRA lets you load multiple LoRA adapters onto a single base model deployment. This is useful when you have several trained variants of the same base model and want to share GPU resources across them rather than creating a separate deployment for each. ### How it works With multi-LoRA: 1. You deploy the base model with addon support enabled 2. You load one or more LoRA adapters onto the running deployment 3. At inference time, the correct adapter is selected and applied dynamically based on the model specified in the request Because adapters are applied dynamically rather than merged, there is some performance overhead compared to live merge. This overhead increases with higher request concurrency. ### LoRA addon shape compatibility Not all deployment shapes support LoRA addons. **FP8 and FP4 quantized shapes do not support `--enable-addons`.** | Precision | `--enable-addons` supported? | | --------- | ---------------------------- | | BF16 | ✅ Yes | | FP8 | ❌ No | | FP4 | ❌ No | Many base models default to FP8 or FP4 shapes. If you need LoRA addon inference on one of these models, you have two options: **Option 1 — Use a BF16 deployment shape** ```bash theme={null} # List available shapes for your model firectl deployment-shape-version list --base-model accounts/fireworks/models/ # Create deployment with a BF16 shape and addons enabled firectl deployment create "accounts/fireworks/models/" \ --deployment-shape \ --enable-addons ``` **Option 2 — Merge the adapter into a standalone model** If no BF16 addon-compatible shape is available, use [live merge](#live-merge-deployment) (recommended for a single adapter) or merge the LoRA into a standalone Fireworks model, then deploy that merged model without `--enable-addons`. See [Uploading custom models](/models/uploading-custom-models#importing-trained-models) and [`firectl model create`](/tools-sdks/firectl/commands/model-create). `"addons cannot be enabled with quantized precisions (FP8/FP4)"` — your model's default shape is quantized; use Option 1 or 2 above. `"the deployment shape version does not exist or you do not have access to it"` — the shape you requested is not available on your account; contact support. ### Deploy with multi-LoRA Deployments for multi-LoRA serving must use a deployment shape. Do not create this deployment without `--deployment-shape` — deployments without a shape skip validation and are the most common cause of failed deployment creations, and the unshaped path may be deprecated in the future. See [Deployment shapes](/guides/ondemand-deployments#deployment-shapes). Deploy the base model with addons enabled, using a BF16 [deployment shape](/guides/ondemand-deployments#deployment-shapes) (find one with `firectl deployment-shape-version list --base-model accounts/fireworks/models/`): ```bash theme={null} firectl deployment create "accounts/fireworks/models/" \ --deployment-shape \ --enable-addons ``` Once the deployment is ready, load your LoRA models onto the deployment: ```bash theme={null} firectl load-lora --deployment ``` Repeat this command for each LoRA adapter you want to load. ### Sending requests To route inference requests to a specific LoRA adapter on a multi-LoRA deployment, set the `model` field to `#`. The `#` separator tells Fireworks to route the request to the specified adapter on the given deployment. **Deprecation notice:** The `deployedModel` request key for routing to LoRA addons is deprecated and will not be supported for any new deployments. Use the `model` field with the `#` format shown below. ```python theme={null} from fireworks import Fireworks client = Fireworks() response = client.chat.completions.create( model="accounts//models/#accounts//deployments/", messages=[{"role": "user", "content": "Hello!"}] ) print(response.choices[0].message.content) ``` ```python theme={null} import os from openai import OpenAI client = OpenAI( api_key=os.environ.get("FIREWORKS_API_KEY"), base_url="https://api.fireworks.ai/inference/v1" ) response = client.chat.completions.create( model="accounts//models/#accounts//deployments/", messages=[{"role": "user", "content": "Hello!"}] ) print(response.choices[0].message.content) ``` ```javascript theme={null} import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.FIREWORKS_API_KEY, baseURL: "https://api.fireworks.ai/inference/v1", }); const response = await client.chat.completions.create({ model: "accounts//models/#accounts//deployments/", messages: [ { role: "user", content: "Hello!", }, ], }); console.log(response.choices[0].message.content); ``` ```bash theme={null} curl https://api.fireworks.ai/inference/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $FIREWORKS_API_KEY" \ -d '{ "model": "accounts//models/#accounts//deployments/", "messages": [ { "role": "user", "content": "Hello!" } ] }' ``` ### When to use multi-LoRA * You need to serve multiple trained models based on the same base model * You want to maximize GPU utilization by sharing a single deployment * You are running experiments or A/B tests across multiple trained variants * You can accept some performance overhead compared to live merge ## Downloading model weights You can download your trained weights from Fireworks to inspect them, extend the context locally, or serve them outside the platform. There are two things you might want: the **LoRA adapter** on its own, or the **merged (base + adapter) model**. ### Download the LoRA adapter LoRA adapters are listed alongside models in `firectl model list` (denoted with the type `HF_PEFT_ADDON`). Download one with the same command used for any model: ```bash theme={null} firectl model download /path/to/checkpoint/ ``` See [`firectl model download`](/tools-sdks/firectl/commands/model-download) for flags. The adapter alone is not enough to run inference. You also need the matching base model. The adapter was trained against a specific base (for example, a vendor checkpoint that may differ from the public Hugging Face weights), so pair the adapter with the exact base it was trained on. If you are unsure which base was used, ask your Fireworks contact before assuming the public Hugging Face weights are identical. ### Download the merged (base + adapter) model On the platform, **the merge happens on the fly at deployment time** (live merge), so serving a trained model does not require a standalone merged file. To produce a merged copy you can run off-platform, download the base and the adapter, then merge them locally in BF16 with PEFT: 1. Download the base model with `firectl model download`. 2. Download the LoRA adapter with `firectl model download`. 3. Load the base model, wrap it with `PeftModel` to load the adapter, call `merge_and_unload()`, and save the merged model. ```python theme={null} from peft import PeftModel from transformers import AutoModelForCausalLM, AutoTokenizer base = AutoModelForCausalLM.from_pretrained("/path/to/base", torch_dtype="bfloat16") merged = PeftModel.from_pretrained(base, "/path/to/adapter").merge_and_unload() merged.save_pretrained("/path/to/merged") AutoTokenizer.from_pretrained("/path/to/base").save_pretrained("/path/to/merged") ``` Merge in BF16; if you need quantized (FP8) weights, quantize the merged result afterward (see FP8 below). ### FP8 (and other quantized) merged weights If you want an FP8 merged model to run off-platform, merge in BF16 first, then quantize the merged result yourself. For reference, the on-platform serving path is: 1. Keep the BF16 base + BF16 LoRA adapter. 2. At deploy, merge in BF16: `W' = W_bf16 + (B·A)_bf16`. 3. Quantize the merged BF16 weights to FP8 on the fly at serving time. To reproduce this locally, merge in BF16 first, then quantize the merged weights to FP8. **Match the original quantization scheme when serving locally.** Use the same quantization the base model ships with on Hugging Face rather than a generic FP8 cast. For example, a GLM-family MoE base uses **blockwise FP8** for its MoE weights, and casting with a different scheme can silently degrade quality. When in doubt, keep the merged model in BF16 and let your serving stack quantize. ## LoRA performance ### Why multi-LoRA can feel slower than the base model Three factors explain most latency gaps: 1. **Unmerged adapters** — dynamic LoRA application adds compute on each request. [Live merge](#live-merge-deployment) removes this entirely. 2. **Speculative decoding** — base deployments often use SD; trained LoRA deployments may not unless you configure a custom draft model. 3. **Concurrency** — multi-LoRA overhead shows up mainly under sustained load (see below). ### Live merge vs multi-LoRA (performance) | | **Live merge** | **Multi-LoRA** | | ----------------------- | ------------------------------- | --------------------------------------------------- | | Latency / throughput | Matches base model | TTFT often +10–30%; lower max throughput under load | | Adapter count at deploy | One adapter per deployment | Many adapters on one base deployment | | Best for | Production single-model serving | A/B tests, many variants, shared GPU | The number of adapters registered on a deployment has **little effect** on per-request performance; concurrency and merge mode matter more. ### Speculative decoding Training and deploying a **custom draft model** for your trained setup can match or beat base-model latency. Speculative decoding for trained models is an enterprise feature — contact Fireworks for access. ## Troubleshooting ### Silent deployment-shape drop (multi-LoRA lands on the default serving image) This is a subtle failure mode specific to multi-LoRA deployments. If the deployment shape you request is not **validated for the exact base model version** you are deploying, deployment create does **not** return an error. The unvalidated shape is **silently dropped**, and the deployment quietly falls back to the **default serving image**. That default image's addon loader then rejects addon (multi-LoRA) checkpoints, so you end up seeing base-model behavior or an addon-load failure with no obvious cause. This differs from training, where an unvalidated shape returns a **400**. At deployment create time there is no such error. The `skip_shape_validation` override is superuser-only, so you cannot force an unvalidated shape through yourself. The shape must be validated for your exact model version. **Why it happens.** A deployment shape is validated against a specific base model version, not just a model family. A shape such as `deploymentShapes/-h200-multilora` may have validated versions that bind one model version but **not** another version of the same family. Deploying a model version that no validated shape version binds triggers the silent drop. **How to detect it.** Before (or after) creating the deployment, confirm a validated shape version exists for the **exact** model version you are deploying, not just the family. List the validated shape versions for your model: ```bash theme={null} firectl deployment-shape-version list --base-model accounts//models/ ``` Or query the API directly with the `latest_validated=true` filter (see [List Deployment Shape Versions](/api-reference/list-deployment-shape-versions)). For general shape discovery — "which shapes work with this model?" — use [Match Deployment Shape Versions](/api-reference/match-deployment-shape-versions) instead; the filter query here is for checking which exact model version each validated shape version binds: ```bash theme={null} curl -s "https://api.fireworks.ai/v1/accounts/-/deploymentShapes/-/versions?filter=snapshot.base_model%3D%22accounts%2F%2Fmodels%2F%22%20AND%20latest_validated%3Dtrue&order_by=create_time%20desc" \ -H "Authorization: Bearer $FIREWORKS_API_KEY" | jq . ``` Signs you have hit this failure mode: * No validated shape version lists your exact model version under `snapshot.base_model` (every validated version binds a **different** version of the same model family). * The deployment comes up serving base-model behavior instead of your adapter. * Loading an addon (a Tinker or other LoRA checkpoint) is rejected even though the shape you requested supports addons. **How to avoid landing on the default serving image.** * Deploy only against a shape version that is validated for your **exact** model version, confirmed with the check above. * If no validated shape version binds your model version, do **not** rely on the shape argument being honored. Ask your Fireworks account team to **validate a deployment shape version for that model version** first. A shape validated only for a sibling version will be dropped. * As an alternative that avoids multi-LoRA and the addon loader entirely, [live merge](#live-merge-deployment) the single adapter, which does not go through the addon path. ## Next steps Deployment configuration, scaling, and hardware Upload LoRA models trained outside Fireworks # Preference Optimization with DPO or ORPO Source: https://docs.fireworks.ai/fine-tuning/dpo-fine-tuning Train on preferred and non-preferred response pairs using managed DPO or ORPO. Preference optimization trains models on pairs of preferred and non-preferred responses to the same prompt. Managed jobs support two objectives: * **DPO** compares the policy against a reference model. * **ORPO** combines supervised and preference objectives without a separate reference model. Use either method for: * Aligning model outputs with brand voice, tone, or style guidelines * Reducing hallucinations or incorrect reasoning patterns * Improving response quality where there's no single "correct" answer * Teaching models to follow specific formatting or structural preferences ## Training with DPO or ORPO Datasets must adhere strictly to the JSONL format, where each line represents a complete JSON-formatted training example. **Minimum Requirements:** * **Minimum examples needed:** 3 * **Maximum examples:** Up to 3 million examples per dataset * **File format:** JSONL (each line is a valid JSON object) * **Dataset Schema:** Each training sample must include the following fields: * An `input` field containing a `messages` array, where each message is an object with two fields: * `role`: one of `system`, `user`, or `assistant` * `content`: a string representing the message content * A `preferred_output` field containing an assistant message with an ideal response * A `non_preferred_output` field containing an assistant message with a suboptimal response Here’s an example conversation dataset (one training example): ```json einstein_dpo.jsonl theme={null} { "input": { "messages": [ { "role": "user", "content": "What is Einstein famous for?" } ], "tools": [] }, "preferred_output": [ { "role": "assistant", "content": "Einstein is renowned for his theory of relativity, especially the equation E=mc²." } ], "non_preferred_output": [ { "role": "assistant", "content": "He was a famous scientist." } ] } ``` We currently only support one-turn conversations for each example, where the preferred and non-preferred messages need to be the last assistant message. Save this dataset as jsonl file locally, for example `einstein_dpo.jsonl`. There are a couple ways to upload the dataset to Fireworks platform for training: `firectl`, `Restful API` , `builder SDK` or `UI`. * You can simply navigate to the dataset tab, click `Create Dataset` and follow the wizard. Dataset Pn * Upload dataset using `firectl` ```bash theme={null} firectl dataset create /path/to/file.jsonl ``` You need to make two separate HTTP requests. One for creating the dataset entry and one for uploading the dataset. Full reference here: [Create dataset](/api-reference/create-dataset). Note that the `exampleCount` parameter needs to be provided by the client. ```jsx theme={null} // Create Dataset Entry const createDatasetPayload = { datasetId: "trader-poe-sample-data", dataset: { userUploaded: {} } // Additional params such as exampleCount }; const urlCreateDataset = `${BASE_URL}/datasets`; const response = await fetch(urlCreateDataset, { method: "POST", headers: HEADERS_WITH_CONTENT_TYPE, body: JSON.stringify(createDatasetPayload) }); ``` ```jsx theme={null} // Upload JSONL file const urlUpload = `${BASE_URL}/datasets/${DATASET_ID}:upload`; const files = new FormData(); files.append("file", localFileInput.files[0]); const uploadResponse = await fetch(urlUpload, { method: "POST", headers: HEADERS, body: files }); ``` While all of the above approaches should work, `UI` is more suitable for smaller datasets `< 500MB` while `firectl` might work better for bigger datasets. Ensure the dataset ID conforms to the [resource id restrictions](/getting-started/concepts#resource-names-and-ids). ```bash theme={null} firectl dpo-job create \ --loss-method DPO \ --base-model accounts/account-id/models/base-model-id \ --dataset accounts/my-account-id/datasets/my-dataset-id \ --output-model new-model-id ``` For reservation capacity: add `--use-reservation` with firectl (default off). REST and the Python SDK (`>=1.2.8`) default to reservation-first placement; set `useReservation: false` or `use_reservation=False` to opt out. For full-parameter DPO, policy and dedicated reference trainers try independently. For ORPO, use the same preference dataset and select the ORPO objective: ```bash theme={null} firectl dpo-job create \ --loss-method ORPO \ --orpo-lambda \ --base-model accounts/account-id/models/base-model-id \ --dataset accounts/my-account-id/datasets/my-dataset-id \ --output-model new-model-id ``` Choose a base model that [Models](/fine-tuning/models) marks as DPO-enabled, and a shape published for it. ```bash theme={null} firectl dpo-job get dpo-job-id ``` Once the job is complete, the `STATE` will be set to `JOB_STATE_COMPLETED`, and the trained model can be deployed. Once training completes, you can create a deployment to interact with the trained model. Refer to [deploying a trained model](/fine-tuning/fine-tuning-models#deploying-a-trained-model) for more details. ## Next Steps Explore other training methods to improve model output for different use cases. Train models on input-output examples to improve task-specific performance. Optimize models using AI feedback for complex reasoning and decision-making. Train vision-language models to understand both images and text. # Evaluating Trained Models Source: https://docs.fireworks.ai/fine-tuning/evaluating-fine-tuned-models Evaluate a trained model before you create a production deployment. After training, evaluate your model before you hold dedicated capacity for production serving. Choose an evaluation path based on the artifact you have and whether the training session is still active. These workflows are for **training evals and other non-production workloads only**. Do not send production or latency-sensitive traffic through them. For production serving after eval, create an on-demand deployment. See [Deploying Trained Models](/fine-tuning/deploying-loras). ## Which approach to use Use the path that matches your current training stage: * **Your serverless training session is still active:** use in-session sampling. * **You have a promoted model ID:** use a preemptible deployment. This works regardless of whether the LoRA was trained with serverless, dedicated, or managed training, or imported. * **Your dedicated training run is still active:** use its inference deployment and refresh it from sampler snapshots. See [Dedicated training and sampling](/fine-tuning/training-api/dedicated#training-and-sampling). | | **In-session sampling** | **Preemptible deployment** | | ------------------ | --------------------------------------------------------- | --------------------------------------------------------------------- | | **Best for** | Quick checks during an active serverless training session | Evaluating a promoted model without reserving dedicated GPUs | | **Training path** | Serverless Training API only | Any training path | | **Artifact** | Sampler checkpoint from `save_weights_for_sampler` | Promoted model (`accounts//models/`) | | **API** | Training SDK `sampler.sample()` | Chat Completions or Fireworks SDK | | **Session bound?** | Yes | No | ## In-session sampling (serverless training) In-session sampling is available only during an active [serverless training](/fine-tuning/training-api/serverless) session, and the base model must be available in the [serverless pool](/fine-tuning/models). It does not evaluate an adapter produced by dedicated training after that run ends. There is no serverless chat endpoint for your adapter. Open a **sampling client** bound to a sampler checkpoint. `sampler.sample()` generates completions from that checkpoint, which you score with your own metric. Use the **sampler checkpoint** returned by `save_weights_for_sampler`, not a promoted model resource (`accounts//models/`). Promoted models are for on-demand deployment and cannot be passed to `create_sampling_client`. The following save-and-sample sequence comes from the [serverless quickstart](/fine-tuning/training-api/serverless#step-4-train-checkpoint-and-sample) and the cookbook [`serverless_rl` example](https://github.com/fw-ai/cookbook/blob/main/training/examples/serverless_rl/countdown_rl.py). Set up `prompt`, `tokenizer`, and `params` as shown in that example. ```python theme={null} snapshot = training_client.save_weights_for_sampler("eval").result().path sampler = service.create_sampling_client(model_path=snapshot, tokenizer=tokenizer) try: result = sampler.sample( prompt=prompt, num_samples=1, sampling_params=params, ).result() for seq in result.sequences or []: tokens = list(seq.tokens or []) completion = get_text_content(renderer.parse_response(tokens)[0]) # Score `completion` against your held-out label or grader. finally: sampler.close() ``` `sampler.sample(...)` is the evaluation call. Repeat it over held-out prompts, then close the sampler. The Countdown example scores with `composite_reward`; replace that with your evaluation metric. For checkpoint and promotion details, see [Saving and loading checkpoints](/fine-tuning/training-api/serverless#saving-and-loading-checkpoints) on the serverless training page. Sampler checkpoints live in the training session. If the session is gone, you cannot open a sampling client from that checkpoint. Promote checkpoints you need to retain, then evaluate the promoted model with a [preemptible deployment](#preemptible-deployment) below. ## Preemptible deployment If you want to evaluate a promoted model without holding dedicated on-demand capacity, create a **preemptible deployment**. It borrows idle reserved GPU capacity instead of reserving GPUs exclusively for you. For LoRA, this includes adapters trained with serverless, dedicated, or managed training, as well as imported adapters. Point the deployment at your promoted fine-tuned model ID, not the base model. It can be reclaimed (preempted) at any time. Fireworks does not guarantee how many GPUs are available or how long the deployment stays up, but in practice it typically lasts long enough to finish a training eval. ### How it works Passing `--preemptible` to `firectl deployment create` opts the deployment into capacity borrowing: * The deployment runs on reserved nodes that are currently idle. * When the capacity owner needs those GPUs back, your deployment can be preempted. Because it borrows idle capacity, you do not need to hold dedicated on-demand capacity for the duration of the eval. ### Requirements `--preemptible` takes effect only on **firectl 1.7.26 or newer**. Check with `firectl version`. The flag is not present in older builds. Upgrade if you are below 1.7.26. ### Behavior * **Training evals only.** A preemptible deployment can be preempted mid-request. Treat disappearance as a normal outcome, not an error. * **`--preemptible` is immutable.** It is set at create time and cannot be toggled on or off afterward. To change it, delete the deployment and create a new one. * **Clean up when done.** Delete the deployment after your eval so you stop holding the borrowed capacity. ### Create the deployment ```bash theme={null} firectl deployment create accounts//models/ \ --deployment-id \ --display-name \ --deployment-shape \ --min-replica-count 1 \ --max-replica-count 1 \ --preemptible ``` Replace the placeholders: * ``: the trained model to eval, not a base model. * `` / ``: a name of your choice for the eval deployment. * ``: the deployment shape to use for that model. ### Worked example ```bash theme={null} firectl deployment create accounts//models/ \ -a \ --deployment-id -eval \ --display-name -eval \ --deployment-shape \ --min-replica-count 1 \ --max-replica-count 1 \ --preemptible ``` ### Run the eval and tear down Check that the deployment is ready, then send eval requests to the trained model: ```bash theme={null} firectl deployment get -a ``` ```bash theme={null} curl https://api.fireworks.ai/inference/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $FIREWORKS_API_KEY" \ -d '{ "model": "accounts//models/", "messages": [ { "role": "user", "content": "Hello!" } ] }' ``` When the evaluation is finished, delete the deployment to release the borrowed capacity: ```bash theme={null} firectl deployment delete -a ``` For more on preemptible capacity and guarantees, see [Preemptible deployments](/guides/ondemand-deployments#preemptible-deployments-eval-batch) in the on-demand deployments guide. ## Next steps Live merge or multi-LoRA for production serving # Supervised Fine-Tuning - Text Source: https://docs.fireworks.ai/fine-tuning/fine-tuning-models This guide will focus on using supervised fine-tuning to train a model and deploy it to an on-demand (dedicated) deployment, which is the only supported method for serving trained models. For the full list of base models supported by managed training (SFT, DPO, and RFT) and their max context lengths, see [Models](/fine-tuning/models). ## Fine-tuning a model using SFT You can confirm that a base model is available to train by looking for the `Tunable` tag in the model library or by using: ```bash theme={null} firectl model get -a fireworks ``` And looking for `Tunable: true`. Custom uploaded base models must include a corresponding Hugging Face URL before Fireworks can determine whether they are tunable. Fireworks uses the URL to infer the training renderer and find compatible training shapes. The tunability refresh runs asynchronously about every 30 minutes, so a newly uploaded or updated custom model may take up to 30 minutes to show `Tunable: true`. Some base models cannot be tuned on Fireworks (`Tunable: false`) but still list support for LoRA (`Supports Lora: true`). This means that users can tune a LoRA for this base model on a separate platform and upload it to Fireworks for inference. Consult [importing trained models](/models/uploading-custom-models#importing-trained-models) for more information. Fireworks uses the **OpenAI-compatible chat completion format** for SFT training data. If you already have datasets formatted for OpenAI training, they work on Fireworks with no changes needed. Datasets must be in JSONL format, where each line represents a complete JSON-formatted training example. Make sure your data conforms to the following restrictions: * **Minimum examples:** 3 * **Maximum examples:** 3 million per dataset * **File format:** `.jsonl` * **Message schema:** Each training sample must include a messages array, where each message is an object with two fields: * `role`: one of `system`, `user`, or `assistant`. A message with the `system` role is optional, but if specified, it must be the first message of the conversation * `content`: the message content. This can be either a plain string **or** a list of content parts in the OpenAI chat completions style, e.g. `[{"type": "text", "text": "..."}]`. Both forms are accepted, and you can mix them freely across messages and even within the same dataset * `weight`: optional key with value to be configured in either 0 or 1. message will be skipped if value is set to 0 * **Sample weight:** Optional key `weight` at the root of the JSON object. It can be any floating point number (positive, negative, or 0) and is used as a loss multiplier for tokens in that sample. If used, this field must be present in all samples in the dataset. Here is an example conversation dataset: ```json theme={null} { "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What is the capital of France?"}, {"role": "assistant", "content": "Paris."} ] } { "messages": [ {"role": "user", "content": "What is 1+1?"}, {"role": "assistant", "content": "2", "weight": 0}, {"role": "user", "content": "Now what is 2+2?"}, {"role": "assistant", "content": "4"} ] } ``` #### OpenAI-style structured content In addition to plain strings, `content` may also be a list of content parts following the OpenAI chat completions format. For text training, use `{"type": "text", "text": "..."}` parts. This is convenient if you already produce data in the OpenAI chat completions shape, or if you generate datasets with the OpenAI SDK. The string form and the list form are equivalent for text models, and you can mix them within the same file (and even within the same conversation): ```json theme={null} {"messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": [{"type": "text", "text": "What is the capital of France?"}]}, {"role": "assistant", "content": [{"type": "text", "text": "Paris."}]}]} {"messages": [{"role": "user", "content": [{"type": "text", "text": "What is 1+1?"}]}, {"role": "assistant", "content": [{"type": "text", "text": "2"}], "weight": 0}, {"role": "user", "content": "Now what is 2+2?"}, {"role": "assistant", "content": "4"}]} {"messages": [{"role": "user", "content": [{"type": "text", "text": "Say hello "}, {"type": "text", "text": "in French."}]}, {"role": "assistant", "content": "Bonjour."}]} ``` All keys you can use with the string form — including the per-message `weight` and `reasoning_content` — work the same way with the list form. When a single message contains multiple text parts (as in the third example above), the parts are concatenated when the chat template is applied. For text-only training, only `{"type": "text", ...}` parts are used; image parts are reserved for [vision training](/fine-tuning/fine-tuning-models#vision-training). Here is an example conversation dataset with sample weights: ```json theme={null} { "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What is the capital of France?"}, {"role": "assistant", "content": "Paris."} ], "weight": 0.5 } { "messages": [ {"role": "user", "content": "What is 1+1?"}, {"role": "assistant", "content": "2", "weight": 0}, {"role": "user", "content": "Now what is 2+2?"}, {"role": "assistant", "content": "4"} ], "weight": 1.0 } ``` We also support function calling dataset with a list of tools. An example would look like: ```json theme={null} { "tools": [ { "type": "function", "function": { "name": "get_car_specs", "description": "Fetches detailed specifications for a car based on the given trim ID.", "parameters": { "trimid": { "description": "The trim ID of the car for which to retrieve specifications.", "type": "int", "default": "" } } } }, ], "messages": [ { "role": "user", "content": "What is the specs of the car with trim 121?" }, { "role": "assistant", "tool_calls": [ { "type": "function", "function": { "name": "get_car_specs", "arguments": "{\"trimid\": 121}" } } ] } ] } ``` #### Thinking traces For managed supervised fine-tuning (SFT), you can include thinking traces for assistant turns in `reasoning_content`. Thinking traces are optional, but ideally each assistant turn includes one. For example: ```json theme={null} { "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What is the capital of France?"}, {"role": "assistant", "content": "Paris.", "reasoning_content": "The user is asking about the capital city of France, it should be Paris."} ] } { "messages": [ {"role": "user", "content": "What is 1+1?"}, {"role": "assistant", "content": "2", "weight": 0, "reasoning_content": "The user is asking about the result of 1+1, the answer is 2."}, {"role": "user", "content": "Now what is 2+2?"}, {"role": "assistant", "content": "4", "reasoning_content": "The user is asking about the result of 2+2, the answer should be 4."} ] } ``` How earlier thinking appears in later training contexts depends on the base model and its thinking-history mode. This is separate from enabling or disabling thinking generation. Some models offer both Interleaved and Preserved history, some have one fixed mode, and DeepSeek V4 derives its behavior from whether each dataset row declares tools. Compare every supported model, understand per-user-turn unrolling, configure the job field, and preview what the trainer will see. There are a couple ways to upload the dataset to Fireworks platform for training: `firectl`, `Restful API` , `builder SDK` or `UI`. * You can simply navigate to the dataset tab, click `Create Dataset` and follow the wizard. Dataset Pn ```bash theme={null} firectl dataset create /path/to/jsonl/file ``` You need to make two separate HTTP requests. One for creating the dataset entry and one for uploading the dataset. Full reference here: [Create dataset](/api-reference/create-dataset). Note that the `exampleCount` parameter needs to be provided by the client. ```jsx theme={null} // Create Dataset Entry const createDatasetPayload = { datasetId: "trader-poe-sample-data", dataset: { userUploaded: {} } // Additional params such as exampleCount }; const urlCreateDataset = `${BASE_URL}/datasets`; const response = await fetch(urlCreateDataset, { method: "POST", headers: HEADERS_WITH_CONTENT_TYPE, body: JSON.stringify(createDatasetPayload) }); ``` ```jsx theme={null} // Upload JSONL file const urlUpload = `${BASE_URL}/datasets/${DATASET_ID}:upload`; const files = new FormData(); files.append("file", localFileInput.files[0]); const uploadResponse = await fetch(urlUpload, { method: "POST", headers: HEADERS, body: files }); ``` While all of the above approaches should work, `UI` is more suitable for smaller datasets `< 500MB` while `firectl` might work better for bigger datasets. Ensure the dataset ID conforms to the [resource id restrictions](/getting-started/concepts#resource-names-and-ids). There are also a couple ways to launch the training jobs. We highly recommend creating supervised fine-tuning jobs via `UI` . Simply navigate to the `Fine-Tuning` tab, click `Fine-Tune a Model` and follow the wizard from there. You can even pick a LoRA model to start the training for continued training. Training Pn Create Sftj Pn Ensure the trained model ID conforms to the [resource id restrictions](/getting-started/concepts#resource-names-and-ids). This will return a training job ID. For a full explanation of the settings available to control the training process, including learning rate and epochs, consult [additional managed training job settings](#additional-managed-training-job-settings). ```bash theme={null} firectl sftj create --base-model --dataset --output-model ``` Similar to UI, instead of tuning a base model, you can also start tuning from a previous LoRA model using ```bash theme={null} firectl sftj create --warm-start-from --dataset --output-model ``` Notice that we use `--warm-start-from` instead of `--base-model` when creating this job. With `UI`, once the job is created, it will show in the list of jobs. Clicking to view the job details to monitor the job progress. Sftj Details Pn If the trained model appears to learn the wrong text or ignore the expected assistant response, use **Render Samples** on the job details page to inspect the rendered token IDs and loss masks. See [Debug SFT tokenization](/fine-tuning/fine-tuning-models#debug-sft-tokenization). With `firectl`, you can monitor the progress of the tuning job by running ```bash theme={null} firectl sftj get ``` Once the job successfully completes, you will see the new LoRA model in your model list ```bash theme={null} firectl model list ``` For a complete Python SDK example that demonstrates the full workflow (creating datasets, uploading files, and launching a supervised fine-tuning job), see the [Python SDK workflow example](https://github.com/fw-ai-external/python-sdk/blob/main/examples/sftj_workflow.py). ## Deploying a trained model After training completes, [evaluate the model](/fine-tuning/evaluating-fine-tuned-models) before you hold dedicated capacity for production serving. To deploy for inference: ```bash theme={null} firectl deployment create ``` This creates a dedicated deployment with performance matching the base model. For more details on deploying trained models, including multi-LoRA deployments, see the [Deploying Trained Models guide](/fine-tuning/deploying-loras). ## Additional managed training job settings Additional tuning settings are available when starting an SFT or preference (DPO/ORPO) job. All of the settings below are optional and have reasonable defaults. For settings that affect tuning quality, such as `epochs` and `learning_rate`, use the defaults first and change them only when the results indicate a clear need. Examples use SFT unless otherwise noted. By default, the training job will run evaluation by running the trained model against an evaluation set that's created by automatically carving out a portion of your training set. You have the option to explicitly specify a separate evaluation dataset to use instead of carving out training data. `evaluation_dataset`: The ID of a separate dataset to use for evaluation. Must be pre-uploaded via firectl ```shell theme={null} firectl sftj create \ --evaluation-dataset my-eval-set \ --base-model MY_BASE_MODEL \ --dataset cancerset \ --output-model my-tuned-model ``` Depending on the size of the model, the default context size will be different. For most models, the default context size is >= 32768. Training examples will be cut-off at 32768 tokens. Usually you do not need to set the max context length unless out of memory error is encountered with higher lora rank and large max context length. ```shell theme={null} firectl sftj create \ --max-context-length 65536 \ --base-model MY_BASE_MODEL \ --dataset cancerset \ --output-model my-tuned-model ``` Managed SFT and preference tuning use sample-count batching. `batch_size_samples` is the number of SFT samples or preference pairs included in each optimizer step. It is independent of `max_context_length`, which limits the token length of each sample. The UI defaults are 32 samples for SFT and 4 preference pairs for DPO/ORPO. ```shell theme={null} firectl sftj create \ --batch-size-samples 32 \ --base-model MY_BASE_MODEL \ --dataset cancerset \ --output-model my-tuned-model ``` Epochs are the number of passes over the training data. Our default value is 1. If the model does not follow the training data as much as expected, increase the number of epochs by 1 or 2. Non-integer values are supported. **Note: we set a max value of 3 million dataset examples × epochs** ```shell theme={null} firectl sftj create \ --epochs 2.0 \ --base-model MY_BASE_MODEL \ --dataset cancerset \ --output-model my-tuned-model ``` Learning rate controls how fast the model updates from data. We generally do not recommend changing learning rate. The default value is automatically based on your selected model. ```shell theme={null} firectl sftj create \ --learning-rate 0.0001 \ --base-model MY_BASE_MODEL \ --dataset cancerset \ --output-model my-tuned-model ``` Learning rate warmup steps controls the number of training steps during which the learning rate will be linearly ramped up to the set learning rate. ```shell theme={null} firectl sftj create \ --learning-rate 0.0001 \ --learning-rate-warmup-steps 200 \ --base-model MY_BASE_MODEL \ --dataset cancerset \ --output-model my-tuned-model ``` Configure how the learning rate changes over training. Supported schedulers are `constant`, `linear`, and `cosine`. When unset, the trainer uses its legacy constant schedule. The same flags apply to SFT and preference tuning jobs (DPO/ORPO). For `linear` and `cosine`, you can optionally set: * `--learning-rate-min-lr-ratio`: minimum learning rate as a fraction of `--learning-rate` (0 to 1) * `--learning-rate-decay-ratio`: fraction of total training steps over which to decay; `0` decays over the full run ```shell theme={null} firectl sftj create \ --base-model MY_BASE_MODEL \ --dataset cancerset \ --output-model my-tuned-model \ --learning-rate 0.0001 \ --learning-rate-warmup-steps 10 \ --learning-rate-scheduler cosine \ --learning-rate-min-lr-ratio 0.1 \ --learning-rate-decay-ratio 0.8 ``` Via the REST API, pass an `lrScheduler` object with one of `constant`, `linear`, or `cosine`: ```javascript theme={null} const payload = { supervisedFineTuningJob: { baseModel: "accounts/my-account/models/MY_BASE_MODEL", dataset: "accounts/my-account/datasets/cancerset", outputModel: "accounts/my-account/models/my-tuned-model", learningRate: 0.0001, learningRateWarmupSteps: 10, lrScheduler: { cosine: { minLrRatio: 0.1, decayRatio: 0.8 } } } }; ``` LoRA rank refers to the number of parameters that will be tuned in your LoRA add-on. Higher LoRA rank increases the amount of information that can be captured while tuning. LoRA rank must be a power of 2 up to 32. Our default value is 8. ```shell theme={null} firectl sftj create \ --lora-rank 16 \ --base-model MY_BASE_MODEL \ --dataset cancerset \ --output-model my-tuned-model ``` The training service integrates with Weights & Biases to provide observability into the tuning process. To use this feature, you must have a Weights & Biases account and have provisioned an API key. ```shell theme={null} firectl sftj create \ --wandb-entity my-org \ --wandb-api-key xxx \ --wandb-project "My Project" \ --base-model MY_BASE_MODEL \ --dataset cancerset \ --output-model my-tuned-model ``` By default, the training job will generate a random unique ID for the model. This ID is used to refer to the model at inference time. You can optionally specify a custom ID, within [ID constraints](/getting-started/concepts#resource-names-and-ids). ```shell theme={null} firectl sftj create \ --output-model my-model \ --base-model MY_BASE_MODEL \ --dataset cancerset ``` By default, the training job will generate a random unique ID for the training job. You can optionally choose a custom ID. ```shell theme={null} firectl sftj create \ --job-id my-fine-tuning-job \ --base-model MY_BASE_MODEL \ --dataset cancerset \ --output-model my-tuned-model ``` Try your account's reservation capacity before falling back to shared trainer capacity. * **firectl**: add `--use-reservation` (default off). * **REST / Python SDK** (`>=1.2.8`): defaults to `useReservation: true` / `use_reservation=True`. Set to `false` to opt out. ```shell theme={null} firectl sftj create \ --use-reservation \ --base-model MY_BASE_MODEL \ --dataset cancerset \ --output-model my-tuned-model ``` ### Deprecated parameters These parameters are deprecated. Do not include them in new managed training requests. The wire fields remain present so existing resources can still be read, but Training V2 rejects or ignores non-default values as described below. | Proto / Python field | Former or legacy `firectl` flag | Affected jobs | Migration behavior | | ----------------------------- | ----------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `batch_size` | `--batch-size` | SFT and DPO/ORPO Training V2 | Training V2 rejects nonzero values; use `batch_size_samples` / `--batch-size-samples`. RFT and RLOR V1 paths are not affected: they still use `batch_size` as the packed-token budget alongside the optional `batch_size_samples` control. | | `gradient_accumulation_steps` | `--gradient-accumulation-steps` | SFT, DPO/ORPO, RFT, RLOR trainer | Legacy V1 accumulation control. SFT and DPO/ORPO V2 reject nonzero values. Use `batch_size_samples` to control samples or preference pairs per optimizer step. | | `jinja_template` | — | SFT and shared training config | Training V2 rejects non-empty values. Conversation rendering comes from the base model's registered renderer configuration. | | `early_stop` | `--early-stop` | Managed SFT | Early stopping is not supported by managed training. The CLI flag is no longer exposed; omit the field or leave it `false`. | | `mtp_enabled` | `--mtp-enable` | Managed SFT | MTP training is no longer supported. The CLI flag was removed, and managed training rejects `true`. | | `mtp_num_draft_tokens` | `--mtp-num-draft-tokens` | Managed SFT | Deprecated with MTP support. The CLI flag was removed; leave the field unset (`0`). | | `mtp_freeze_base_model` | `--mtp-freeze-base-model` | Managed SFT | Deprecated with MTP support. The CLI flag was removed; leave the field unset (`false`). | | `extra_values` | `--extra-values` (admin-only legacy flag) | Managed SFT | Legacy V1 Helm overrides. Training V2 rejects a non-empty map. | ## Appendix * `Python SDK` [references](/tools-sdks/python-sdk) * `Restful API` [references](/api-reference/introduction) * `firectl` [references](/tools-sdks/firectl/firectl) * [Complete Python SDK workflow example](https://github.com/fw-ai-external/python-sdk/blob/main/examples/sftj_workflow.py) for a code-only implementation ## Vision training Vision-language SFT uses the same managed job flow as text SFT with multimodal content in `messages`. Confirm VLM support and training shapes in the live [Models](/fine-tuning/models) matrix because modality, method, and shape eligibility are model-specific. Each message `content` is an array of text and `image_url` objects. Images must be base64 data URIs with a MIME type; raw HTTP image URLs are not supported in training datasets. ```json theme={null} { "messages": [ { "role": "user", "content": [ {"type": "text", "text": "What is shown?"}, { "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..." } } ] }, { "role": "assistant", "content": [{"type": "text", "text": "A red bicycle."}] } ] } ``` Multiple images and multi-turn conversations use the same content-array shape. Keep the assistant response you want to train as the final message, upload the JSONL dataset, then create the managed SFT job with a VLM-capable base model. Download remote images and encode them before upload. Keep each MIME prefix accurate (`image/jpeg`, `image/png`, and so on), and validate the rendered sample before starting a paid job. For Training API VLM loops, use a VLM-compatible training shape and the model's processor rather than a text-only tokenizer. The same Training API primitives support multimodal SFT, DPO, and RL datums. Start from the relevant cookbook recipe and verify processor output and loss masks before launch. Shape details: [Training Shapes](/fine-tuning/models#vision-and-multimodal-support). ## Debug SFT tokenization If the model learns the wrong text or ignores assistant turns, the training renderer may not match inference tokenization. 1. In the dashboard, open your SFT job → **Render Samples** to inspect token boundaries and loss masks. 2. Compare rendered tokens against inference for the same prompt. 3. For custom renderers or agent-driven debugging, use the [training skill — renderer verification](https://github.com/fw-ai/cookbook/blob/main/skills/fireworks-training/references/renderer-verification.md). In the REST response, the render preview identifies each datum produced from a source row with `examples[].renderings[].renderedDatums[].datumIndex`. Downloaded **Render Samples** use the legacy `split_index` field. The fields play corresponding roles in different schemas; `split_index` has not been renamed in the downloadable artifact. Common fix: ensure assistant messages you intend to train have non-zero loss weight; system/user turns should be masked out. ### Common findings | What you see | Likely cause | What to do | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Assistant answer tokens have `token_weights` of `0` | The assistant message has `weight: 0`, the sample has zero weight, or the job is configured to train on different content. | Check the original JSONL row and remove unintended weights. | | User or system tokens have positive `token_weights` | The row schema or training configuration is not representing roles as intended. | Verify every message has the correct `role`, and avoid putting assistant text in a `user` message. | | Expected text is missing from `decoded_tokens` | The source row may have been split, truncated, or rendered differently by the model chat template. | Check `split_index`, source line number, and the job's max context length. | | Extra special tokens appear around messages | The selected model renderer is adding chat template markers. | This is often expected. If the markers are wrong for your use case, check that the base model and dataset format match. | | Thinking traces missing from conversation history | The job's thinking-history mode and model renderer decide whether earlier turns' `reasoning_content` is retained. Interleaved removes thinking across user-turn boundaries; Preserved retains it. Datum unrolling is model-specific. | Compare the available modes in the render preview, then verify the created job's mode. See [Thinking history in training](/fine-tuning/thinking-history). | | Token boundaries look surprising | Many tokenizers encode whitespace, Unicode, and byte fallback pieces in non-obvious ways. | Compare with the same Hugging Face tokenizer using `skip_special_tokens=False`. | | The Render Samples row is missing | The job may predate this feature, may have failed before rendering, or may not have captured samples. | Create a new supervised fine-tuning job, or contact support with the job ID if the job should have rendered samples. | # Training Overview Source: https://docs.fireworks.ai/fine-tuning/finetuning-intro Training adapts a base model to your task by training it on your own data, so it learns your formats, tone, tools, and edge cases instead of relying on prompt instructions alone. Fireworks runs the training for you, without the burden of building and maintaining your own GPU or training infrastructure. Training is worth it when you want: * **Higher task quality** - beat a general-purpose model on your specific workload, and often match or exceed a larger closed model. * **Lower latency and cost** - a smaller specialized model can replace a bigger one at a fraction of the per-token cost. * **Consistent behavior** - bake in formats, style, and tool-use so you stop paying for long prompts and few-shot examples on every request. * **Ownership and no infra** - you keep the resulting weights, and Fireworks handles the GPUs, scheduling, and checkpointing. **Coming from OpenAI?** Fireworks uses the same **OpenAI-compatible chat completion format** for training data — the same `messages` array with `role`, `content`, `tool_calls`, and `weight` fields. You can use your existing SFT datasets with no conversion required. See the [SFT dataset format](/fine-tuning/fine-tuning-models#fine-tuning-a-model-using-sft) for the full schema and examples. ## Choose a method Pick a method based on the data or signal you have. All three run as standard jobs on [Managed Training](/fine-tuning/managed-finetuning-intro), or as custom loops you write yourself on the [Training API](/fine-tuning/training-api/introduction). | | SFT | DPO | RL | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Good for** | Classification, extraction, format and tone adherence, distillation | Steering the model toward a goal you cannot measure objectively, such as style, helpfulness, or safety | Tasks where you have no verified outputs to learn from, but you can tell whether an outcome was good or bad. Pushing the model beyond state-of-the-art | | **Data you supply** | Verified input/output pairs, or successful trajectories | Preference pairs, single-turn only: one prompt, a chosen and a rejected response | Prompts, plus an evaluator that can tell a good outcome from a bad one | | **Dataset size** | Hundreds of examples, or roughly 10M+ tokens | Hundreds to thousands of pairs | Dozens to thousands of prompts, sometimes more. Often fewer than 100 is enough | | **Consider alternatives if** | You have very few examples, or no high-quality verified outputs to learn from | Outputs can be judged objectively, or you already have high-quality verified pairs. Both point to SFT or RL | You have no way at all to judge an outcome, including an LLM judge. Simpler methods are untried, or you want a quick training experiment | | **Guides** | [Text](/fine-tuning/fine-tuning-models) · [Vision](/fine-tuning/fine-tuning-models#vision-training) · [Cookbook](/fine-tuning/training-api/cookbook/sft) | [Managed DPO / ORPO](/fine-tuning/dpo-fine-tuning) · [Cookbook](/fine-tuning/training-api/cookbook/dpo) | [Managed RFT](/fine-tuning/reinforcement-fine-tuning-models) · [Cookbook](/fine-tuning/training-api/cookbook/rl) | **Verifiable** means you can reliably judge whether a model output is good (rules, unit tests, programmatic checks). RL fits reasoning and agentic tasks where full ground-truth labels are hard to write. The Training API also supports custom methods (GRPO, distillation, and others) via the Python SDK. See [Cookbook recipes](/fine-tuning/training-api/cookbook/overview) and [Managed Training](/fine-tuning/managed-finetuning-intro) for model support and pricing. ## Choose a surface Pick a **surface** (managed or Training API, serverless or dedicated). The surface decides how much of the model you update and which **interfaces** are available to you. Answer the question below and the flow takes you to your surface, which links to its guide. Click any answered question to change it, or show every path at once. Compare the last branch in detail on [serverless versus dedicated](/fine-tuning/training-api/introduction#infrastructure), and check per-model support on [Models](/fine-tuning/models). ### Managed Training vs Training API Fireworks offers two ways to train: **Managed Training** (Fireworks runs the loop) and the **Training API** (you write the loop in Python). | Choose Managed Training when | Choose the Training API when | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | You need a standard SFT, DPO, ORPO, or RFT job | You need a custom loss, reward, rollout, trajectory, or optimizer-step loop | | You want Fireworks to own scheduling, training, and checkpointing | You want to fork or write Python training logic | | A supported model and managed configuration cover the task | You need inference in the loop, distillation, per-step diagnostics, or research algorithms | Standard jobs with a platform-managed loop. Programmable loops built from cookbook recipes or the SDK. ### Serverless vs Dedicated infrastructure Infrastructure applies to the **Training API** only. Managed Training uses platform-managed compute. | Choose Serverless Training when | Choose Dedicated Training when | | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | Supported LoRA SFT or RL covers the workload | You need full-parameter, DPO, ORPO, distillation, or broader model support | | You want shared pooled compute with no trainer or sampler deployment provisioning | You need explicit trainer, deployment, checkpoint, reconnect, or promotion control | | Per-token billing fits a small or bursty experiment | A sustained, highly utilized time-based run fits the workload | | In-session sampling is sufficient | You need provisioned rollout or evaluation deployments | Shared pooled trainer, no provisioning, per-token billing. Provisioned trainer and deployment resources with explicit lifecycle control. See the detailed [serverless versus dedicated comparison](/fine-tuning/training-api/introduction#infrastructure). ## Choose how to interact * **Skill** — the only interface that drives both surfaces. Your coding agent configures, runs, and troubleshoots training through the [Fireworks training skill](/fine-tuning/agent/use-with-coding-agents). * **Fireworks UI, `firectl`, or the REST API** — managed jobs only. Guided creation and monitoring in the UI, reproducible job and resource automation from the CLI or API. * **Python SDK** — Training API loops only, on serverless or dedicated. Start from a [cookbook recipe](/fine-tuning/training-api/cookbook/overview). **CLI or API vs Python SDK:** `firectl` and the REST API manage **managed** jobs and platform resources. The **Python SDK** runs **Training API** loops you author yourself (loss, rollouts, optimizer steps). ### GPU quota prerequisite Managed jobs and dedicated Training API runs need training GPU quota, granted automatically by [spending tier](/guides/quotas_usage/account-quotas#training-gpu-quota). [Serverless Training](/fine-tuning/training-api/serverless) uses a shared pool with its own model, concurrency, and rate limits instead of dedicated training GPU quota. | Tier | How to reach it | B200 / B300 (Blackwell) | H200 | H100 / A100 | | ----------------- | ---------------------------------------- | :---------------------: | :--: | :---------: | | No payment method | — | 0 | 0 | 0 | | Tier 1 | Valid payment method and billing profile | 0 | 16 | 8 | | Tier 2 | Spend or add \$50 in credits | 16 | 16 | 16 | | Tier 3 | Spend or add \$500 in credits | 24 | 24 | 24 | | Tier 4 | Spend or add \$5,000 in credits | 32 | 32 | 32 | Check your quota with the Fireworks CLI (`firectl quota list`). A job rejected with HTTP 429 `quota_exceeded` (sometimes a `403` on the job poll) is a tier issue, not a dataset/config problem. Need more training quota than your tier allows? [Reach out for enterprise support](https://fireworks.ai/contact-training) and we'll help size the right allocation for your workload. ## Models Model availability is decided per model and per surface — managed jobs by method (SFT, DPO, RFT), Training API jobs by parameter mode (LoRA or full-parameter). Check the live catalog before you launch. Browse the base model catalog with per-model surface, method, and training-shape support. ## Training security Across every training surface, one principle holds: **your training data is never used to train Fireworks-owned or shared models**. Inference follows [Zero Data Retention](/guides/security_compliance/data_handling) by default. This section summarizes the training surfaces; step-by-step BYOB IAM setup, CMEK KMS setup, and secure RFT are in [Secure Training](/guides/security_compliance/secure_training) and [CMEK](/guides/security_compliance/secure_training/cmek). ### Choose a surface by data-privacy needs | Surface | Where your training data lives | What Fireworks retains | Your deletion controls | | -------------------- | --------------------------------------------------------------- | ---------------------------- | ----------------------------------------------------------------- | | **Managed Training** | Fireworks-managed storage (GCS); reference link in our database | Dataset, checkpoints, traces | Delete dataset after job; request checkpoint/trace deletion | | **Managed + BYOB** | Your cloud bucket; read in-place during training only | Checkpoints and traces only | Revoke bucket access after job; request checkpoint/trace deletion | | **Training API** | No dataset file on Fireworks — transient tokenized batches only | Checkpoints and traces only | Request checkpoint/trace deletion | Checkpoints and traces are retained \~30 days by default (deletable on request). Strictest governance: [BYOB](#dataset-storage-byob) (dataset never copied to Fireworks) or the [Training API](/fine-tuning/training-api/introduction) (no stored dataset file). ### Bring your own bucket (BYOB) Register an external URL so Fireworks reads your dataset during the job without persisting a copy, then revoke access after the job: ```bash theme={null} firectl dataset create my-dataset --external-url gs://your-bucket/path/train.jsonl ``` Supported: GCS, AWS S3, and Azure Blob, with least-privilege IAM to Fireworks service accounts provided at onboarding. For AWS S3, lock the IAM trust policy with both `accounts.google.com:sub` and `accounts.google.com:oaud` (your Fireworks account ID) so tokens for other accounts are rejected. Full IAM trust policies, OIDC audience, and rotation are in [Secure Training](/guides/security_compliance/secure_training/byob). ### Customer-managed encryption keys (CMEK) CMEK encrypts datasets and checkpoints on Fireworks-managed storage with **your** cloud KMS key — revoke the key and Fireworks cannot decrypt. Supported on AWS KMS, Google Cloud KMS, and Azure Key Vault. It does not cover in-memory training compute or inference request/response. Setup, IAM, and rotation detail: [CMEK](/guides/security_compliance/secure_training/cmek) · [Data Security Overview](/guides/security_compliance/data_security). ### Secure RFT and customer controls For RFT under strict governance, combine a [BYOB](#dataset-storage-byob) dataset with evaluators and rollout servers kept in your own environment (see [Remote Environment Setup](/fine-tuning/connect-environments)). To delete checkpoints, traces, or rollout data, contact your Fireworks account team; datasets are deletable from the console or API after a job completes. ## Before launch Verify current model support, shapes, access status, pricing, limits, and quota in the linked live pages. A coding agent asks for confirmation before upload, registration, paid inference, job creation, promotion, deployment, or another mutation. Material changes require approval again; promotion and deployment are confirmed separately. # Managed Training Overview Source: https://docs.fireworks.ai/fine-tuning/managed-finetuning-intro Train models with Fireworks-managed infrastructure — no custom code required. Give Fireworks your data and configuration. The platform handles scheduling, training, checkpointing, and model output. Training data uses the **OpenAI-compatible chat completion format**, so existing OpenAI SFT datasets work with no conversion required. ## How to launch managed training These interfaces create the same underlying managed jobs: | Interface | Use when | | ---------------- | ---------------------------------------------------------------- | | **Fireworks UI** | You want guided configuration and visual monitoring | | **CLI or API** | You want scripted and reproducible job operations | | **Your agent** | You want help configuring, running, and troubleshooting training | The Fireworks CLI is called `firectl`. [Install the training skill](/fine-tuning/agent/use-with-coding-agents) to use your agent, or continue with the method-specific managed guides below. For custom Python training loops, start with the [Training API overview](/fine-tuning/training-api/introduction). ## Methods Train text and vision models with labeled examples of desired outputs Train on preferred and non-preferred response pairs using DPO or ORPO Train models using custom reward functions for complex reasoning tasks ## Supported base models Fireworks supports training for major open source model families, including DeepSeek, Qwen, Kimi, Gemma, GLM, and Llama. Eligibility is decided per model and per method: a model can support SFT without supporting DPO or RFT. [**Models**](/fine-tuning/models) is the live per-model matrix: the surfaces and methods each base model is enabled for, the training shapes behind it, and each shape's maximum context length. Check it before creating a job, and set the job context from a shape that supports the method you picked, using `firectl sftj create`, `firectl dpo-job create`, or the corresponding RFT command. Custom models uploaded by users are not automatically tunable. To use managed training with an uploaded custom base model, the model must have a corresponding Hugging Face URL. Fireworks uses that URL to infer the training renderer and locate compatible training shapes. A custom model is supported only when Fireworks can resolve both a supported renderer and at least one compatible training shape. After the Hugging Face URL is set, tunability is refreshed by a background operation that runs about every 30 minutes, so the model may take up to 30 minutes to show as `Tunable: true`. We are working to make this refresh faster. To browse the broader catalog (including non-tunable inference models), visit the [Model Library for text models](https://app.fireworks.ai/models?filter=LLM\&tunable=true) or [vision models](https://app.fireworks.ai/models?filter=vision\&tunable=true). ## Tuning modes and context length Managed training runs **[Low-Rank Adaptation (LoRA)](https://arxiv.org/abs/2106.09685)** only. It supports the full context lengths exposed by the available training shapes, matching the same long-context capabilities used by cookbook recipes. LoRA gives you efficient adapter training and flexible deployment, including [multiple LoRAs](/fine-tuning/deploying-loras#multi-lora-deployment) on a single base model deployment. For full-parameter tuning, use the [Training API](/fine-tuning/training-api/introduction). **Deprecation notice:** The `deployedModel` request key for routing to LoRA addons is deprecated and will not be supported for any new deployments. Please migrate to the `model` field with the `#` format described in [Routing requests to LoRA addons](/fine-tuning/deploying-loras#multi-lora-deployment). # Models Source: https://docs.fireworks.ai/fine-tuning/models Which base models you can train on Fireworks and the surfaces each one is available on. Managed training, the Training API, and serverless training all draw from the same base model catalog, but availability is decided per model: managed jobs by method (SFT, DPO, RFT), Training API jobs by parameter mode (LoRA or full-parameter). ## Model availability Pick a model to see the surfaces and methods it is enabled for, plus any training shapes that back it. Switch to **All models** for the full matrix. ## Vision and multimodal support Vision support is model- and surface-specific. Use the catalog above to confirm that the selected VLM has a compatible managed method or Training API shape before preparing data. * Managed VLM SFT dataset schema and launch flow: [Supervised Fine-Tuning: Vision](/fine-tuning/fine-tuning-models#vision-training) * Training API VLM loops: start from a VLM-compatible shape and the same cookbook SFT, DPO, or RL recipe used for text, replacing the text tokenizer with the model processor * Inference request formats after deployment: [Vision-language models](/guides/querying-vision-language-models) ## Next steps Hand Fireworks your data and let the platform run the job Write your own training loop against a Tinker-compatible API Train on shared pooled infrastructure with per-token billing What a shape pins and how to reference one Provision a trainer and sampler on reserved GPU capacity Current rates across training and inference # RL rollout cost comparison vs Tinker Source: https://docs.fireworks.ai/fine-tuning/multi-turn-cost-comparison Compare rollout inference costs for multi-turn agentic RL on Fireworks and Tinker This page estimates **rollout inference only**. To plan SFT or DPO training costs, use the separate [Training cost estimator](/fine-tuning/cost-estimator). If you're running RL or agentic post-training on a long-context model and your provider bills you per token with **no cross-turn prefix cache**, the prefill cost grows quadratically with the number of turns — every turn re-prefills the full conversation history. On Fireworks Dedicated, session-affinity routing keeps an episode pinned to one replica so the KV cache is reused across turns, and cached prompt tokens contribute essentially zero extra compute. The calculator below makes that difference concrete. Set your episode shape (turns, context growth, generation length) and compare: * **Tinker** — flat per-token billing, no cross-turn cache (re-prefill every turn) * **Fireworks Dedicated** — on-demand GPU-hour billing; the cache savings show up as more work per hour, not as a discounted token rate ## Performance and benchmarking notes ### Dedicated trainer vs pooled/serverless resourcing Tinker runs training jobs on a **pooled/serverless** GPU fleet, which lets a single job burst onto many more GPUs than you would dedicate to a replica on Fireworks. That burst is what makes individual Tinker steps feel fast — but it also **caps the maximum training speed you can buy**: you cannot pay to scale beyond the pool's per-job allocation, and you cannot reserve isolated capacity. Fireworks dedicated trainers take the opposite trade-off: predictable, isolated execution with no shared-pool queueing or noisy-neighbor variance, and the ability to scale **wall-clock time and cost independently** by adjusting replica count. If you want faster steps on dedicated, increase replica count and parallelize work. For **large model training or longer rollouts**, we have consistently found the dedicated setup like ours is **cheaper overall and can also be faster** depending on the customer's resourcing needs. ### Context-length benchmarking caveat Benchmark comparisons are only apples-to-apples when truncation policy and effective context length are matched. If one system truncates `>32k` samples and another does not, the non-truncating run is doing more work and will appear slower. ### Replica count is a speed/cost knob Users can trade cost and wall-clock time by scaling replicas. A quick back-of-envelope estimate: $$ \text{\$ / 1M tokens} \approx \frac{\text{GPU count} \cdot \text{\$ / GPU-hour}}{\text{tokens/sec(cluster)} \cdot 3600} \cdot 10^6 $$ ### Check utilization before scaling Fireworks Dedicated is billed by GPU-hour, so low rollout traffic can make a job look slow or expensive even when the deployment has spare capacity. Before adding replicas, first confirm whether the inference deployment is saturated or waiting for more work from your rollout client. Useful signals: * **Per-request performance metrics:** log Fireworks response metrics such as prompt tokens, cached prompt tokens, time to first token, and total server processing time from your rollout client. Non-streaming requests include these in response headers; for streaming requests, set [`perf_metrics_in_response`](/guides/querying-text-models#usage--performance-tracking) to include them in the final response chunk. * **Deployment-level metrics:** export [Prometheus-style metrics](/deployments/exporting-metrics) for request rate, prompt and cached-token rates, queue latency, KV-cache usage, and concurrent request count. Low request/concurrency metrics with low queueing usually mean the deployment can accept more traffic. * **Training API efficiency hints:** when available, monitor `trainer/training_efficiency/.../effective_batch_fill_ratio:last` and `trainer/training_efficiency/.../trainer_waiting_for_work:last`. These are returned in the `metrics` dict on your `forward` / `forward_backward` responses, not on the deployment dashboard. Low batch fill or a trainer-waiting-for-work signal usually points to the rollout side not feeding the trainer fast enough. See [Reading Training API efficiency metrics](#reading-training-api-efficiency-metrics) below for how to access and interpret them. If the deployment is not saturated, increase rollout traffic first. For managed RFT and Training API jobs, the main throughput knob is concurrent rollouts; see [`max_concurrent_rollouts`](/fine-tuning/rft-parameters-reference) and the Training API [deployment replica guidance](/fine-tuning/training-api/reference/deployment-manager#deployment-shape-and-training-shapes). #### Reading Training API efficiency metrics The two `trainer/training_efficiency/...` metrics are returned in the `metrics` dict on your `forward` / `forward_backward` responses. They do **not** appear on inference deployment dashboards, the per-request and deployment-level signals above are separate. ```python theme={null} # forward / forward_backward return a future, call .result() result = training_client.forward_backward(datums, "cross_entropy").result() # result.metrics is a dict; it includes: # trainer/training_efficiency/.../effective_batch_fill_ratio:last # trainer/training_efficiency/.../trainer_waiting_for_work:last print(result.metrics) ``` * **`effective_batch_fill_ratio:last`**: the number of tokens in a batch divided by the maximum possible. **1.0 means fully saturated**; consistently low values across steps indicate under-filling. * **`trainer_waiting_for_work:last`**: how much time the trainer (GPU) sat idle since the last op, i.e. the gap between `forward` calls. More waiting means the trainer is starved for work. Low fill or significant waiting-for-work means the rollout side isn't feeding the trainer fast enough: raise rollout concurrency (`max_concurrent_rollouts`) before adding deployment replicas. ## How the numbers come together ### Tinker (the cost customers describe) Each turn re-prefills the full accumulated context: $$ \text{Prefill tokens (Tinker)} = \sum_{t=1}^{T} P_t = T \cdot P_1 + \Delta \cdot \frac{T(T-1)}{2} $$ …where $P_1$ is the initial prompt (system + tools + task), $\Delta$ is the context added per turn (model response + tool result), and $T$ is the turn count. This is **quadratic in $T$**. $$ \text{Cost (Tinker)} = \frac{\text{Prefill tokens}}{10^6} \cdot r_{\text{prefill}} + \frac{\text{Decode tokens}}{10^6} \cdot r_{\text{sample}} $$ ### Fireworks Dedicated — GPU-hour billing Dedicated deployments are billed per GPU-second, so the prefix cache shows up as **higher effective throughput** rather than a discount on per-token rates. Across one episode, each unique token is prefilled at most once — the rest of the prompt is served from the prefix cache and contributes essentially no GPU work. The uncached portion that actually hits prefill is: $$ \text{Uncached prompt} = P_T = P_1 + (T - 1) \Delta $$ On a saturated cluster: $$ \text{Cluster-hours} = \frac{\text{Uncached prompt} / \text{prefill TPS}}{3600} $$ $$ \text{Cost} = \text{Cluster-hours} \cdot N_{\text{GPU}} \cdot r_{\text{GPU/hr}} $$ Because cached tokens contribute essentially nothing to wall-clock work, the cluster's effective \$/M token rate falls as utilization rises. For continuous RL training, where rollouts run at sustained pace, dedicated is typically the cheapest path at scale. The calculator's dedicated path uses *saturated* throughput estimates as defaults. A small, lightly-loaded test deployment will look more expensive per token than these numbers because the cluster is paid for whether it's busy or idle. Tune the throughput inputs in the **Advanced** panel to match your actual rollout pace. ## What's covered The calculator currently includes the four models for which Tinker publishes per-token rates: | Model | Tinker prefill / sample (per 1M) | | ------------------------ | -------------------------------- | | Kimi K2.6 (128K) | $5.15 / $12.81 | | Kimi K2.5 (128K) | $5.15 / $12.81 | | Qwen3.5-397B-A17B (256K) | $4.00 / $10.00 | | GPT-OSS-120B (128K) | $0.63 / $1.54 | All Fireworks-side rates are taken from the public pages linked below and the constants live in `snippets/multi-turn-cost-calculator.jsx` — update there if either side's pricing changes. ## FAQ ### What is the fastest way to reduce wall-clock time? Increase replicas and overlap sampling/training where your workflow allows it. Those are usually the most direct levers for shortening end-to-end cycle time. ### How should I compare costs between providers? Use matched assumptions for context length, truncation policy, and effective resource allocation. The calculator at the top of this page handles the math once you plug in your episode shape — be sure to also align truncation policy and effective context window between providers before drawing conclusions. ## Sources * Tinker pricing: [thinkingmachines.ai/tinker](https://thinkingmachines.ai/tinker) * Fireworks GPU-hour pricing: [fireworks.ai/pricing](https://fireworks.ai/pricing) * Related: [RFT Cost Estimator](/fine-tuning/reinforcement-fine-tuning-models#rft-cost-planning) — same idea, but for the training-side bill (Fireworks GPU-hour, no comparison column). This is an estimator, not a quote (updated). Real costs depend on your exact workload, cache hit rate, hardware utilization, and rate-card terms at run time. # Single-Turn Training Quickstart Source: https://docs.fireworks.ai/fine-tuning/quickstart-math Train a model to be an expert at answering GSM8K math questions **Following the [RFT Overview](/fine-tuning/reinforcement-fine-tuning-models)?** This is the **Single-Turn Training** path—the fastest way to get started with RFT. In this quickstart, you'll train `Qwen3 4B` to solve mathematical reasoning problems from the GSM8K dataset. ## What you'll learn * How to set up and test an evaluator locally, using the Eval Protocol SDK * How to take that evaluator and use it in an RFT job, from the command line * How to monitor training progress and evaluate accuracy improvements Prefer a notebook experience? You can also [run this tutorial in Google Colab](https://colab.research.google.com/drive/16xrb9rx6AoAEOtrDXumzo71HjhunaoPi#scrollTo=CP18QX4tgi-0). Note that Colab requires billing enabled on your Google account. ## Prerequisites * Python 3.10+ * A Fireworks API key (stored in your shell or .env) * Command-line access (terminal or shell) ## 1. Install dependencies and set up files Clone the quickstart-gsm8k repository and install dependencies: ```bash theme={null} git clone https://github.com/eval-protocol/quickstart-gsm8k.git cd quickstart-gsm8k pip install -r requirements.txt ``` Create the `gsm8k_artifacts/` folder structure and copy files: ```bash theme={null} mkdir -p gsm8k_artifacts/{tests/pytest/gsm8k,development} cp evaluation.py gsm8k_artifacts/tests/pytest/gsm8k/test_pytest_math_example.py cp gsm8k_sample.jsonl gsm8k_artifacts/development/gsm8k_sample.jsonl ``` The repository includes: * **Evaluator** (`evaluation.py`): Defines how to evaluate math answers * **Dataset** (`gsm8k_sample.jsonl`): Contains example math problems to test on Install the latest `eval-protocol` SDK, `pytest`, and `requests`: ```bash theme={null} python -m pip install --upgrade pip python -m pip install pytest requests git+https://github.com/eval-protocol/python-sdk.git ``` Download the evaluator and dataset files: Run this Python script to download two files from the Eval Protocol repository into a folder on your machine called `gsm8k_artifacts/`. * **Test script** (`test_pytest_math_example.py`): Defines how to evaluate math answers * **Sample dataset** (`gsm8k_sample.jsonl`): Contains example math problems to test on ```python tutorial/download_gsm8k_assets.py theme={null} from pathlib import Path import requests ARTIFACT_ROOT = Path("gsm8k_artifacts") TEST_PATH = ARTIFACT_ROOT / "tests" / "pytest" / "gsm8k" / "test_pytest_math_example.py" DATASET_PATH = ARTIFACT_ROOT / "development" / "gsm8k_sample.jsonl" files_to_download = { TEST_PATH: "https://raw.githubusercontent.com/eval-protocol/python-sdk/main/tests/pytest/gsm8k/test_pytest_math_example.py", DATASET_PATH: "https://raw.githubusercontent.com/eval-protocol/python-sdk/main/development/gsm8k_sample.jsonl", } for local_path, url in files_to_download.items(): local_path.parent.mkdir(parents=True, exist_ok=True) response = requests.get(url, timeout=30) response.raise_for_status() local_path.write_bytes(response.content) print(f"Saved {url} -> {local_path}") ``` Expected output: ``` Saved https://raw.githubusercontent.com/.../test_pytest_math_example.py -> gsm8k_artifacts/tests/pytest/gsm8k/test_pytest_math_example.py Saved https://raw.githubusercontent.com/.../gsm8k_sample.jsonl -> gsm8k_artifacts/development/gsm8k_sample.jsonl ``` ## 2. Test your evaluator locally In this step, we will test your evaluator by examining the output locally. Feel free to iterate on the evaluator you downloaded in the last step until it gives the output you want. Open a terminal and run: ```bash theme={null} ep logs ``` This will start a local server, navigate to `http://localhost:8000`. Keep this terminal running. In a **new terminal**, call the test script to run the evaluator on your dataset of sample math problems. ```bash theme={null} cd gsm8k_artifacts ep local-test ``` This command discovers and runs your `@evaluation_test` with pytest. As the test runs, you'll see evaluation scores appear in the browser, with detailed logs for each problem the model attempts. `pytest` will also register your evaluator and dataset with Fireworks automatically, so you can use them in the next step for RFT. GSM8K evaluation UI showing model scores and trajectories ## 3. Start training First, set your Fireworks API key so the Fireworks CLI can authenticate you: ```bash theme={null} export FIREWORKS_API_KEY="" ``` Next, launch the RFT job using the evaluator and dataset you registered. This example uses `qwen3-4b`; confirm current RFT eligibility and pricing before launch. ```bash theme={null} cd .. eval-protocol create rft \ --base-model accounts/fireworks/models/qwen3-4b ``` The CLI will output dashboard links where you can monitor your training job in real-time. GSM8K evaluation score showing upward trajectory You can also store your API key in a `.env` file instead of exporting it each session. ## Monitor your training progress Your RFT job is now running. You can monitor progress in the dashboard links provided by the CLI output. Re-run the pytest evaluation command to measure your model's performance on new checkpoints: ```bash theme={null} cd gsm8k_artifacts pytest -q tests/pytest/gsm8k/test_pytest_math_example.py::test_math_dataset -s ``` This helps you see how your model's accuracy improves over time and decide when to stop training. You can adjust the evaluation logic to better fit your needs: * **Modify reward shaping**: Edit the scoring logic in `test_pytest_math_example.py` to match your answer format expectations * **Use your own data**: Replace the sample dataset by either editing the JSONL file locally or passing `--dataset-jsonl` when creating the RFT job ### What's happening behind the scenes Understanding the training workflow: 1. **Evaluation registration**: The pytest script evaluates a small GSM8K subset using numeric answer checking, then automatically registers both your evaluator and dataset with Fireworks 2. **RFT job creation**: The `create rft` command connects your registered evaluator and dataset to a Reinforcement Fine-Tuning job for your chosen base model 3. **Continuous improvement**: As training progresses, evaluation scores on the held-out set reflect improved accuracy, allowing you to iterate quickly before scaling to larger experiments ## Next steps Learn all CLI options to customize your training parameters Train agents that run in your production infrastructure Understand how reinforcement fine-tuning works # Remote Agent Quickstart Source: https://docs.fireworks.ai/fine-tuning/quickstart-svg-agent Train an SVG drawing agent running in a remote environment **Following the [RFT Overview](/fine-tuning/reinforcement-fine-tuning-models)?** This is the **Remote Agent Training** path—for training agents that run in your production infrastructure. In this quickstart, you'll train an agent to generate SVG drawings. Your agent runs in a remote server (Vercel), which means rollouts happen remotely while Fireworks handles the training. This approach lets you train agents that already live in your production environment. Here's a quick walkthrough: