Cycles

Appearance

Cost Estimation Cheat Sheet ​

This guide answers the most common question when adopting Cycles: how much should I reserve for a given LLM call?

For the broader strategy guide on estimation approaches, see Estimate Exposure Before Execution.

The unit: USD_MICROCENTS ​

Cycles uses USD_MICROCENTS as its primary currency unit:

1 USD_MICROCENT = 10⁻⁶ cents = 10⁻⁸ dollars
$1.00 = 100,000,000 microcents
$0.01 = 1,000,000 microcents

The formula for converting provider pricing to microcents:

microcents = (price_per_million_tokens / 1,000,000) × token_count × 100,000,000

Simplified:

microcents = price_per_million_tokens × token_count × 100

Provider pricing reference ​

OpenAI ​

ModelInput (per 1M tokens)Output (per 1M tokens)Input (microcents/token)Output (microcents/token)
gpt-5.6-sol$5.00$30.005003,000
gpt-5.6-terra$2.50$15.002501,500
gpt-5.6-luna$1.00$6.00100600
gpt-5$1.25$10.001251,000
gpt-5-mini$0.25$2.0025200
gpt-5-nano$0.05$0.40540
gpt-4o$2.50$10.002501,000
gpt-4o-mini$0.15$0.601560
gpt-4.1$2.00$8.00200800
gpt-4.1-mini$0.40$1.6040160
gpt-4.1-nano$0.10$0.401040
o3$2.00$8.00200800
o3-mini$1.10$4.40110440
o4-mini$1.10$4.40110440

Anthropic ​

ModelInput (per 1M tokens)Output (per 1M tokens)Input (microcents/token)Output (microcents/token)
Claude Opus 4.8$5.00$25.005002,500
Claude Sonnet 4.6$3.00$15.003001,500
Claude Haiku 4.5$1.00$5.00100500

Google ​

ModelInput (per 1M tokens)Output (per 1M tokens)Input (microcents/token)Output (microcents/token)
Gemini 2.5 Pro$1.25$10.001251,000
Gemini 2.5 Flash$0.30$2.5030250
Gemini 2.5 Flash-Lite$0.10$0.401040

Groq on-demand ​

ModelInput (per 1M tokens)Output (per 1M tokens)Input (microcents/token)Output (microcents/token)
openai/gpt-oss-20b$0.075$0.307.530
openai/gpt-oss-120b$0.15$0.601560
qwen/qwen3.6-27b$0.60$3.0060300

Open-model pricing and availability vary by host. The table above is specifically Groq's on-demand pricing, not a universal rate for those model families. Round the final reservation amount up when a per-token conversion is fractional. Self-hosted models have no provider token invoice, but still consume compute; use a unit that matches what you want to bound. See the Groq integration guide and Ollama integration guide.

Note

Provider rates above were checked on July 24, 2026. The OpenAI table includes the current GPT-5.6 family plus selected older models that still appear in examples. GPT-5.6 cache reads are discounted, cache writes cost 1.25 times the uncached input rate, and requests above 272,000 input tokens use higher rates for the full request. Prices, caching rules, long-context tiers, and regional premiums change; check each provider's pricing page before deploying. The formulas remain the same.

Quick estimation formula ​

For a single LLM call:

estimate = (max_input_tokens × input_microcents) + (max_output_tokens × output_microcents)

Then add a safety buffer:

reservation_amount = estimate × 1.2   # 20% buffer

Example: GPT-5.6 Luna call with 2,000 input tokens, 1,000 max output tokens ​

input_cost  = 2,000 × 100 = 200,000 microcents
output_cost = 1,000 × 600 = 600,000 microcents
total       = 800,000 microcents ($0.008)
with buffer = 960,000 microcents

Example: Claude Sonnet 4.6 call with 4,000 input tokens, 2,000 max output tokens ​

input_cost  = 4,000 × 300   = 1,200,000 microcents
output_cost = 2,000 × 1,500 = 3,000,000 microcents
total       = 4,200,000 microcents ($0.042)
with buffer = 5,040,000 microcents

Estimation helpers in code ​

python
import math

