openrouter-generations skill by openrouterteam

openrouter-generations

Retrieve detailed metadata and stored content for individual OpenRouter generations. Use this skill when you need to inspect a specific request — its cost, latency, token usage, provider routing, or the actual prompt/completion text.

Prerequisites

Any valid OpenRouter API key (regular or management key). Get one at openrouter.ai/settings/keys.
Pass it via --api-key <key> or set the OPENROUTER_API_KEY environment variable
Generation IDs look like gen-1234567890 or gen-aBcDeFgHiJkLmNoPqRsT.

First-Time Setup

cd <skill-path>/scripts && npm install

Endpoints

Endpoint	Method	Purpose
`/api/v1/generation`	GET	Request metadata and usage (tokens, cost, latency, model, provider)
`/api/v1/generation/content`	GET	Stored prompt and completion text

Both take a single query parameter: id (the generation ID).

Full API reference: openrouter.ai/docs/api/api-reference/generations/get-generation

Workflow

1. Get generation metadata

Retrieves everything about a generation except the actual prompt/completion text:

cd <skill-path>/scripts

What you get back:

Model & routing: model, provider_name, router, service_tier
Tokens: tokens_prompt, tokens_completion, native_tokens_reasoning, native_tokens_cached
Cost: total_cost, usage, upstream_inference_cost, cache_discount
Performance: latency, generation_time, moderation_latency
Status: finish_reason, streamed, cancelled, is_byok
Context: created_at, app_id, external_user, session_id, request_id
Provider chain: provider_responses array showing fallback attempts with per-provider latency and status

2. Get generation content

Retrieves the stored prompt and completion:

What you get back:

Input: prompt (raw text) and/or messages (array of {role, content})
Output: completion (the model's response) and reasoning (chain-of-thought, if applicable)

Note: Content is only available if the generation was not made with Zero Data Retention (ZDR) enabled. If ZDR was on, this endpoint returns empty/null content.

Direct API Usage (curl)

Get metadata

Get content

Response Schemas

Metadata response (`/api/v1/generation`)

Content response (`/api/v1/generation/content`)

Common Use Cases

Debug a failed generation

Look for:

finish_reason = "length" means the model hit max tokens
finish_reason = "content_filter" means content was filtered
cancelled = true means the request was cancelled by the client
provider_responses with multiple entries means fallbacks occurred

Check cost of a specific request

Check total_cost (what you were charged) vs upstream_inference_cost (what the provider charged OpenRouter).

Review what was actually sent/received

Useful for debugging unexpected outputs — verify the actual prompt sent and completion received.

Trace a multi-generation session

If you have a request_id or session_id from one generation, you can find related generations via the analytics query endpoint (see openrouter-analytics skill).

Error Handling

Status	Meaning
401	Invalid or missing API key
403	You don't have access to this generation (belongs to another user)
404	Generation ID not found
429	Rate limited — wait and retry
500	Server error — retry
502	Upstream failure — retry

Key Fields Reference

Metadata fields

Field	Type	Description
`id`	string	Generation ID (`gen-...`)
`model`	string	Model permaslug (e.g., `openai/gpt-4o`)
`provider_name`	string\|null	Provider that served the request
`api_type`	string	One of: `completions`, `embeddings`, `rerank`, `tts`, `stt`, `video`
`tokens_prompt`	int\|null	Prompt token count
`tokens_completion`	int\|null	Completion token count
`native_tokens_reasoning`	int\|null	Reasoning/thinking tokens
`native_tokens_cached`	int\|null	Cached input tokens
`total_cost`	number	Total cost in USD
`usage`	number	Usage amount in USD
`upstream_inference_cost`	number\|null	Provider's cost in USD
`cache_discount`	number\|null	Discount from caching
`latency`	number\|null	Total latency in ms
`generation_time`	number\|null	Model generation time in ms
`moderation_latency`	number\|null	Moderation check time in ms
`finish_reason`	string\|null	Why generation stopped (`stop`, `length`, `content_filter`, etc.)
`native_finish_reason`	string\|null	Raw finish reason from provider
`streamed`	bool\|null	Whether response was streamed
`is_byok`	bool	Whether user's own provider key was used
`cancelled`	bool\|null	Whether request was cancelled
`app_id`	int\|null	OAuth app ID
`external_user`	string\|null	External user identifier (X-External-User header)
`session_id`	string\|null	Session grouping ID
`request_id`	string\|null	Request grouping ID (all gens from one API call)
`router`	string\|null	Router used (e.g., `openrouter/auto`)
`service_tier`	string\|null	Provider service tier
`web_search_engine`	string\|null	Search engine used (e.g., `exa`, `firecrawl`)
`num_search_results`	int\|null	Number of search results included
`provider_responses`	array\|null	Provider attempt chain with per-provider latency/status

Content fields

Field	Type	Description
`data.input.prompt`	string\|null	Raw prompt text
`data.input.messages`	array\|null	Messages array (`[{role, content}]`)
`data.output.completion`	string\|null	Model's completion text
`data.output.reasoning`	string\|null	Chain-of-thought reasoning