OpenAI Spend Review
Overview
openai_admin_costs is the money view: daily cost buckets, optionally
broken down by project, user, line item, API key, or API source. The ten
usage tools are the volume view behind it (tokens, requests, images,
seconds of audio, storage). A spend review starts from cost, then uses
usage only to explain the lines that matter.
None of these tools are admin-gated in Conduit; a read grant on OpenAI
Admin is enough for everything in this skill.
Anti-triggers
- Seat counts or who has a key: use the
seat-key-inventory skill.
- Billing a client in the PSA: this skill produces the numbers; the
invoice or agreement change happens in the PSA plugin.
Key Concepts
| Tool |
Measures |
Groupable by |
openai_admin_costs |
Cost per day (amount.value in amount.currency, normally USD) |
project_id, user_id, line_item, api_key_id, api_source |
openai_admin_usage_completions |
Input, cached, output, and audio tokens; request counts |
project_id, user_id, api_key_id, model, batch, service_tier, api_source |
openai_admin_usage_embeddings |
Embedding tokens |
project_id, user_id, api_key_id, model |
openai_admin_usage_moderations |
Moderation tokens |
project_id, user_id, api_key_id, model |
openai_admin_usage_images |
Images generated, edited, varied |
project_id, user_id, api_key_id, model, size, source |
openai_admin_usage_audio_speeches |
Text-to-speech characters |
project_id, user_id, api_key_id, model |
openai_admin_usage_audio_transcriptions |
Seconds of audio transcribed |
project_id, user_id, api_key_id, model |
openai_admin_usage_vector_stores |
Vector store bytes |
project_id |
openai_admin_usage_code_interpreter_sessions |
Code interpreter sessions |
project_id |
openai_admin_usage_file_search_calls |
File search calls |
project_id, user_id, api_key_id, vector_store_id |
openai_admin_usage_web_search_calls |
Web search calls |
project_id, user_id, api_key_id, model, context_level, api_source |
All times are UTC Unix seconds; start_time is required and end_time
is exclusive. Cost is daily only.
Common Workflows
Monthly spend by client project
- Compute the month's UTC boundaries as Unix seconds.
openai_admin_costs with start_time, end_time, limit: 31,
group_by: ["project_id"]. Follow next_page while has_more.
- Sum
amount.value per project_id across the daily buckets.
openai_admin_projects_list (with include_archived: true, since
spend can land on a project archived mid-month) to turn project IDs
into names.
- Repeat steps 2-3 for the previous month and show both, with the
change in currency and percent.
Report rows that come back with no project_id as "unattributed"
rather than dropping them; they are still the client's money.
Explain a spike
openai_admin_costs with group_by: ["project_id", "line_item"] over
the spike window plus the same length before it. The line item names
the model and direction (for example input vs output) that moved.
- For the project and model that moved,
openai_admin_usage_completions
with bucket_width: "1h", project_ids: [...], and
group_by: ["api_key_id", "model"] to find the key and the hour it
started.
- If the key is unexpected, hand off to the
security-review skill to see who created
it and whether it belongs to a removed user.
Use "1h" buckets for a few days at most (168 per page); use "1d" for
anything longer.
Per-person usage for a client that pays per user
openai_admin_usage_completions with group_by: ["user_id"] over the
month, then openai_admin_users_list to map IDs to emails. Usage made
through a service account's key has no user; group by api_key_id as
well to see it.
429s and rate-limit headroom
openai_admin_project_rate_limits_list for the client's project returns
the per-model request, token, and image limits. Compare them with the
peak hour from openai_admin_usage_completions (bucket_width: "1h",
group_by: ["model"]). Raising a limit or the organization's usage tier
is done in the OpenAI dashboard, not here.
Gotchas
- Ungrouped rows cannot be attributed.
project_id, user_id, and
api_key_id are null unless they are in group_by. Always group when
the answer has to name a client.
limit counts buckets. A 31-day month needs limit: 31 on daily
buckets, or two pages at the default of 7 is not "the month".
- Grouped long ranges get truncated. If the output says
truncated: true, repeat with a smaller limit; do not page on from
next_page.
- Costs are the operational view. Late-arriving usage and credits can
move a day's number after the fact. For an invoice dispute, the
invoice in the client's OpenAI billing settings is authoritative; say
which one you quoted.
- Batch and flex pricing differ. Group completions by
batch or
service_tier before comparing token volume to cost between months.
Related Skills
1---2name: openai-admin-spend-review3description: >4 Turning the OpenAI Admin usage and cost reports into a per-client spend5 review: daily cost by project, line item, user, or API key; token and6 request volume behind that cost; month-over-month comparison; spike7 attribution; and project rate-limit headroom when a client reports 429s.8when_to_use: >-9 When reviewing what a client's OpenAI organization costs, attributing10 spend to client projects or people for chargeback, explaining a cost11 spike, or preparing AI spend for a QBR. Use when: openai spend, openai12 cost, openai bill, openai usage by project, openai chargeback, token13 usage, gpt cost, openai qbr, openai spike, or openai rate limit14 headroom.15metadata:16 source: https://skillmd.com/skills/wyre-ai/openai-admin-spend-review17---1819# OpenAI Spend Review2021## Overview2223`openai_admin_costs` is the money view: daily cost buckets, optionally24broken down by project, user, line item, API key, or API source. The ten25usage tools are the volume view behind it (tokens, requests, images,26seconds of audio, storage). A spend review starts from cost, then uses27usage only to explain the lines that matter.2829None of these tools are admin-gated in Conduit; a `read` grant on OpenAI30Admin is enough for everything in this skill.3132## Anti-triggers3334- **Seat counts or who has a key**: use the35 [seat-key-inventory](../seat-key-inventory/SKILL.md) skill.36- **Billing a client in the PSA**: this skill produces the numbers; the37 invoice or agreement change happens in the PSA plugin.3839## Key Concepts4041| Tool | Measures | Groupable by |42|------|----------|--------------|43| `openai_admin_costs` | Cost per day (`amount.value` in `amount.currency`, normally USD) | project_id, user_id, line_item, api_key_id, api_source |44| `openai_admin_usage_completions` | Input, cached, output, and audio tokens; request counts | project_id, user_id, api_key_id, model, batch, service_tier, api_source |45| `openai_admin_usage_embeddings` | Embedding tokens | project_id, user_id, api_key_id, model |46| `openai_admin_usage_moderations` | Moderation tokens | project_id, user_id, api_key_id, model |47| `openai_admin_usage_images` | Images generated, edited, varied | project_id, user_id, api_key_id, model, size, source |48| `openai_admin_usage_audio_speeches` | Text-to-speech characters | project_id, user_id, api_key_id, model |49| `openai_admin_usage_audio_transcriptions` | Seconds of audio transcribed | project_id, user_id, api_key_id, model |50| `openai_admin_usage_vector_stores` | Vector store bytes | project_id |51| `openai_admin_usage_code_interpreter_sessions` | Code interpreter sessions | project_id |52| `openai_admin_usage_file_search_calls` | File search calls | project_id, user_id, api_key_id, vector_store_id |53| `openai_admin_usage_web_search_calls` | Web search calls | project_id, user_id, api_key_id, model, context_level, api_source |5455All times are UTC Unix seconds; `start_time` is required and `end_time`56is exclusive. Cost is daily only.5758## Common Workflows5960### Monthly spend by client project61621. Compute the month's UTC boundaries as Unix seconds.632. `openai_admin_costs` with `start_time`, `end_time`, `limit: 31`,64 `group_by: ["project_id"]`. Follow `next_page` while `has_more`.653. Sum `amount.value` per `project_id` across the daily buckets.664. `openai_admin_projects_list` (with `include_archived: true`, since67 spend can land on a project archived mid-month) to turn project IDs68 into names.695. Repeat steps 2-3 for the previous month and show both, with the70 change in currency and percent.7172Report rows that come back with no `project_id` as "unattributed"73rather than dropping them; they are still the client's money.7475### Explain a spike76771. `openai_admin_costs` with `group_by: ["project_id", "line_item"]` over78 the spike window plus the same length before it. The line item names79 the model and direction (for example input vs output) that moved.802. For the project and model that moved, `openai_admin_usage_completions`81 with `bucket_width: "1h"`, `project_ids: [...]`, and82 `group_by: ["api_key_id", "model"]` to find the key and the hour it83 started.843. If the key is unexpected, hand off to the85 [security-review](../security-review/SKILL.md) skill to see who created86 it and whether it belongs to a removed user.8788Use `"1h"` buckets for a few days at most (168 per page); use `"1d"` for89anything longer.9091### Per-person usage for a client that pays per user9293`openai_admin_usage_completions` with `group_by: ["user_id"]` over the94month, then `openai_admin_users_list` to map IDs to emails. Usage made95through a service account's key has no user; group by `api_key_id` as96well to see it.9798### 429s and rate-limit headroom99100`openai_admin_project_rate_limits_list` for the client's project returns101the per-model request, token, and image limits. Compare them with the102peak hour from `openai_admin_usage_completions` (`bucket_width: "1h"`,103`group_by: ["model"]`). Raising a limit or the organization's usage tier104is done in the OpenAI dashboard, not here.105106## Gotchas107108- **Ungrouped rows cannot be attributed.** `project_id`, `user_id`, and109 `api_key_id` are null unless they are in `group_by`. Always group when110 the answer has to name a client.111- **`limit` counts buckets.** A 31-day month needs `limit: 31` on daily112 buckets, or two pages at the default of 7 is not "the month".113- **Grouped long ranges get truncated.** If the output says114 `truncated: true`, repeat with a smaller `limit`; do not page on from115 `next_page`.116- **Costs are the operational view.** Late-arriving usage and credits can117 move a day's number after the fact. For an invoice dispute, the118 invoice in the client's OpenAI billing settings is authoritative; say119 which one you quoted.120- **Batch and flex pricing differ.** Group completions by `batch` or121 `service_tier` before comparing token volume to cost between months.122123## Related Skills124125- [api-patterns](../api-patterns/SKILL.md) - page tokens, bucket caps, errors126- [seat-key-inventory](../seat-key-inventory/SKILL.md) - map user and key IDs to people and owners