# Simple cost estimator
def estimate_cost(input_tokens: int, max_output_tokens: int, model: str) -> int:
    """Return estimated cost in USD_MICROCENTS with 20% buffer."""
    rates = {
        "gpt-5.6-sol":     (500, 3000),
        "gpt-5.6-terra":   (250, 1500),
        "gpt-5.6-luna":    (100, 600),
        "gpt-4o":          (250, 1000),
        "gpt-4o-mini":     (15, 60),
        "gpt-4.1":         (200, 800),
        "gpt-4.1-mini":    (40, 160),
        "gpt-4.1-nano":    (10, 40),
        "claude-sonnet":   (300, 1500),
        "claude-haiku":    (100, 500),
        "gemini-2.5-pro":  (125, 1000),
        "gemini-2.5-flash":(30, 250),
        "groq:gpt-oss-20b":(7.5, 30),
        "groq:gpt-oss-120b":(15, 60),
        "groq:qwen3.6-27b": (60, 300),
    }
    input_rate, output_rate = rates.get(model, (100, 600))
    estimate = (input_tokens * input_rate) + (max_output_tokens * output_rate)
    return math.ceil(estimate * 1.2)

# Usage with the @cycles decorator
@cycles(
    estimate=lambda prompt, max_tokens=1000: estimate_cost(
        len(prompt) // 4, max_tokens, "gpt-5.6-luna"
    ),
    action_kind="llm.completion",
    action_name="openai:gpt-5.6-luna",
)
def ask(prompt: str, max_tokens: int = 1000) -> str:
    ...
typescript
function estimateCost(inputTokens: number, maxOutputTokens: number, model: string): number {
  const rates: Record<string, [number, number]> = {
    "gpt-5.6-sol":     [500, 3000],
    "gpt-5.6-terra":   [250, 1500],
    "gpt-5.6-luna":    [100, 600],
    "gpt-4o":          [250, 1000],
    "gpt-4o-mini":     [15, 60],
    "gpt-4.1":         [200, 800],
    "gpt-4.1-mini":    [40, 160],
    "gpt-4.1-nano":    [10, 40],
    "claude-sonnet":   [300, 1500],
    "claude-haiku":    [100, 500],
    "gemini-2.5-pro":  [125, 1000],
    "gemini-2.5-flash":[30, 250],
    "groq:gpt-oss-20b":[7.5, 30],
    "groq:gpt-oss-120b":[15, 60],
    "groq:qwen3.6-27b": [60, 300],
  };
  const [inputRate, outputRate] = rates[model] ?? [100, 600];
  const estimate = inputTokens * inputRate + maxOutputTokens * outputRate;
  return Math.ceil(estimate * 1.2);
}

const ask = withCycles(
  {
    estimate: (prompt: string) => estimateCost(Math.ceil(prompt.length / 4), 1000, "gpt-5.6-luna"),
    actionKind: "llm.completion",
    actionName: "openai:gpt-5.6-luna",
  },
  async (prompt: string) => { ... },
);

Common reservation amounts ​

Quick reference for typical operations (including 20% buffer):

OperationModelTypical Estimate (microcents)Approx USD
Short chat reply (500 in / 200 out)gpt-5.6-luna204,000$0.002
Long chat reply (2,000 in / 1,000 out)gpt-5.6-luna960,000$0.010
Document summary (8,000 in / 2,000 out)gpt-5.6-luna2,400,000$0.024
Short chat reply (500 in / 200 out)gpt-4o-mini23,400$0.0002
Long chat reply (2,000 in / 1,000 out)claude-sonnet2,520,000$0.025
Code generation (4,000 in / 4,000 out)claude-sonnet8,640,000$0.086

When you don't know the exact token count ​

Use these rules of thumb:

  • 1 token is roughly 4 characters of English text (or ~0.75 words)
  • For input: count the prompt characters and divide by 4
  • For output: use the max_tokens parameter you're passing to the provider
  • Always round up — over-reserving temporarily locks budget but releases the unused portion on commit

Using TOKENS unit instead of USD_MICROCENTS ​

If you prefer to budget in tokens rather than dollars:

python
@cycles(estimate=2000, unit="TOKENS", action_kind="llm.completion", action_name="gpt-5.6-luna")
def ask(prompt: str) -> str:
    ...

This is simpler but does not account for different costs across models. Use TOKENS when all your calls use the same model, or when you want model-agnostic budgets.

Overage policies and estimation ​

Your estimation strategy should match your overage policy:

PolicyEstimation approach
REJECTReserve conservatively (use 120-150% buffer). Under-reserving causes commit failures.
ALLOW_IF_AVAILABLEReserve your best estimate. If actual exceeds reserved, the delta is deducted from remaining budget.
ALLOW_WITH_OVERDRAFTReserve normally. Overage is allowed up to the overdraft limit. Best for SLA-critical operations.

Next steps ​