/openrouter-generations

name: openrouter-generations
description: Retrieve detailed metadata and stored content for individual OpenRouter generations. Use when the user wants to inspect a specific request — its cost, latency, token usage, provider routing, or the actual prompt/completion text — or is debugging a failed or unexpected generation.
version: 0.1.0

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](https://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](https://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