Skip to content

feat: add cost and cost_details to ChatGenerationTokenUsage schema#66

Open
untilhamza wants to merge 1 commit intoOpenRouterTeam:mainfrom
untilhamza:feat/add-cost-fields-to-usage
Open

feat: add cost and cost_details to ChatGenerationTokenUsage schema#66
untilhamza wants to merge 1 commit intoOpenRouterTeam:mainfrom
untilhamza:feat/add-cost-fields-to-usage

Conversation

@untilhamza
Copy link

@untilhamza untilhamza commented Mar 4, 2026

Summary

The OpenRouter API returns cost, is_byok, and cost_details in the usage object of chat completion responses, but the OpenAPI spec doesn't define these fields — so they're silently dropped during model_dump().

This PR adds the missing fields to ChatGenerationTokenUsage in in.openapi.yaml.

Fields added

Field Type Description
cost number, nullable Total generation cost in USD
is_byok boolean, nullable Whether the request used bring-your-own-key
cost_details.upstream_inference_cost number, nullable Total upstream inference cost
cost_details.upstream_inference_prompt_cost number, nullable Upstream cost for prompt tokens
cost_details.upstream_inference_completions_cost number, nullable Upstream cost for completion tokens

The problem

Raw HTTP response includes cost data:

{
  "usage": {
    "prompt_tokens": 158,
    "completion_tokens": 152,
    "total_tokens": 310,
    "cost": 8.41005e-05,
    "is_byok": false,
    "cost_details": {
      "upstream_inference_cost": 8.495e-05,
      "upstream_inference_prompt_cost": 8.95e-06,
      "upstream_inference_completions_cost": 7.6e-05
    }
  }
}

But after the SDK deserializes via model_dump(), cost and cost_details are gone:

from openrouter import OpenRouter

client = OpenRouter()
resp = client.chat.send(model="x-ai/grok-4.1-fast", messages=[...])
print(resp.usage.cost)  # AttributeError — field doesn't exist

Verification

I patched ChatGenerationTokenUsage locally to add these fields and confirmed cost data flows through correctly after model_dump().

Fixes #65

The OpenRouter API returns `cost`, `is_byok`, and `cost_details` in
the `usage` object of chat completion responses, but the OpenAPI spec
doesn't define these fields. This causes them to be silently dropped
during deserialization.

Adds the following optional/nullable fields to ChatGenerationTokenUsage:
- `cost` (number) — total generation cost in USD
- `is_byok` (boolean) — whether the request used bring-your-own-key
- `cost_details` (object) — breakdown with upstream_inference_cost,
  upstream_inference_prompt_cost, upstream_inference_completions_cost

Fixes OpenRouterTeam#65
@untilhamza
Copy link
Author

@mattapperson , @robert-j-y please take a look at this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

cost and cost_details missing from ChatGenerationTokenUsage schema

1 participant