OpenAI Team Usage API: Pulling Token Data for Engineering

Engineering teams rarely have “one OpenAI bill.” They have org-level API usage, project keys for CI, ChatGPT Team seats, and IDE tools (Cursor, Copilot) that call OpenAI models without touching your admin console. The OpenAI Organization Usage and Costs APIs are how platform teams pull authoritative token and dollar data — if you use the right key type and parse responses correctly.

This guide covers admin keys, the endpoints ForgeMeter syncs against, and the mistakes we see when teams first wire OpenAI into an AI spend dashboard.

Admin keys vs project keys

Key type	Prefix (typical)	Can read org billing?
Admin API key	sk-admin-...	Yes
Project key	sk-proj-...	No — project scope only
User / legacy key	sk-...	No

Create admin keys at platform.openai.com → Settings → Organization → Admin keys.

If ForgeMeter or your script returns 401/403, the fix is almost always: wrong key type, not a broken integration.

Important: Admin keys are for administration and usage reporting — they are not drop-in replacements for application inference keys.

The two endpoints you need

OpenAI splits cost and usage (OpenAI cookbook: Completions Usage API).

Organization costs

GET https://api.openai.com/v1/organization/costs
  ?start_time={unix}
  &end_time={unix}
  &bucket_width=1d
  &group_by=line_item

Returns daily buckets with amount.value in USD. Values may arrive as strings — always coerce with Number() before summing in code or spreadsheets.

Completions usage

GET https://api.openai.com/v1/organization/usage/completions
  ?start_time={unix}
  &end_time={unix}
  &bucket_width=1d
  &group_by=model

Returns input/output tokens and request counts grouped by model.

Pagination

Both endpoints paginate with has_more and next_page. The cursor is passed as the page query parameter, not as a full URL. Missing pagination under-reports spend on active orgs.

Step-by-step: first sync

1. Choose a time window

For a weekly leadership review, pull 7–30 days aligned to UTC midnight boundaries. OpenAI expects start_time / end_time as Unix seconds.

2. Fetch costs and usage

# Illustrative — use your admin key from secrets manager
curl "https://api.openai.com/v1/organization/costs?start_time=START&end_time=END&bucket_width=1d" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY"

Repeat for /organization/usage/completions with group_by=model.

3. Normalize to daily rows

date	model	tokens	cost_usd
2026-07-01	gpt-4o	1_240_000	18.42
2026-07-01	gpt-4o-mini	8_100_000	4.11

Org-level sync won’t attribute rows to individual developers unless you also partition by project_id or issue per-team project keys.

4. Join with IDE tool spend

OpenAI API totals are only part of the story. Cursor and Copilot may consume OpenAI-backed models through their billing — see Cursor Enterprise analytics setup and Copilot metrics API.

What engineering leaders should track

1. Daily burn rate — $ / day trend, not just month-to-date
2. Model mix — share of tokens on premium vs mini models
3. Batch vs interactive — batch endpoints are cheaper for CI/eval (if separated in reporting)
4. Project or team allocation — chargeback prep for finance
5. Spike detection — 2× average daily cost triggers review

ForgeMeter’s sync pipeline writes UsageEvent rows and raises spend spike alerts when a single day exceeds recent averages.

Common pitfalls (we’ve hit these in production)

String cost values

Summing amount.value without Number() produces string concatenation bugs — Prisma and Postgres will reject the row. Always parse floats explicitly.

Wrong key in “org admin” field

Developers paste project keys into team tools. Validate on connect by calling /organization/costs for the last 7 days.

Expecting per-developer email in org API

Org-level admin keys aggregate. For attribution you need:

• Per-project API keys mapped to teams, or
• IDE tools (Cursor/Copilot) that expose per-user analytics, or
• CLI wrappers (e.g. Scruple, Lineman) that bind sessions to git context

Ignoring zero-token cost days

Cost buckets can exist with low token counts (cached pricing, line items). Don’t drop zero-token days when building budget charts.

Syncing once, never again

OpenAI usage shifts daily. Schedule daily sync (ForgeMeter cron at 06:00 UTC) or weekly minimum for leadership reviews.

OpenAI-only stack: what dashboards can’t show

If OpenAI is your only connected provider, you can report:

• Org token and dollar trends
• Model distribution (when completions usage succeeds)

You cannot honestly report:

• Active developers (unless project keys per person — rare)
• Copilot/Cursor overlap
• Per-repo attribution

ForgeMeter’s Optimize playbook will recommend connecting IDE tools when it detects OpenAI-only workspaces.

Security & compliance talking points

• Admin keys live in secrets manager, rotated quarterly
• Read-only usage scope — no prompt content in these endpoints
• Align with API key rotation policy for team keys vs admin keys
• Finance export: daily CSV from synced warehouse or ForgeMeter report email

When to add ForgeMeter vs build

Build yourself	Use ForgeMeter
One-off finance export	Ongoing dashboards + alerts
Only OpenAI, no IDE tools	Cursor + Copilot + OpenAI unified
Internal data team owns ETL	Want audit trail + Optimize playbook

How ForgeMeter helps

Connect your sk-admin-... key on the Integrations page. ForgeMeter validates against the live Costs API, syncs daily usage, and shows spend on the Overview dashboard alongside other providers.

Start free · Free executive audit · Live demo

See also: Best AI engineering analytics tools in 2026 · Multi-provider AI billing (coming 2027)