> ## Documentation Index
> Fetch the complete documentation index at: https://docs.costory.io/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenRouter Billing Setup

> Connect OpenRouter billing to Costory with a Management API key. Import organization costs into Explorer next to AWS, GCP, Azure, and other LLM providers.

OpenRouter usage sits on a separate bill from AWS, GCP, Azure, and the model providers you route through. Connect with a **Management API key** so organization costs land in <Tooltip tip="Costory's main interface for exploring cloud costs across all connected providers." cta="See Glossary" href="/docs/glossary#cost-explorer">Explorer</Tooltip> with your other [billing datasources](/setup/billing).

This connector imports organization **costs** from the [Analytics query](https://openrouter.ai/docs/api/api-reference/analytics/query-analytics-data) API. Costory stores them as a billing datasource, the same as other SaaS billing sources.

<Info>
  Use a **Management API key**. A chat or inference key (`sk-or-v1-...`) returns 403 on analytics (`Only management keys can perform this operation`). Management keys cannot call completion endpoints.
</Info>

<Tabs>
  <Tab title="Manual setup">
    <Steps>
      <Step title="Create a Management API key">
        In [OpenRouter > Settings > Management keys](https://openrouter.ai/settings/management-keys), create a **Management API key**. Copy it immediately. It is shown once.

        Do **not** use a chat or inference key. See OpenRouter's [Management API keys](https://openrouter.ai/docs/guides/overview/auth/management-api-keys) guide.
      </Step>

      <Step title="Connect in Costory">
        Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then choose **OpenRouter** under **Billing**. The connect URL is `/integration/new/openrouter/billing`.&#x20;
      </Step>

      <Step title="Enter connection details">
        Fill **Connection name** (default **OpenRouter**) and **Management key**.

        **Organization name** is optional. It is a display label Costory stores as the billing-account name. It is not sent to OpenRouter. The management key already scopes the org.

        **Start date** is optional. Leave it empty to use Costory's default lookback.
      </Step>

      <Step title="Validate, then save">
        Click **Validate**. Costory calls `GET /api/v1/keys` with `Authorization: Bearer`. **Save** stays disabled until the key can read the Management API. An empty key list is still success. If this is the only billing source and it is demo data, Costory asks you to confirm before replacing it.
      </Step>
    </Steps>

    On first sync, Costory backfills up to **12 months** of organization costs, depending on what OpenRouter retains. New data then follows the usual [data refresh](/docs/data-refresh) cadence. SaaS sources typically appear in about **10 minutes**.
  </Tab>

  <Tab title="Terraform">
    Not supported yet.
  </Tab>
</Tabs>

## Field reference

| Field                 | Required | Description                                                                             |
| --------------------- | -------- | --------------------------------------------------------------------------------------- |
| **Connection name**   | Yes      | Label in **Integrations**.                                                              |
| **Management key**    | Yes      | Management API key from Settings > Management keys. Stored in Costory's secret manager. |
| **Organization name** | No       | Display label stored as billing-account name. Not sent to OpenRouter.                   |
| **Start date**        | No       | Optional start of the first sync. Leave empty for the default lookback.                 |

## What Costory includes

Costory pulls organization costs from OpenRouter's [Analytics query](https://openrouter.ai/docs/api/api-reference/analytics/query-analytics-data) API and maps them into <Tooltip tip="Costory's unified billing schema: the same dimensions everywhere (Provider, Billing account id, Service name, SKU ID, Region, Category, and more). In SQL and exports, column names use a cos_ prefix (for example cos_service_name)." cta="See Glossary" href="/docs/glossary#standard-columns">Standard Columns</Tooltip>.

Typical lines are billed credit usage for that OpenRouter organization. Explorer dollars follow OpenRouter **credits usage**, not a BYOK or token-list estimate.

**How to analyze OpenRouter costs**

* Spend over time: use the same date presets as other billing sources in Explorer
* Spend by model or SKU: group by **Service name** or **SKU** when those fields are populated from analytics
* Spend for this org: the optional **Organization name** is the **Billing account id** label

**What Costory does not include**

* Chat or inference keys (`sk-or-v1-...`)
* BYOK or `total_usage` estimates as billed dollars
* Serving-provider or `endpoint_id` splits (not on this connector yet)
* Taxes, credits, or invoice adjustments outside the analytics query

<Info>
  Rotate the Management API key from **Integrations** when you need a new credential. The stored organization name stays the same.
</Info>

## Troubleshooting

| Issue                                     | What to check                                                                                                                                                       |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Failed to authenticate                    | Paste a **Management API key** from [Management keys](https://openrouter.ai/settings/management-keys), not a chat or inference key.                                 |
| Access denied (403)                       | Inference keys cannot read analytics. Create a Management API key. The error text is `Only management keys can perform this operation`.                             |
| Management API endpoint not found         | Confirm the Management API is enabled for this organization.                                                                                                        |
| Validation succeeds but Explorer is empty | Wait for the first sync (about 10 minutes). Check the datasource date range on [Integrations](https://app.costory.io/integration). A new org can have no usage yet. |

## Related pages

<CardGroup cols={2}>
  <Card title="Billing Data" icon="database" href="/setup/billing">
    All billing providers and shared setup notes.
  </Card>

  <Card title="OpenAI billing" icon="robot" href="/setup/billing/openai">
    Import OpenAI Platform organization costs.
  </Card>

  <Card title="Allocate LLM cost per team" icon="sitemap" href="/use-cases/llm-ai-cost">
    Split OpenRouter, OpenAI, Anthropic, and cloud LLM spend by team.
  </Card>

  <Card title="Explorer" icon="chart-line" href="/features/cost-explorer">
    Filter and group OpenRouter spend with the rest of your stack.
  </Card>
</CardGroup>