Cost Fields in Responses

Track Costs in Real Time

Every Grok API response carries the details of what it just cost. Many teams discover this information too late, when the monthly bill arrives, even though it’s available request by request. By leveraging it from the start of integration, you spot drift within an hour of it appearing: a system prompt that doubled in size after a deployment, a poorly calibrated retry loop replaying the same calls, or context crossing a billing threshold. Without this tracking, these incidents remain invisible until the statement.

The usage Object

Every response includes a usage object detailing token consumption and associated cost:

{
  "usage": {
    "prompt_tokens": 1250,
    "completion_tokens": 340,
    "total_tokens": 1590,
    "cached_tokens": 800,
    "cost_in_usd_ticks": 5000000000,
    "cost_in_nano_usd": 500000000
  }
}

The four counting fields read as follows.

One detail prevents a common mistake: cached_tokens is included in prompt_tokens, not added to it. In the example above, 1,250 tokens entered the model, 800 came from cache, and only 450 were billed at the full rate. If your aggregator adds both fields, it will double-count the cached portion and artificially inflate your volume statistics.

Two Scales for the Same Cost

The request cost is provided in two integer units. This choice isn’t arbitrary: expressing fractions of a cent in floating-point numbers introduces rounding errors that become visible when aggregating millions of calls. Integers avoid this problem entirely.

The cost_in_usd_ticks field counts in “ticks,” with 10 billion ticks per dollar. The value 5,000,000,000 in the example therefore corresponds to $0.50, and one million ticks equals $0.0001. The conversion fits in one line:

cost_usd = cost_in_usd_ticks / 10_000_000_000

The cost_in_nano_usd field counts in nano-dollars, with one billion nano-dollars per dollar. The 500,000,000 in the example represents the same amount, $0.50, and one thousand nano-dollars equals $0.000001. The conversion follows the same logic:

cost_usd = cost_in_nano_usd / 1_000_000_000

Both fields describe the same amount at different scales. cost_in_nano_usd is more intuitive to handle, while cost_in_usd_ticks offers slightly higher precision. Pick one and stick with it throughout your measurement chain: mixing both in the same aggregate is the best way to get inconsistent totals.

Build a Cost Tracker

In production, a single accumulator is enough to turn these fields into a dashboard. The class below records each usage object and exposes the cumulative cost along with the cache rate:

class CostTracker:
    def __init__(self):
        self.total_nano_usd = 0
        self.requests = 0
        self.input_tokens = 0
        self.output_tokens = 0
        self.cached_tokens = 0

    def record(self, usage):
        self.total_nano_usd += usage.get("cost_in_nano_usd", 0)
        self.requests += 1
        self.input_tokens += usage.get("prompt_tokens", 0)
        self.output_tokens += usage.get("completion_tokens", 0)
        self.cached_tokens += usage.get("cached_tokens", 0)

    @property
    def total_cost_usd(self):
        return self.total_nano_usd / 1_000_000_000

    @property
    def cache_rate(self):
        if self.input_tokens == 0:
            return 0
        return self.cached_tokens / self.input_tokens

Next, attach thresholds to total_cost_usd. A first threshold at 80% of the daily budget triggers an informational alert for the technical team; a second at 95% becomes a critical alert requiring human decision; at 100%, the application automatically cuts non-critical requests—batch jobs, pre-computations, deferred enrichments—and allows only direct user traffic. This graceful degradation is better than a sudden service stop on a peak day.

Analyze the Cache Rate

The cache_rate property deserves a dashboard of its own, as it directly reflects the quality of your prompt structure.

A rate that drops sharply from one week to the next is almost always a sign of a deployment that introduced a variable at the start of the prompt. The next lesson details the mechanism; for now, remember that this figure is a regression indicator as valuable as an error rate.

Prices as of August 5, 2026 — prices evolve regularly: before any budget calculation, check the current rate card on the official xAI models and pricing page.

Key Takeaways

• Every API response contains a usage object with token details and cost
• cost_in_usd_ticks: 10 billion ticks = $1 USD
• cost_in_nano_usd: 1 billion nano-USD = $1 USD
• The cached_tokens field measures cache efficiency
• Build a cost tracker in production with budget alerts