OpenAI Integration

Customer Onboarding Guide — OpenAI Organization Costs API

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

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.

1

Create an Admin API Key

1. Sign in to platform.openai.com as an organization Owner

2. Navigate to Settings → Organization → Admin API keys (direct link)

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

2

Find Your Organization ID

1. In platform.openai.com, go to Settings → Organization → General

2. Copy your Organization ID (starts with org-)

3

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.

4

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:

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"

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

• Administration API Reference

• Costs API Reference

• Assign API Key Permissions

• OpenAI Pricing

OneLens Support: [e-mail]