Skip to main content
← back to extensions

Openai Usage

@dougschaefer/openai-usagev2026.10.07.2· 19d agoBEHAVIORS
01README

OpenAI platform usage and cost reporting via the Organization Usage API — daily and total completion token counts, embeddings/moderations/images/audio usage, and USD spend, month-to-date by default, optionally grouped and filtered by project, model, API key, or cost line item. Vault-based Admin API key (the api.usage.read scope is required; a standard project key cannot read usage).

02Release Notes

Adds group_by and project/model filters to usage and costs, and usageByType for the embeddings, images, audio speeches/transcriptions and moderations buckets. Results are never silently truncated: a pull that would exceed 100 pages, or a missing pagination cursor, fails loudly; periods are capped at 2,900 days with real-date validation. Retries one 429 honouring Retry-After.

03Behaviors1
@dougschaefer/openai-usagev2026.10.07.2openai-usage/usage.ts

Global Arguments

ArgumentTypeDescription
apiKeystringOpenAI Admin API key (sk-admin-...) carrying the api.usage.read scope. Store it in a vault and pass via a CEL expression; a standard project key cannot read usage.
fn usage()
Fetch OpenAI completion token usage (input/output tokens and request counts) by day for the period, optionally grouped by project, model, or API key and filtered to projects or models. Defaults to month-to-date. Requires an Admin key with the api.usage.read scope.
fn usageByType()
Fetch OpenAI usage for one non-completions endpoint (embeddings, moderations, images, audio_speeches, audio_transcriptions) by day for the period, as a quantity in that type's unit (input tokens, images, characters, or seconds) plus request counts. Optionally grouped by project, model, or API key and filtered to projects or models. Defaults to month-to-date. Requires an Admin key with the api.usage.read scope.
fn costs()
Fetch OpenAI spend in USD by day for the period, optionally grouped by line item or project and filtered to projects. Defaults to month-to-date. Requires an Admin key with the api.usage.read scope.

Resources

usage(infinite)— Completion token usage totals and daily breakdown
usageByType(infinite)— Embeddings, moderations, images, or audio usage totals and daily breakdown, one instance per type
costs(infinite)— Spend totals and daily breakdown in USD
04Previous Versions3
2026.06.29.1

Mark the Admin API key field sensitive (.meta sensitive:true) so it is masked in logs/output.

Added 1, removed 1 behaviors

2026.06.08.1
2026.05.27.1

Initial release. Query the OpenAI Organization Usage and Cost API for month-to-date completion token usage and USD spend, with daily breakdowns; vault-based Admin key (api.usage.read scope). Fills a gap no community extension covers: the OpenAI platform usage API (not Azure/Bedrock/Vertex).

05Stats
A
93 / 100
Downloads
27
Archive size
14.0 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License1/2partial

    no SPDX license declared

  • Verified public repository2/2earned
Repository
https://github.com/dougschaefer6/swamp-openai-usage
06Platforms
07Labels
#openai#usage#cost#tokens#finops#monitoring