Usage and costs

Use /usage to see the usage your provider reports for the account you use with fx. The numbers come from the provider, so they include requests from other devices and applications that use the same account. A custom connection has no usage report, so /usage says that provider's usage isn't shown.

Check AI Gateway usage

With AI Gateway selected, /usage shows spend, requests, and tokens for today, the last 7 days, and the calendar month, with a breakdown by model. Days follow UTC. What the numbers cover depends on how you sign in:

Sign-inWhat /usage shows
fx loginYour spend on the selected team, and your user budget when the team sets one.
API keyThe spend of that key.

Press tab or the left and right arrow keys to change the period, and the up and down arrow keys to select a model. Press enter to see the selected model's spend, share, requests, token types, cache hit rate, 90th-percentile time to first token and output speed, and error rate. There, the up and down arrow keys move between models and esc goes back to the table. Press r to refresh and esc to close /usage.

AI Gateway can take a few minutes to include a new request in its reports, so the latest requests may not appear yet.

Check Codex and Grok plan usage

With Codex selected, /usage shows your ChatGPT plan: its usage limits and when they reset, its credits, and its spend limit. It also shows your token activity, with shares by model and by surface, and records such as your longest chat. fx reads all of it from ChatGPT with your Codex sign-in.

With Grok selected, /usage shows your plan's allowance for the current period and when it resets, usage by product when Grok reports it, bought credits, and pay-as-you-go spending. For an account that a team manages, /usage points to the team's usage page instead.

How fx refreshes usage

/usage opens with the numbers fx already has and refreshes in the background, so it never waits on the network. While it stays open, fx refreshes every 15 minutes. Press r to refresh at any time, unless a refresh is already running.

If you reopen /usage within a minute of a refresh in the same fx process for the same sign-in, fx shows what it has without refreshing again. The same minute applies after a failed refresh. After you switch to another provider or sign-in, the next /usage refreshes right away.

fx keeps the numbers in ~/.fx/usage-cache/, shared by every fx process on the machine, so a refresh in one fx window shows up within a minute in any other window that has /usage open. For AI Gateway, each refresh reads today, and reads the finished days of the 7-day and monthly views only when the cache doesn't already hold them for the current UTC day.

Check usage from the terminal

From your terminal, show the same tables for the calendar month:

$fx usage

Choose a period or return structured output:

$fx usage --period today --json

Periods are today, 7d, and month. Each run asks your provider for current numbers and reuses the finished days already in ~/.fx/usage-cache/. fx usage exits with a nonzero status when it can't read usage, for example when you aren't signed in to AI Gateway.

To see the tokens that one fx ask run used, including cached-read and cache-write counts when the provider reports them, read usage in fx ask --json.

Account billing

For invoices, payment methods, and plan changes, use your provider's dashboard. A request that /usage doesn't show yet may still be billed.

Ultrafast pricing

Ultrafast is an explicit opt-in to a higher-priced OpenAI tier through AI Gateway. Check the selected model's current pricing before enabling it. Main-agent and eligible subagent requests can both use the tier.

The footer's single yellow lightning marker and ultrafast_requested report what fx requested, not a billing guarantee. When Gateway does not confirm that it served Ultrafast, fx warns that the response may have used a standard or lower tier. Check Gateway's billed usage for the charge; missing confirmation does not mean the request was free.

Session titles, permission reviews, and context compaction do not inherit Ultrafast.

Prompt caching

On supported models, fx reuses shared instructions across workspaces and worktrees. Branch changes, permission changes, newly read folder rules, and resumed conversations preserve earlier conversation content for prompt caching. Named skills send their full instructions with the turn that invokes them instead of adding them to the shared instructions, so later requests read that turn from the cache. Cache use and savings depend on the model and provider.

Cache warming

Claude's prompt cache keeps a conversation for 5 minutes after the last request that read or wrote it. While a Claude conversation through AI Gateway waits for your next message or for a long tool run, in the terminal or fx acp, fx keeps the cache warm: it resends the last request with a one-token reply limit, which reads the cached conversation and starts its 5 minutes again. The first resend goes out 4.5 minutes after the request, a tenth of the cache's lifetime before it expires, and the next ones follow every 4.5 minutes, for up to 30 minutes after the request. That is at most six resends per pause.

Each resend reads the conversation at Anthropic's cache-read price, a tenth of the input price, instead of writing it again at the cache-write price, 1.25 times the input price. Its tokens count toward the session's usage.

Warming stops:

  • When you send your next message, start a new conversation with /new or /clear, or quit fx.
  • 30 minutes after the last request.
  • When a resend fails, or writes the cache instead of reading it because the provider dropped the entry.
  • When the computer sleeps through a resend. A resend more than 15 seconds late could arrive after the cache expired and pay for a full write.

fx doesn't warm subagent requests, requests through a Codex or Grok sign-in or a custom connection, or requests that use a credential supplied by the app hosting fx. It also skips Claude models that use a fixed thinking budget instead of effort levels when thinking is on, because a one-token reply limit doesn't stop them from thinking.

To turn warming off, run fx config set cache_warming false, or set cache_warming: false in your profile.

Additional model requests

These features can make requests in addition to the main conversation:

FeatureWhen it runs
Auto modeA tool action needs a model review.
SubagentsEach subagent makes its own model requests.
Vision fallbackAI Gateway analyzes images for a model without image input.
Context compactionfx summarizes older context automatically or through /compact.
Session titlesfx generates a title from the first prompt.
Cache warmingA Claude conversation through AI Gateway waits for your next message or a long tool run.
Resent repliesA reply runs out of output tokens before any text, or the provider stops it for another reason before any text or tool call, and fx asks the model once more.

To turn off session titles, set session_titles: false in your profile or use /settings.

Web search can also add provider charges.

Check your AI Gateway balance

With AI Gateway selected, check the balance for the active credential:

$fx credits

fx balance is an alias, and --json returns structured output. In a session, run /credits or /balance.

For billing details, open your AI Gateway dashboard.