How to get your OpenAI API usage, balance and spend programmatically

What the OpenAI API exposes

Call it yourself

Credential. An Admin key (sk-admin-…), created by an org owner under Organization settings → Admin keys. Normal project keys can't read organization endpoints, and Argus rejects them at connect time.

curl "https://api.openai.com/v1/organization/costs?start_time=1760054400&bucket_width=1d&limit=7&group_by=project_id" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY"

{
  "data": [
    {
      "start_time": 1760054400,
      "end_time": 1760140800,
      "results": [
        { "amount": { "value": 12.84, "currency": "usd" }, "project_id": "proj_abc123" }
      ]
    }
  ],
  "has_more": false,
  "next_page": null
}

Gotchas

• bucket_width only accepts 1d on the Costs API, and limit tops out at 180 buckets. Page with next_page while has_more is true.
• end_time is exclusive.
• amount.value is dollars as a float, not cents.
• Plan and hard limit aren't in the admin API. The old /dashboard/billing/subscription endpoint only answers to a dashboard session, is undocumented, and may be retired.
• Running out of credits returns 429 insufficient_quota, the same status as a rate limit. Check the error code, not just the status.
• Rate-limit headroom is only in response headers (x-ratelimit-remaining-requests, x-ratelimit-remaining-tokens), so you see it only if you capture responses.

How OpenAI charges

Per-token, prepaid credits by default (invoiced for larger orgs). Rate limits and monthly caps rise through spend-qualified usage tiers 1–5.

• Tier 1: $100/mo cap; 500 RPM / 500K TPM (sol)
• Tier 3: $1,000/mo cap; 5,000 RPM / 2M TPM
• Tier 5: $200,000/mo cap; 15,000 RPM / 40M TPM

At zero. 429 insufficient_quota at zero balance or spent monthly cap; no negative balance.

• requests per minute, per org. Per-model × per-tier RPM/TPM; see usage tiers.

Or let Argus track it

Paste the key once. Argus keeps the ledger, and your coding agent reads it through the MCP server.

• Pulls OpenAI's daily cost buckets every hour for month-to-date spend and a projected month-end total, broken down by project.
• Tracks the plan: the allowance, what's used this period, the reset date, and when you cross into overage.
• With the SDK, records token counts on each response and prices them per model, so you see what a call cost before the provider's daily bucket lands.
• Emails you on low balance, days to zero, a spend spike, or projected overage.
• Hands all of it to your coding agent over MCP, so it can ask what a run cost or how much runway is left without leaving the editor.

> what has openai cost today, and how long until it runs out?

get_overview       → openai: mtd spend, burn per day, days to zero
get_request_costs  { "provider": "openai", "limit": 25 }
get_advisories     → credits_low, spend_spike, rate_limit_low …

Questions

Does OpenAI have an API for its balance?

OpenAI has no API for your prepaid credit balance. Spend comes from the Costs API, GET /v1/organization/costs, which takes an Admin key and returns USD in 1-day buckets, optionally grouped by project.

Can I get OpenAI spend per day from the API?

Yes, from GET /v1/organization/usage/completions, GET /v1/organization/costs (admin key), in daily buckets.

What happens when OpenAI credits run out?

429 insufficient_quota at zero balance or spent monthly cap; no negative balance. Auto-recharge is available.

What key does Argus need for OpenAI?

An Admin key (sk-admin-…), created by an org owner under Organization settings → Admin keys. Normal project keys can't read organization endpoints, and Argus rejects them at connect time.

Related

AnthropicDeepSeekGoogle GeminiOpenRouterPerplexity