OpenAI Integration
Connect your OpenAI account to track GPT, o-series, and other model costs in Grafient.
Overview
Grafient connects to your OpenAI account using the Costs API endpoint with a read-only Admin Key. This integration supports any models and services returned by the OpenAI Costs endpoint, including GPT-4, GPT-4o, o1, o3, DALL-E, embeddings, and more.
The OpenAI Costs endpoint is only accessible with an Admin API key. Standard API keys and project-scoped keys do not have access to organization-level cost data.
Prerequisites
Before you begin, make sure you have:
- An OpenAI Organization account — the Costs API is scoped to organizations, not individual users.
- Organization Owner role — only owners can create Admin API keys. Organization readers and members do not have this permission.
- A Grafient account on the Free, Pro, or Ultimate plan.
Permissions and Security
Grafient requires a read-only Admin API key. When creating the key in the OpenAI Console, set the permissions to Read only. This ensures the key cannot be used to create completions, modify organization settings, or perform any cost-incurring actions.
Grafient only reads the following data:
- Daily cost reports grouped by model and token type
- Cost metadata (service, model, input/output/cached breakdown)
Your API key is encrypted with AES-256-GCM before storage and is never exposed after the initial connection.
Always select Read only permissions when creating the Admin Key. This follows the principle of least privilege and ensures your key cannot be used for anything beyond reading cost data.
Create a Connection
Step 1: Create a Read-Only Admin Key in OpenAI
- Log in to the OpenAI Platform.
- Click the Settings gear icon in the left sidebar.
- Navigate to Organization > Admin API Keys (or go directly to the Admin Keys page).
- Click + Create new admin key at the top of the page.
- For Name, enter a descriptive identifier such as
Grafient Integration. - For Permissions, select Read only.
- Click Create and copy the generated key immediately.
The key starts with sk-admin- and is only shown once. If you lose it, you will need to create a new one. Store it securely until you complete the next step.
Step 2: Add the Key to Grafient
- In Grafient, navigate to the Integrations page from the sidebar.
- Click Add Integration.
- Select OpenAI as the provider.
- Enter a label to identify this integration (e.g.,
Production — OpenAI). If left blank, a default label is generated for you. - Paste the Admin API key you copied in Step 1.
- Click Test Connection — a green checkmark confirms the key is valid.
- Click Add Integration to save.
What Happens Next
Once you add the integration, Grafient will:
- Validate your API key against the OpenAI Costs endpoint.
- Backfill historical costs — up to 30 days on Free, or 180 days on Pro/Ultimate (the maximum OpenAI retains).
- Sync daily via an automated job at 6 AM UTC to pull the previous day's finalized cost data.
Your costs will appear on the Dashboard within a few seconds of the initial sync. You can also click Force Sync on the integration card at any time to pull the latest data.
Data Collected
| Data Point | Description |
|---|---|
| Daily cost (USD) | Total spend per day, broken down by model |
| Model breakdown | Cost attributed to each model (e.g., GPT-4o, o3, text-embedding-3-small) |
| Input tokens | Standard input token cost |
| Output tokens | Output token cost |
| Cached tokens | Cached input token cost |
| Line item detail | Service-level breakdown (e.g., "gpt-4o, input" and "gpt-4o, output") |
API Endpoint Used
Grafient calls a single endpoint:
| Endpoint | Purpose |
|---|---|
GET /v1/organization/costs | Daily cost data grouped by line item, with 1-day bucket width |
Requests are paginated (up to 180 results per page) and sent sequentially to respect rate limits.
Supported Models
All models and services available through the OpenAI Costs endpoint are tracked automatically, including:
- Chat Completions: GPT-4, GPT-4o, GPT-4o-mini, GPT-4.1, GPT-3.5 Turbo
- Reasoning: o1, o3, o3-mini, o4-mini
- Embeddings: text-embedding-3-small, text-embedding-3-large, text-embedding-ada-002
- Images: DALL-E 2, DALL-E 3
- Audio: Whisper, TTS
- Fine-tuning: Any fine-tuned model variants
New models are tracked automatically as they appear in the Costs API — no configuration changes needed.
Data Freshness
OpenAI cost data is typically available within a few minutes of API usage. The Costs endpoint is authoritative for billing reconciliation, meaning the values match what appears on your OpenAI invoice.
The daily cron sync at 6 AM UTC captures the previous day's finalized data. For real-time visibility, use Force Sync on your integration card.
Troubleshooting
"Test Connection" fails
- Verify the key prefix: The key must start with
sk-admin-. Standard API keys (sk-proj-orsk-) do not have access to the Costs endpoint. - Check your role: Only Organization Owners can create Admin API keys. Go to Settings > Organization > Members in the OpenAI Console to verify your role. If you are a Reader or Member, ask an Owner to create the key.
- Confirm organization setup: The Costs endpoint is scoped to organizations. Verify that your OpenAI account is part of an organization under Settings > Organization.
No cost data appears after sync
- Check for recent usage: If there has been no API usage in the sync window, there will be no cost data to display.
- Verify key permissions: If the key was created with incorrect permissions, cost data requests may return empty. Create a new key with Read only access.
- Try Force Sync: Click the refresh icon on your integration card to trigger a manual sync.
Cost data looks incomplete
- OpenAI retains 180 days: The Costs endpoint only returns data for the last ~180 days. Older data is not available through the API.
- Line item granularity: Costs are broken down by model and token type (input, output, cached). If a model shows less detail than expected, this reflects what the Costs API returns.
- Multiple organizations: If you use multiple OpenAI organizations, each one needs its own integration with a separate Admin Key.
Integration shows an error status
- Revoked key: If the Admin API key was deleted or rotated in the OpenAI Console, the integration will fail. Remove the integration and add a new one with the updated key.
- Permission change: If someone changed the key's permissions after creation, it may lose access to the Costs endpoint. Create a fresh key with Read only permissions.