> For the complete documentation index, see [llms.txt](https://docs.onelens.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onelens.cloud/integrations/ai-integrations/openai-integration.md).
# OpenAI Integration
## TL;DR
* **What this does:** Connects OneLens to your OpenAI organization to pull per-user, per-model cost and usage data — giving you unified cost visibility, anomaly detection, and optimization insights across all OpenAI models (GPT-4o, GPT-4, GPT-3.5, o1, DALL·E, Whisper, Embeddings, etc.).
* **Time required:** \~5 minutes
* **Who you need:** An OpenAI organization **Owner** (to create an Admin API key).
* **What OneLens reads:** Read-only cost metadata from the OpenAI Organization Costs API (`/v1/organization/costs`), grouped by user. Your prompts, completions, and production data are never accessed.
## What You'll Get Once Connected
| Capability | What it does for you |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Per-User Cost Attribution | See exactly what each user in your OpenAI organization spends, broken down by model. |
| Per-Model Cost Breakdown | Compare spend across GPT-4o, GPT-4, o1, GPT-3.5, DALL·E, Whisper, Embeddings, and other models. |
| Usage Type Breakdown | Separate costs by usage type — input tokens, output tokens, cached tokens, image generation, audio minutes, etc. |
| Cost Anomaly Detection | Get alerted when OpenAI spend deviates from historical patterns — catch unexpected usage spikes early. |
| Budget Tracking | Set and monitor budgets at the organization or user level with OneLens alerts. |
| Multi-Provider Visibility | View OpenAI costs alongside Anthropic, AWS Bedrock, LiteLLM, and other providers in a single dashboard. |
## Security at a Glance
| Question | Answer |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Does OneLens read our prompts or completions? | No. The `/v1/organization/costs` endpoint returns only aggregated cost amounts, model identifiers, and usage types. No prompt or completion content is included. |
| Does OneLens access our OpenAI projects or users? | No. OneLens does not call any user management, project management, or audit log endpoints. |
| Is the access read-only? | Yes. OneLens only calls `GET /v1/organization/costs`. It cannot invoke models, manage users, create keys, or modify any organization resources. |
| What authentication is used? | An OpenAI Admin API key, created by an organization Owner at platform.openai.com. The key is passed as a Bearer token in the Authorization header. |
| Does OneLens see user identifiers? | Yes — the API returns `user_id` values from the `group_by=user_id` parameter. These are internal OpenAI user IDs used for per-user cost attribution. |
| How is data transmitted and stored? | All API calls use HTTPS/TLS 1.2+. Credentials are encrypted at rest using GCP KMS in OneLens infrastructure. |
## Cost of the Integration
OneLens reads cost metadata via the OpenAI Organization Costs API. There is no additional charge from OpenAI for API cost queries.
| Item | What it is | Typical cost |
| ----------------------- | --------------------------------------------------------- | -------------------------------- |
| API calls | Daily polling of `/v1/organization/costs` with pagination | $0 (no per-request charge) |
| Data egress | JSON cost metadata responses | $0 |
| Compute in your account | None — OneLens calls OpenAI's hosted API | $0 |
| **Estimated total** | | **$0/month on your OpenAI bill** |
## How It Works
The OpenAI Organization Costs API provides programmatic access to cost data across your entire OpenAI organization. OneLens calls a single endpoint:
**GET /v1/organization/costs** — returns cost data grouped by user, with each record containing the model name, usage type (e.g., input tokens, output tokens, cached tokens, image generation), cost amount, and currency. OneLens queries day-by-day with `group_by=user_id` to build per-user, per-model cost attribution.
OneLens polls the Costs API daily. Each poll iterates over the date range day-by-day, handling pagination automatically (up to 180 records per page). All data is normalized into a unified cost model alongside your other AI providers.
> For financial reconciliation, the Costs endpoint is the recommended source — it reconciles back to your OpenAI billing invoice, unlike the Usage API which provides more granular but potentially less reconciled data.
## Prerequisites
* An OpenAI organization with API usage
* A user with the **Owner** role in the organization
* Access to [platform.openai.com](https://platform.openai.com/)
## What OneLens Will Access
| Endpoint | Purpose |
| -------------------------- | ------------------------------------------------------- |
| GET /v1/organization/costs | Per-user, per-model cost data with usage type breakdown |
**Parameters used:**
| Parameter | Value | Purpose |
| ----------- | -------------- | ------------------------- |
| start\_time | Unix timestamp | Start of the query window |
| end\_time | Unix timestamp | End of the query window |
| group\_by | user\_id | Per-user cost attribution |
| limit | 180 | Pagination page size |
| page | cursor token | Pagination |
## What OneLens Will NOT Access
* `/v1/chat/completions`, `/v1/responses`, `/v1/embeddings` — OneLens cannot invoke any model
* `/v1/organization/users`, `/v1/organization/invites` — OneLens cannot manage users or send invitations
* `/v1/organization/projects` — OneLens cannot create or modify projects
* `/v1/organization/admin_api_keys` — OneLens cannot create or manage API keys
* `/v1/organization/audit_logs` — OneLens does not access audit logs
* `/v1/fine_tuning`, `/v1/files`, `/v1/images` — OneLens cannot access fine-tuning, file uploads, or image generation endpoints
* Any prompt, completion, or request/response content
> **Note:** Admin API keys cannot be used for non-administration endpoints. The key OneLens uses literally cannot invoke models even if misconfigured.
{% stepper %}
{% step %}
## Create an Admin API Key
1. Sign in to [platform.openai.com](https://platform.openai.com/) as an organization **Owner**
2. Navigate to **Settings → Organization → Admin API keys** ([direct link](https://platform.openai.com/settings/organization/admin-keys))
3. Click **Create admin key**
4. Name it **OneLens Integration**
5. Copy the key — store it securely
> **Secure key sharing:** Never share API keys over email or chat. Use a validated secure sharing tool like [Password.link](https://password.link/en) to transmit credentials safely.
> **Important:** Only organization Owners can create Admin API keys. Admin keys can only access administration endpoints — they cannot be used to call models.
> {% endstep %}
{% step %}
## Find Your Organization ID
1. In [platform.openai.com](https://platform.openai.com/), go to **Settings → Organization → General**
2. Copy your **Organization ID** (starts with `org-`)
{% endstep %}
{% step %}
## Connect to OneLens
Provide the following in the OneLens integration setup:
| Field | Value | Example |
| ---------------- | ---------------------------------- | -------------------- |
| Integration Name | A display name for this connection | Acme Corp OpenAI |
| Organization ID | Your OpenAI organization ID | org-xxxxxxxxxxxx |
| API Key | Your Admin API key | sk-admin-xxxx...xxxx |
OneLens will begin ingesting data on the next scheduled poll.
{% endstep %}
{% step %}
## Verify the Connection
After connecting, verify by checking the OneLens dashboard for:
1. OpenAI models appearing in the cost explorer
2. Per-user cost data populating
3. Historical cost data backfilling (up to the available date range)
If data doesn't appear within 24 hours, run this from your terminal to confirm the key works independently:
```bash
curl -X GET "https://api.openai.com/v1/organization/costs?start_time=1717200000&end_time=1717286400&group_by=user_id&limit=10" \
-H "Authorization: Bearer YOUR_OPENAI_ADMIN_KEY_HERE"
```
{% endstep %}
{% endstepper %}
## Data Refresh Schedule
OneLens polls the OpenAI Costs API once daily, iterating day-by-day over the configured date range.
1. The Costs endpoint provides data that reconciles to your billing invoice.
2. Current-day figures may shift as in-progress requests complete.
3. Historical data is backfilled automatically on initial connection.
## Data Privacy & Security
* **Read-only access** — OneLens only calls `GET /v1/organization/costs`; no write or model invocation capability.
* **Admin key isolation** — Admin API keys cannot invoke models by design. The key OneLens uses is structurally limited to administration endpoints.
* **No prompt/completion content** — the Costs endpoint returns only aggregated cost amounts, model names, and usage types.
* **TLS in transit** — all API calls use HTTPS/TLS 1.2+.
* **Encrypted at rest** — credentials and ingested data are encrypted at rest using GCP KMS in OneLens.
* **Data retention** — 12-month default, configurable. Deletion within 30 days on request with confirmation.
## Frequently Asked Questions
Can OneLens see our prompts or completions?
No. The Costs endpoint returns only aggregated cost amounts, model names, and usage types (e.g., "input tokens", "output tokens"). No request or response content is included.
Can OneLens invoke models or run up our OpenAI bill?
No. Admin API keys cannot be used for model invocation by design. They are structurally limited to administration endpoints.
Will this impact our API latency or rate limits?
No. OneLens polls once daily using the Costs API, which is separate from the model inference path. It does not affect your production API calls.
Can I connect multiple OpenAI organizations?
Yes. Add each organization separately in OneLens with its own Admin API key and Organization ID.
How do I disconnect OneLens?
Delete the Admin API key at platform.openai.com → Settings → Organization → Admin API keys. All access is immediately revoked.
How do I rotate the API key?
Create a new Admin API key, update it in OneLens, then delete the old key. OneLens uses the new key on the next daily poll — no downtime.
What about OpenAI usage via Azure OpenAI Service?
Azure OpenAI has its own billing managed by Microsoft Azure. This integration covers direct OpenAI API usage only (platform.openai.com). For Azure OpenAI costs, use the Azure Cost Management integration.
Does OneLens see user email addresses?
No. The Costs API returns internal OpenAI `user_id` values, not email addresses. OneLens uses these for per-user cost attribution.
## Need Help?
**OpenAI Documentation:**
* [Admin APIs Guide](https://developers.openai.com/api/docs/guides/admin-apis)
* [Administration API Reference](https://developers.openai.com/api/reference/administration/overview)
* [Costs API Reference](https://platform.openai.com/docs/api-reference/usage/costs_object)
* [Assign API Key Permissions](https://help.openai.com/en/articles/8867743-assign-api-key-permissions)
* [OpenAI Pricing](https://platform.openai.com/docs/pricing)
**OneLens Support:**
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.onelens.cloud/integrations/ai-integrations/openai-integration.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.