---
title: "AI Token Spend"
method: POST
path: "/v1/tools/estimate_ai_token_spend"
tags: ["compliance_mandate", "ai-spend", "token-pricing", "llm-cost", "budgeting", "price-table", "dated-snapshot", "integer-minor-units", "mcp:estimate_ai_token_spend"]
---

# AI Token Spend

`POST /v1/tools/estimate_ai_token_spend`

## Request

- Base URL: `https://ainumbers.co`
- URL: `https://ainumbers.co/v1/tools/estimate_ai_token_spend`
- Auth: none declared

Monthly AI token spend estimator and cross-model comparator: per-model monthly cost, cost per request, the component breakdown, and a cheapest-first ranking, priced from a dated price table by an as_of date. Integer USD micros per million tokens with an overflow-safe floor-split cost formula. Refuses ambiguous price entries, missing component prices and cap overruns with named reasons. Prices are an input, never kernel constants: the default is the dated 2026-10-04 provider-page snapshot.

**Tool URL:** https://ainumbers.co/chaingraph/art-704-ai-token-spend.html
**AP2/Policy Mandate export:** yes

## Request body

- object
  - `as_of` string, required: Pricing date, a real calendar date as YYYY-MM-DD. The node reads no clock; an entry applies when effective_from <= as_of <= effective_through.
  - `usage` object, required: Requests per month, input and output tokens per request, cached-input and batch/long-context shares in bp, cache-write tokens with a 5m or 1h TTL.
    - `requests_per_month` integer: Non-negative integer at most 1e12: billable requests per month.
    - `input_tokens_per_request` integer: Non-negative integer input tokens per request; input tokens per month (times requests_per_month) must not exceed the 1e12 per-component cap.
    - `cached_input_share_bp` integer: Integer basis-point share of input tokens served from cache, 0..10000.
    - `cache_write_tokens_per_request` integer: Non-negative integer cache-write tokens per request; monthly cache-write tokens (times requests_per_month) must not exceed the 1e12 per-component cap.
    - `cache_write_ttl` '5m' | '1h': Cache-write TTL class: '5m' or '1h'.
    - `output_tokens_per_request` integer: Non-negative integer output tokens per request; output tokens per month (times requests_per_month) must not exceed the 1e12 per-component cap.
    - `batch_share_bp` integer: Integer basis-point share priced at batch rates, 0..10000; batch_share_bp plus long_context_share_bp must not exceed 10000.
    - `long_context_share_bp` integer: Integer basis-point share priced at long-context rates, 0..10000; batch_share_bp plus long_context_share_bp must not exceed 10000.
  - `price_table` object, required: Dated snapshot: snapshot_verified_on, currency USD, unit usd_micros_per_million_tokens, and models[] with tier, effective dates and micros prices.
  - `compare` unknown[], required: Model names to price and rank, cheapest first; ties break by the model string.
    - unknown

## Response `200`

Successful tool execution result

- object: output_payload: as_of, snapshot_verified_on, snapshot_age_days, results[]{provider, model, tier, monthly_micros, per_request_micros, components{input, cached_input, cache_write, output}, price_entry_source_sha256}, ranking[model...], cheapest, refusals[]{provider, model, code, text}, refusal_reason, domain_errors[], scope_note.

---

[API](https://skmtc.dev/ainumbers/apis/ainumbers-co-fintech-intelligence-suite.md) · [All operations](https://skmtc.dev/ainumbers/apis/ainumbers-co-fintech-intelligence-suite/llms.txt) · [OpenAPI document](https://skmtc.dev/ainumbers/apis/ainumbers-co-fintech-intelligence-suite/revisions/b462e4f5bb28?raw)