> ## 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.

# OpenAI Billing Setup

> Connect OpenAI organization costs to Costory with a read-only Admin API key. Import Platform API usage into Explorer next to AWS, GCP, and Azure.

OpenAI Platform spend sits on a separate bill from AWS, GCP, and Azure. Connect with a **read-only Admin 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 **OpenAI Platform (API usage)** organization costs from the [Costs API](https://developers.openai.com/api/reference/resources/admin/subresources/organization/subresources/usage/methods/costs). Costory stores them as a billing datasource, the same as other SaaS billing sources.

<Info>
  Azure OpenAI (Cognitive Services) is billed through Azure. Use the [Azure billing connector](/setup/billing/azure) for that spend. ChatGPT Enterprise and Codex are not on this connector.
</Info>

<Tabs>
  <Tab title="Manual setup">
    <Steps>
      <Step title="Create an Admin API key">
        In [OpenAI Platform > Settings > Admin keys](https://platform.openai.com/settings/organization/admin-keys), create an **Admin API key** (`sk-admin-...`). You must be an organization **admin**. A project inference key (`sk-...` or `sk-proj-...`) will not work. Copy the key immediately. It is shown once.
      </Step>

      <Step title="Grant read-only scopes">
        Grant **read-only** scopes only. Do not grant write.

        | Scope                   | API id                | Required                                                                                      |
        | ----------------------- | --------------------- | --------------------------------------------------------------------------------------------- |
        | **Usage**               | `api.usage.read`      | Yes. Costory cannot ingest spend without it.                                                  |
        | **API keys + Projects** | `api.management.read` | Recommended. Without it, spend still lands, but key, user, and project names stay as raw ids. |
      </Step>

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

      <Step title="Enter connection details">
        Fill **Connection name** (default **OpenAI**) and **Admin API key**. **Start date** is optional. Leave it empty to use Costory's default lookback.
      </Step>

      <Step title="Validate, then save">
        Click **Validate**. Costory calls `GET /v1/organization/costs` with `Authorization: Bearer`. **Save** stays disabled until the Admin key can read organization costs. 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 OpenAI 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**.                                                                       |
| **Admin API key**   | Yes      | Organization Admin key (`sk-admin-...`) with **Usage** read. Stored in Costory's secret manager. |
| **Start date**      | No       | Optional start of the first sync. Leave empty for the default lookback.                          |

## What Costory includes

Costory pulls organization costs from OpenAI's Costs 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 include billed Platform usage for that organization (models, line items, and the project or API key OpenAI returns on the Costs API).

**How to analyze OpenAI costs**

* Spend by project: one OpenAI **project** (and project key) per team is the split the Costs API exposes. Map those projects onto a [virtual dimension](/features/tagging/dimensions) for showback. See [Allocate LLM cost per team](/use-cases/llm-ai-cost).
* Spend by model or line item: group by **Service name** or **SKU**
* Spend by API key or user: names appear when the key has **API keys + Projects** read. Otherwise you see raw ids.

**What Costory does not include**

* Azure OpenAI charges (use the [Azure connector](/setup/billing/azure))
* ChatGPT Enterprise or Codex billing
* Taxes, credits, or invoice adjustments outside the Costs API
* Per-request application metadata (feature, route, customer). OpenAI's export does not carry those labels.

<Info>
  Rotate the Admin API key from **Integrations** when you need a new credential. Keep **Usage** read on the replacement key.
</Info>

## Troubleshooting

| Issue                                     | What to check                                                                                                                                                                     |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Failed to authenticate                    | Confirm you pasted an **Admin API key** (`sk-admin-...`), not a project inference key. Recreate it in [Admin keys](https://platform.openai.com/settings/organization/admin-keys). |
| Access denied                             | Grant **Usage** (`api.usage.read`) on a **read-only** Admin key.                                                                                                                  |
| Costs API endpoint not found              | Confirm the Admin API is enabled for this organization and that you are an organization admin.                                                                                    |
| Spend lands, names are raw ids            | Add **API keys + Projects** (`api.management.read`). Costory does not block save when this scope is missing.                                                                      |
| 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).                                                |

## Related pages

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

  <Card title="Anthropic billing" icon="robot" href="/setup/billing/anthropic">
    Connect Anthropic Claude Console and claude.ai costs.
  </Card>

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

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