api docs v01

Purpose

Convert LLM token usage into USD

Design philosophy

The API expects to receive the JSON (or JSONL) that you received from your call to the LLM. It will then reply with the cost in USD.

There are various JSON shapes used by various providers and models to report usage. For ease of use, this API does not require you to "normalize" them. Just forward whatever you received. We'll figure it out.

It currently works with Anthropic, Google and OpenAI.

For Anthropic, it expects to see

• "model":
• "usage":
• "service_tier":

For Google, it expects to see

• "modelVersion":
• "usageMetadata":
• "serviceTier":

For OpenAI, it expects to see

• "model":
• "usage":
• "tool_usage":
• "service_tier":

Some models have multiple snapshots or aliases. They are all charged at the same rates, so we collapse each family into a single model ID.

Example : gpt-4o-2024-11-20 gpt-4o-2024-08-06 gpt-4o-2024-05-13 are all collapsed to gpt-4o.

Full list of model collapsing rules is available here.

Input

Send us the JSON (or JSONL) that you received from your call

Alternatively you can craft your own JSON with the same structure as a response from an LLM API call, and send that to us.

Usage

Endpoint: POST https://api.tokenstodollars.online/v01/calculate

Headers: X-API-KEY: your_api_key

Request body

{
  "provider": "openai",
  "model": "gpt-5.6-terra",
  "usage": {
    "prompt_tokens": 2620,
    "completion_tokens": 220,
    "total_tokens": 2840,
    "prompt_tokens_details": {
      "cached_tokens": 1792,
      "audio_tokens": 0
    }
  }
}

Success Response (example)

{
  "success": true,
  "provider": "openai",
  "model": "gpt-5.6-terra",
  "currency": "USD",
  "cost_usd": 0.010298,
  "usage_received": {
    "prompt_tokens": 2620,
    "completion_tokens": 220,
    "total_tokens": 2840,
    "prompt_tokens_details": {
      "cached_tokens": 1792,
      "audio_tokens": 0
    }
  },
  "usage_normalized": {
    "input_tokens": 2620,
    "cached_input_tokens": 1792,
    "output_tokens": 220
  },
  "ignored_usage_keys": [
    "prompt_tokens",
    "completion_tokens",
    "total_tokens"
  ],
  "unmatched_usage_keys": [],
  "breakdown": {
    "input_tokens": {
      "tokens": 2620,
      "usd_per_million_tokens": 2.5,
      "usd": 0.00655
    }
  },
  "pricing_entry": {
    "effective_from_utc": "2026-07-23T00:00:00Z",
    "source_url": "https://developers.openai.com/api/docs/pricing"
  }
}