Connect OpenAI

CloudQuell reads your OpenAI spend through a read-only Admin API key — dollars from OpenAI’s Costs API (the billing source of truth) and token usage from the Usage API. Nothing is written back to your OpenAI organization, and the key can never incur usage. Once connected, OpenAI spend flows into the same AI Spend view and ledger as your other providers.

Prerequisites

An OpenAI API-platform organization. ChatGPT-only accounts (Free, Plus, Enterprise, or Team without API usage) have no admin API and can’t be connected.
The Organization Owner role in that OpenAI organization — only Owners can create Admin API keys.
A CloudQuell admin — creating integrations requires the super_admin or admin role. See roles.

The three steps

1. Create a read-only Admin API key

In the OpenAI platform, go to platform.openai.com → Settings → Organization → Admin Keys and create a new admin key with Read Only permissions. You must be an Organization Owner to see this page.

Admin keys start with sk-admin-. Regular project keys (sk-proj-…) are scoped to a single project and will not work — the Costs and Usage APIs are organization-level and require an admin key.

2. Connect it in CloudQuell

In the CloudQuell admin, go to Integrations, open the OpenAI tile, and click Connect. Paste the admin key. CloudQuell validates the key live against OpenAI before saving — a bad key fails immediately, not on the first sync.

3. Done — the backfill starts

That’s it. The key is stored in AWS Secrets Manager — never in the database — and the first ingest kicks off right away.

What data appears, and when

On connect, CloudQuell backfills up to 12 months of history (shorter if OpenAI retains less for your organization), so you have trend context from the start. After that, OpenAI spend syncs daily — and each sync re-pulls a trailing 3-day window to absorb late billing corrections, so recent days may adjust slightly before settling.

Two sources feed the view:

Dollars come from OpenAI’s Costs API — the billing source of truth, so CloudQuell’s totals match your OpenAI invoice.
Token usage comes from the Usage API — the chat/completions and embeddings API families in v1.

In the AI Spend view you can break OpenAI spend down by:

Dimension	What you get
Model	Cost and tokens per model.
Day	Daily trend.
Token type	OpenAI-native types: uncached input, cached input, output, audio in/out, plus request counts.
Project	Spend per OpenAI Project, with display names.
API key	Token and request attribution per key. OpenAI exposes no per-key dollars, so this dimension shows usage, not cost.
Service tier	Batch vs. standard — batch runs at roughly a 50% discount, so this split shows your batch-adoption savings headroom.

Rotate or replace the key

You can rotate the key any time from the integration’s Manage dialog in Integrations — create a new read-only admin key at OpenAI, paste it in, and it’s validated live and swapped in Secrets Manager. Rotation doesn’t interrupt or reset your ingested data. If OpenAI revokes or expires the key, syncs stop until you paste a fresh one the same way.

Troubleshooting

“Invalid key” when connecting

The live validation failed — OpenAI rejected the key (a 401). Check for a copy/paste truncation, and confirm the key hasn’t been revoked or expired at platform.openai.com → Settings → Organization → Admin Keys. Recreate the key and paste it again.

The key connects nothing / lacks permission

The admin key was created without Read Only permissions, so it can’t read the Costs and Usage endpoints. Create a new admin key and select Read Only when creating it.

My key starts with `sk-proj-`

That’s a project key, not an admin key — it can’t read organization-level cost data. Ask an Organization Owner to create an Admin Key (sk-admin-…) with Read Only permissions from Settings → Organization → Admin Keys.

I can’t find “Admin Keys” in OpenAI’s settings

Only Organization Owners on the API platform see it. If your OpenAI account is ChatGPT-only, there is no admin API to connect — CloudQuell can only ingest API-platform spend.

What’s not included

Azure OpenAI Service — billed by Microsoft, not OpenAI; it’s covered by the Azure integration instead.
AWS Bedrock — AWS-billed and already in your AWS cloud spend, so it’s excluded here to avoid double-counting.
ChatGPT Enterprise / Team seats — seat licensing doesn’t appear in the API Costs endpoint, so it’s not in this integration.

Remove the integration

Deleting the OpenAI integration is a permanent hard delete: it removes all ingested OpenAI cost data and the stored key from Secrets Manager. This can’t be undone — see manage your integrations.

Query it from an agent

The MCP server’s get_ai_spend tool accepts provider: "openai", so a connected agent can query OpenAI spend by model, token type, project, API key, or service tier in plain language.