Tracking inference spend

A catalog document is JSON:

An exchange is priced only when every token class that it used has a rate. A rate that you leave out means the class has no price, not that it costs nothing. If a model does not charge for a class, set its rate to 0. If you leave out cacheRead for a model whose traffic uses cached input, that traffic is unpriced. An OpenAI model that charges for cache writes, GPT-5.6 and later, needs a cacheWrite rate, or its traffic that wrote to the cache is unpriced. The service ignores a field that the document does not define, so a misspelled rate counts as a rate that you left out.

A version can price some served names and leave out others. The served names that it leaves out keep their earlier price.

Exchanges are unpriced until you publish a catalog version. The example in this section holds list prices for some common OpenAI and Anthropic models. Review it and adjust it before you publish it.

The rates are the list prices that OpenAI API pricing and Claude API pricing stated on October 18, 2026. List prices change, so check each rate on the provider’s page before you publish.

Change the example before you publish it:

Check the document with --dry-run before you publish it.

Check a document without publishing it:

The service validates the document and states the version it would publish. Nothing is written.

Publish it:

The command asks you to confirm. Pass --force to skip the question in a script. To read the document from standard input, pass -f -. Without a terminal, publishing requires --force, --disable-prompt, or AKKA_DISABLE_PROMPTS=true; otherwise, the command stops without publishing.

A document that the service refuses is not published, and the error names what is wrong, for example a rate that is missing or negative, or an effectiveAt that is not later than the latest price.

Read the prices in force now:

get lists every served name that has a price in force, ordered by served name, each with the entry of the version that prices it. PRICED BY names that version. The top block names the version that most recently took effect. In this example, version 2 priced only frontier-model, so finetune-model keeps the price that version 1 set. A class with no price shows —. Pass --at with an ISO-8601 instant to read the prices in force at that time.

To see when each version took effect, list the versions:

The list is newest first.

get -o json writes a catalog document that apply takes. When you publish it, the service ignores the fields that the service sets: version and publishedAt at the top, and version on each entry. The service refuses the document if you publish it unchanged, because its effectiveAt is not later than the prices it carries.

Pass --by to divide the period into rows. The rows are ordered by spend, biggest first, and always add up to the total.

A + after a token count marks a lower bound: some exchanges did not report every token class, so the true count can be higher. This is common, because providers do not report every class. For example, OpenAI responses report cache-write tokens only for the models that charge for them, GPT-5.6 and later, and Anthropic responses do not report reasoning tokens. The command prints a note that names the classes that were not reported.

A served name longer than 256 bytes of UTF-8 is held and shown as sha256: followed by the hex SHA-256 of those bytes.

A route holds how the gateway router reached the destination of an exchange: the basis, the routing ruleset and its revision, the rule, and the destination. Each revision of a ruleset is a row of its own, so a period that spans a ruleset change shows the spend of each revision. See Routing requests to models.

A route reads as its basis, then ruleset@revision and the rule where the route has them, then → and the destination where it has one. The basis is one of these:

A system id names the AI system that a request was sent for. The request names it in the x-akka-system-id header. An agent of an Akka service sends this header with its identity headers. See Identity headers. Any other client sets the header itself. Traffic that names no system id is the row unidentified.

Divide a period by system id:

The answer has a row for every system id with traffic in the period. No system id is left out or folded into another row, so the rows add up to the total. system combines with the other divisions, for example --by system,model for what each system spent on each model.

Pass --system to read the spend of one system id. It works on spend get, spend compare and spend series, with any division:

--system cannot select the traffic that named no system id: --system unidentified reads a system id named unidentified. A system id longer than 256 bytes of UTF-8 is held and shown as sha256: followed by the hex SHA-256 of those bytes, and --system takes either form.

List every system id that the service has seen:

Each row is one system id that the service holds. CALLS is how many exchanges named it, and FIRST CALL HOUR and LAST CALL HOUR are the first and the last UTC hour in which one did. These are whole hours, not instants. A system id whose exchanges left the records before the service counted them in an hour has no calls and no hours, such as svc-legacy above. To list the last exchanges of a system id, run akka optimize spend recent --system ID. See List the most recent exchanges.

The service does not check a system id. A client sends the value that it chooses, unless your deployment overwrites the header at its own edge. The service keeps every system id that it sees, and nothing deletes one. Use the name of a system as the system id, never personal data.

An exchange is unpriced when no price covers every token class that it used. It counts in the exchanges and tokens, and not in the spend. When a period has unpriced traffic, the answer states the cause: a served name with no price, or a token class with no rate. An exchange whose response names no served name, such as a refused request or an error response, counts as a served name with no price, and no price can cover it. Divide by model to see which served names have unpriced traffic. Publish a catalog version that adds the price or the missing rate.

Which unpriced traffic the new version prices depends on the cause:

To price the recorded traffic of a served name, publish the first price of that served name:

The service starts to price the recorded traffic shortly after the publish, and a long range takes longer. The service keeps the record of each exchange for at least 90 days. Older traffic keeps its figures and remains unpriced. The spend of a period can rise after a publish, and its unpriced count fall, also when the period is complete.

A period that spans a price change holds exchanges priced at each rate. To see when each price took effect, run akka optimize pricing-catalog versions list. To read the prices at an instant, run akka optimize pricing-catalog get --at with that instant.

The answer gives the tokens and spend for each period, and the difference between them. A difference has a value only when both periods have one in the same currency.

spend series divides a period into UTC hours or UTC days. It answers each of them as spend get answers that hour or day alone, completeness included.

--granularity is hour or day, and has no default. A day series starts and ends at midnight UTC. For days in another time zone, ask for hours and add them up. PERMANENCE is reported when the hour or day is complete and nothing more arrives for it, and working otherwise. A publish can still price the unpriced traffic of a reported hour or day. --by and --system work as they do for one period. A series holds at most 744 buckets by default, and the service refuses a longer one.

spend recent lists the most recent exchanges, newest first. --since is required. It is an ISO-8601 instant, and it is inclusive. The service refuses a --since before the start of its record period, and the refusal names the oldest instant that you can ask for.

Each row is one exchange: when it was served, its exchange id, its system id, its tags, the model, the provider that the pricing catalog names for the model, its outcome, its tokens and its spend. TAGS holds every tag of the exchange, written KEY=VALUE, such as team=payments. --limit sets how many rows the command returns: 20 by default, and at most 100. --system lists the exchanges of one system id, and --tag KEY:VALUE lists the exchanges that carry that tag. With both flags, a row has to match both.

SPEND has no value when no price covers the exchange: — (no-price) when its served name has no price, and — (class-not-priced) when a token class it used has no rate. PROVIDER is — when its served name has no price.

OUTCOME is one of these:

An exchange appears only after the service has read its capture, so the newest exchanges may not be in the list yet.

This is a ranking of conversations by spend, not a division: the rows do not add up to the period total. The service refuses a window longer than 24 hours by default, and the refusal names the longest window that you can ask for.