OpenAI API Usage API and Dashboard Guide

Usage vs Billing vs Credits

OpenAI separates usage monitoring, billing administration and credit management into three distinct areas:

• Usage — tokens, requests, images, audio and other consumption quantities; tracked via the Usage Dashboard and Usage APIs
• Billing — payment arrangements, invoices, Tax ID, project budgets and payment methods; see the OpenAI API Billing guide
• Credits — prepaid credit balance, purchases, auto recharge and expiry; see the OpenAI API Credits guide

Who Can View Usage

The Usage Dashboard and organization Usage APIs are part of the Administration API. Only Organization Owners or users explicitly granted Usage Dashboard permission can access them.

If the dashboard is not visible, check:

• The correct organization is selected in the top-right selector
• The account role is Organization Owner or has Usage Dashboard permission
• The project filter within the Usage page itself is not restricting the view
• The browser is logged into the correct account

Ordinary project members and API key holders do not automatically have access. Use the AI API Cost Benchmark to turn usage assumptions into an estimated monthly budget.

Dashboard Time Zone and Filters

The Usage Dashboard uses UTC for all time ranges. Always confirm the UTC range when reconciling against local logs, invoices or support requests.

• The date-range selector applies to the currently selected project and filter set
• The project selector within the Usage page is independent of the top-right organization selector — clearing it shows organization-level aggregates
• The dashboard does not automatically consolidate usage across multiple organizations

Activity Data vs Cost Data

The Usage Dashboard provides two distinct export types:

• Activity export — granular usage data filterable by project, user, API key, model, batch and service tier; suited for investigating usage patterns and debugging cost anomalies
• Cost export — spend data grouped by line item; the preferred source for monthly spend reporting, invoice reconciliation and financial totals

For financial purposes, use the Costs endpoint or Cost tab. Token counts alone do not equal the final billed amount.

OpenAI Organization Usage and Costs Endpoints

OpenAI provides a set of organization-level administration endpoints for programmatic usage and cost retrieval. All require an Admin API key. The following endpoints are selected examples; additional endpoints may exist — check the current OpenAI API reference for the full list.

Check the current OpenAI API reference to confirm which endpoints are available, as the surface may expand over time.

Admin API Key and Authorization

Organization Usage and Costs endpoints require an Admin API key — distinct from application API keys used for model inference.

• Admin API keys cannot be used for model inference endpoints
• Application API keys do not grant access to administration endpoints
• Admin keys must be stored in environment variables, never in source code, browser code or support tickets
• Never paste admin keys into screenshots shared with support

cURL example

curl "https://api.openai.com/v1/organization/costs?start_time=<unix-seconds>&end_time=<unix-seconds>" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY"

JavaScript example (Node.js / backend only)

const https = require('https');

async function getOrgCosts(startTime, endTime) {
  const adminKey = process.env.OPENAI_ADMIN_KEY;
  if (!adminKey) throw new Error('OPENAI_ADMIN_KEY environment variable is not set');

  const params = new URLSearchParams({ start_time: startTime, end_time: endTime });
  const options = {
    hostname: 'api.openai.com',
    path: `/v1/organization/costs?${params}`,
    method: 'GET',
    headers: { 'Authorization': `Bearer ${adminKey}` }
  };

  return new Promise((resolve, reject) => {
    const req = https.request(options, (res) => {
      let data = '';
      res.on('data', (chunk) => { data += chunk; });
      res.on('end', () => {
        if (res.statusCode >= 400) {
          console.error('API error:', res.statusCode, data);
          // Inspect error body for error.type and error.code
          return reject(new Error(`HTTP ${res.statusCode}: ${data}`));
        }
        resolve(JSON.parse(data));
      });
    });
    req.on('error', reject);
    req.end();
  });
}

This code runs in a Node.js backend environment. Do not place Admin API keys in browser-facing code.

Parameters

Pagination

// Fetch all pages of usage data
let page = null;
let allData = [];

do {
  const params = new URLSearchParams({
    start_time: String(startTime),
    end_time: String(endTime)
  });
  if (page) {
    params.set('page', page);
  }

  const response = await getOrgUsage(params);
  allData = allData.concat(response.data ?? []);
  page = response.next_page ?? null;
} while (page);

Usage API vs Costs API

Exporting Cost Data from the Dashboard

Steps to download a Cost CSV from the Usage Dashboard:

1. Navigate to the Usage Dashboard in the API Platform
2. Select the target organization and project (or leave blank for organization-level data)
3. Choose the calendar-month or custom UTC date range
4. Switch to the Cost tab
5. Download the CSV and note the export timestamp

The Cost export provides aggregated spend grouped by line item. For partial-month data, export month-to-date and compare carefully with the full-month export when it becomes available.

Troubleshooting

401 or 403 on administration endpoints

Verify the key is an Admin API key, not a project API key. Check that the Authorization: Bearer header is correctly formatted. Admin keys are distinct from keys used for model inference.

Empty results or zero totals

Confirm the UTC date range covers the period with actual usage. Verify the correct organization is selected. Check whether the project filter within the Usage page is narrowing the results. Ensure the Admin key has access to the target organization.

Data mismatch between local logs and API response

Common causes: incomplete pagination (missing next_page results), UTC boundary mismatch at month ends, project filter set differently in dashboard vs API, automatic retries adding usage not in application logs, or cached-token pricing differences.

Why Usage Does Not Equal Final Cost

Token usage and billed cost are related but not identical. Common discrepancies:

• Cached tokens — context caching results in lower effective cost than raw token counts suggest
• Reasoning tokens — some models bill reasoning tokens as output tokens even if not visible in response text
• Batch vs standard pricing — batch-mode usage has different rates
• UTC boundary mismatch — local logs and the dashboard may use different UTC ranges
• Incomplete pagination — next_page tokens not followed result in partial totals
• Automatic retries — retries may generate additional usage not in application logs

Usage Reconciliation Checklist

• ✓Confirm correct organization and Usage Dashboard permission
• ✓Clear or select the intended project filter within the Usage page
• ✓Normalize time range to UTC — confirm both dashboard and API use the same UTC boundaries
• ✓Use inclusive start_time and exclusive end_time for API queries
• ✓Export Activity data for usage investigation
• ✓Export Cost data for spend reconciliation
• ✓Follow all next_page cursors and pass them as the page query parameter
• ✓Use Costs endpoint for financial totals, not token estimates
• ✓Compare with the API Billing Mismatch guide when totals still differ

Security Checklist

• ✓Store Admin API keys in environment variables, never in source code
• ✓Never paste API keys into browser tools, chat interfaces or support tickets
• ✓Redact keys from screenshots before sharing evidence with support
• ✓Rotate Admin API keys regularly and immediately upon suspected exposure
• ✓Apply least privilege — grant Usage Dashboard access only to users who need it
• ✓Save request_id, timestamp, model, project, input/output usage and retry count for every request

Official Sources Reviewed

Information on this page is based on OpenAI official documentation reviewed as of June 25, 2026. OpenAI API usage features may change; verify current behavior in the API Platform and API reference.

• OpenAI Help: Understanding your API usage
• OpenAI Help: How do I export monthly usage details from the API Usage Dashboard
• OpenAI API Reference: Organization Usage — Costs endpoint
• OpenAI API Reference: Administration overview
• OpenAI API Docs: Pricing

Related Guides

Frequently Asked Questions