openrouterteam/openrouter-generations

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 && npx tsx get-generation.ts gen-1234567890
npx tsx get-generation.ts --id gen-1234567890 --json

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:

cd <skill-path>/scripts && npx tsx get-generation-content.ts gen-1234567890
npx tsx get-generation-content.ts --id gen-1234567890 --json

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

curl -G https://openrouter.ai/api/v1/generation \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -d id=gen-1234567890

Get content

curl -G https://openrouter.ai/api/v1/generation/content \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -d id=gen-1234567890

Response Schemas

Metadata response (/api/v1/generation)

{
  "data": {
    "id": "gen-3bhGkxlo4XFrqiabUM7NDtwDzWwG",
    "api_type": "completions",
    "model": "openai/gpt-4o",
    "provider_name": "OpenAI",
    "created_at": "2024-07-15T23:33:19.433273+00:00",
    "tokens_prompt": 10,
    "tokens_completion": 25,
    "native_tokens_reasoning": 5,
    "native_tokens_cached": 3,
    "total_cost": 0.0015,
    "usage": 0.0015,
    "upstream_inference_cost": 0.0012,
    "latency": 1250,
    "generation_time": 1200,
    "finish_reason": "stop",
    "streamed": true,
    "is_byok": false,
    "cancelled": false,
    "router": "openrouter/auto",
    "service_tier": "priority",
    "provider_responses": [
      {
        "provider_name": "OpenAI",
        "model_permaslug": "openai/gpt-4o",
        "status": 200,
        "latency": 1200,
        "is_byok": false
      }
    ]
  }
}

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

{
  "data": {
    "input": {
      "prompt": "What is the meaning of life?",
      "messages": [
        {
          "content": "What is the meaning of life?",
          "role": "user"
        }
      ]
    },
    "output": {
      "completion": "The meaning of life is a philosophical question...",
      "reasoning": null
    }
  }
}

Common Use Cases

Debug a failed generation

# Check what happened — look at finish_reason, provider_responses, and cancelled
cd <skill-path>/scripts && npx tsx get-generation.ts gen-abc123 --json

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

cd <skill-path>/scripts && npx tsx get-generation.ts gen-abc123

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

Review what was actually sent/received

cd <skill-path>/scripts && npx tsx get-generation-content.ts gen-abc123

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 |