Przejdź do treści
Biblioteka skilli
AI i agenci · Analiza

openai-usage

/openai-usage

Mierzy zużycie tokenów modeli OpenAI w zadaniu i szacuje koszt według cennika API, z podziałem na modele i próby.

Repozytorium
jstack ↗
Licencja
MIT
Ostatnia zmiana repozytorium
09.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
12
Skrypty
2
Komentarze HTML
0
Adresy URL w SKILL.md
6
Przestarzałość

Brak sygnałów. Repozytorium zmienione 09.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 2 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: openai_usage.py, tests/test_openai_usage.py

Co robi i kiedy

Mierzy zużycie tokenów modeli OpenAI w zadaniu i szacuje koszt według cennika API, z podziałem na modele i próby.

Oryginalny opis (EN)

Measure token usage of OpenAI models across a delegated goal and estimate its cost at OpenAI's API list price, per model, role, task and attempt, with explicit coverage of what is measured, estimated or unknown. Use when the operator asks what a goal cost in OpenAI tokens, when a mandate sets a cost limit on OpenAI runs, or when reporting usage of Codex CLI sessions or OpenAI API calls. OpenAI models only; it does not cover other providers.

Jak działa

  1. What can be observed where
  2. What the tool computes
  3. What you do
  4. Limits
  5. Tests
Sekcje z nagłówków SKILL.md, w oryginale · 223 linii, 2 001 słów
Podgląd SKILL.md
---
name: openai-usage
description: Measure token usage of OpenAI models across a delegated goal and estimate its cost at OpenAI's API list price, per model, role, task and attempt, with explicit coverage of what is measured, estimated or unknown. Use when the operator asks what a goal cost in OpenAI tokens, when a mandate sets a cost limit on OpenAI runs, or when reporting usage of Codex CLI sessions or OpenAI API calls. OpenAI models only; it does not cover other providers.
license: MIT
---

# OpenAI Usage

After a delegated goal, show what the OpenAI models consumed and what that
would cost at OpenAI's API list price: per actual model, per role, task and
attempt where the attribution is safe, and for the whole goal including
failed attempts, reviews and the orchestrator's own runs. Every number
says whether it was measured, estimated or is unknown.

This skill covers **OpenAI models only**. Runs on other providers appear
in the report only as "not measured".

It has two parts. Keep them apart when you report:

- **Implemented and tested**: `openai_usage.py`, a Python 3.9+ standard-library
  tool, the pinned price table in `prices/`, and the tests in `tests/`.
- **Instructions to the agent**: everything under "What you do" below.
  Nothing enforces them; they are rules you follow.

## What can be observed where

Checked on 2026-11-06 against the OpenAI documentation and Codex CLI
0.165.0 session logs. Field names are exact.

| Source | Per-call usage fields | Model | Service tier | Gaps |
|---|---|---|---|---|
| Responses API response | `usage.input_tokens`, `usage.input_tokens_details.cached_tokens`, `.cache_write_tokens`, `.cache_write_tokens_details.ttl_30m_tokens` / `ttl_12h_tokens`, `usage.output_tokens`, `usage.output_tokens_details.reasoning_tokens` | `model` of the response | `service_tier` of the response (the tier actually used) | `usage` can be null |
| Chat Completions response | `usage.prompt_tokens`, `usage.prompt_tokens_details.cached_tokens`, `.cache_write_tokens`, `usage.completion_tokens`, `usage.completion_tokens_details.reasoning_tokens` | `model` | `service_tier` | 12-hour cache writes don't exist here |
| Agents API session turns | turn `usage` with the Responses fields above, and `subagent_id` (null for the root agent) | as recorded | as recorded | No cache-write count; "best-effort", "can be `null` when unknown, and recorded counts may change" |
| Codex CLI session log `$CODEX_HOME/sessions/**/rollout-*-<thread id>.jsonl` | `token_usage_record` events: `payload.usage.{input_tokens, cached_input_tokens, cache_write_input_tokens, output_tokens, reasoning_output_tokens}` per `response_id`; cumulative `turn_token_usage` and `thread_token_usage` | `turn_context.payload.model`: the model Codex **requested**, not confirmed by a response | `thread_settings_applied.service_tier`: **configured** | `cache_write_input_tokens` was 0 in every one of 8,741 local records although 98% of input was cache reads, so a 0 is not evidence. Older logs have only `token_count` events. Runs with `--ephemeral` write no log |
| `codex exec --json` stdout | `turn.completed.usage` per turn, no model | - | - | Per turn, not per request; not read by the tool |
| Codex cloud tasks, ChatGPT | none found locally | - | - | Not observable with this tool |

How the counts nest (OpenAI Agents API observability guide: "Cached tokens
are included in `input_tokens`, and reasoning tokens are included in
`output_tokens`." and "Reasoning tokens are billed as output tokens."):

```
input  = ordinary input + cached reads + cache writes   (each billed at its own rate)
output = visible output + reasoning                     (one output rate)
```

The local Codex logs agree: `total_tokens == input_tokens + output_tokens` in
all 8,741 records, with cached ≤ input and reasoning ≤ output. The tool never
adds cached to input or reasoning to output.

Billing evidence: a Codex log whose `token_count` events carry
`rate_limits.plan_type` comes from a ChatGPT plan. Those runs are not billed
per token. OpenAI's Codex pricing page says: "API token prices are separate
from subscription usage; don't use them to estimate included tasks." For
them the USD figure is a hypothetical, labelled so. Direct API calls are
billed per token, but the tool's figure is still an estimate; only the
organization's billing records show the charge.

Sources: https://developers.openai.com/api/docs/guides/agents-api/observability,
https://developers.openai.com/api/docs/guides/prompt-caching,
https://developers.openai.com/api/docs/pricing,
https://developers.openai.com/codex/pricing,
https://developers.openai.com/codex/noninteractive (all read 2026-11-06).

## What the tool computes

`<skill>` is this skill's folder, for example `~/.claude/skills/openai-usage`:

```bash
python3 <skill>/openai_usage.py \
  --attribution ops/usage-attribution.json \
  --ledger ops/openai-calls.jsonl \
  [--codex-session FILE ...] [--codex-home ~/.codex] \
  [--format markdown|json|records]
```

- **Codex runs** listed in the attribution file are found by thread id
  under `--codex-home` (default `$CODEX_HOME`, else `~/.codex`), together
  with every subagent thread below them (`parent_thread_id`).
- **Deduplication**: one count per `response_id` (Codex) or `call_id`
  (ledger), across all inputs, so a resumed or forked log, a file given
  twice or a call logged twice counts once. Cumulative counters are never
  summed: Codex per-response records are used; older `token_count` logs and
  ledger snapshots marked `cumulative` count the difference from the
  previous snapshot, skip repeats, and flag a counter that goes down.
- **Pricing** per call from the pinned table: the tier's rates, the
  long-context rates when that call's input exceeds 272,000 tokens, the
  cached-input rate, the 30-minute and 12-hour cache-write rates for models
  that bill writes separately (GPT-5.6 and later), and one output rate that
  covers reasoning. All money is `Decimal`.
- **Status per call**, and the worst one for every sum:

| Status | Meaning | Sum shown as |
|---|---|---|
| `exact` | Model and tier from the response, every needed count and rate present | `$X` |
| `estimate` | Priced fully, but the model or tier is requested, configured or assumed, or a snapshot name was priced as its alias, or the promotional price had ended | `~$X` |
| `lower_bound` | A count or split is missing; it is priced at the cheapest rate it could have had (missing cached split at the cached rate, unreported cache writes at the ordinary input rate, unknown write lifetime at the 30-minute rate, unknown request length at the short-context rate, a missing count or listed rate at 0) | `at least $X` |
| `unknown` | No usage, model not in the table, tier not observed, inconsistent counts, or audio and image tokens | `unknown`; never added as 0 |

- **Attribution** comes only from the attribution file. Calls from threads
  it doesn't list are `unattributed`. A subagent thread is attributed to the
  run that spawned it and counted as such. `attempt` above 1 is a retry,
  summed separately as well.
- **Coverage** lists listed runs with no usage ("unknown, not zero"), runs
  marked not measured, session files without usage, input files that are
  missing or unreadable (by file name), duplicates dropped,
  every assumption and gap with its call count, and the charges no amount
  includes: per-call tool fees, container sessions, the 10% regional or
  FedRAMP uplift, and audio or image tokens.
- **Output**: a Markdown summary, the same as JSON, or `records`: one
  metadata-only line per call that the tool reads back as a ledger
  (`"api": "normalized"`), so a goal can be priced again after the session
  logs are gone or with a newer price table.

The tool reads only ids, model names, tiers, timestamps and token counts. It
never prints or stores prompts, messages, paths, code or tool output; a test
plants secrets in message, instruction and path fields and checks that none
reaches any output. It makes no network calls and needs no API key. It exits 0 when
usage or an input file is missing: measurement never blocks the work.

[Example report](reference/example-report.md), from the synthetic fixtures
in `tests/fixtures/example/`: an orchestrator, a failed builder attempt
with one long-context request, its retry with a subagent, a reviewer on
the API with one call whose usage is null and one model the table doesn't
list, a reviewer whose Codex session had no usage, a builder whose session
file is missing, and planning that was never measured.

## What you do

1. **Before the first delegation**, create the attribution file in the ops
   folder (untracked, next to the log). One entry per run, written when
   the run starts:

   ```json
   {
    "goal": "csv-export",
    "runs": [
     {"id": "<codex thread id>", "source": "codex", "role": "builder", "task": "T1", "attempt": 1, "outcome": "failed"},
     {"id": "<codex thread id>", "source": "codex", "role": "builder", "task": "T1", "attempt": 2},
     {"id": "review-t1", "source": "ledger", "role": "reviewer", "task": "T1", "attempt": 1, "billing": "api"},
     {"id": "planning", "source": "none", "role": "orchestrator", "task": "plan", "note": "not run on an OpenAI model"}
    ]
   }
   ```

   The Codex thread id is the `thread_id` of the `thread.started` event
   (`codex exec --json`) or the UUID at the end of the session file name.
   Every retry gets its own entry with the next attempt number. List the
   orchestrator's own OpenAI runs too. Work that is not an OpenAI call,
   or that you can't measure, gets `"source": "none"` and a note; it then
   shows as not measured instead of silently missing.
2. **When your own code calls the OpenAI API**, append one line per
   response to the ledger. Copy `id`, `model`, `service_tier` and the
   `usage` object from the response, nothing else:

   ```json
   {"run": "review-t1", "call_id": "<response id>", "api": "responses", "model": "<response.model>", "service_tier": "<response.service_tier>", "timestamp": "<UTC>", "usage": {"...": "as returned"}}
   ```

   `api` is `responses`, `chat` or `agents_turn` (use the turn id as
   `call_id`). If you only know the model you asked for, write
   `requested_model` instead of `model`. Batch API calls add
   `"batch": true`. Session-level totals go in as `"cumulative": true`
   with a `stream` and `seq`, never as separate calls. Never copy input,
   instructions, output text, tool arguments or headers.
3. **Don't treat a model name in a brief, a config or a routing rule as the
   model that ran.** Only a response's `model` counts as observed; Codex
   logs give the requested model, and the report says so.
4. **Report after the goal** (and at checkpoints if the operator asks):
   run the tool, put the total, the status counts and the coverage gaps in
   the log, and keep the `--format records` output in the ops folder so
   the numbers can be reproduced. Say in words whether the amount is a
   bill or a hypothetical, and name every run that is unknown.
5. **Cost limits.** The tool measures after the calls happened; it can't
   stop a call, and it sees nothing for runs that leave no usage. If the
   operator sets a hard USD limit on OpenAI usage:
   - Say before the first delegation which runs it can measure and which
     it can't, and that a ChatGPT plan's usage is limited by the plan, not
     by USD, so a list-price figure is not what that limit protects.
   - If any run that counts against the limit is unmeasured, or the total
     is `unknown`, the limit is **not monitored**. Say so plainly, propose
     a limit you can enforce (number of runs or attempts, a cheaper
     model, API-only runs with a ledger), and treat the answer as a
     reserved decision. Don't start runs that the limit would cover while
     you wait.
   - When it is monitored, compare the `at least` total with the limit at
     every task boundary, and stop starting new runs before the next run
     could cross it.
   A soft budget or no limit never blocks work: report and continue.
6. **Updating prices.** Never edit a pinned table. Fetch
   `https://developers.openai.com/api/docs/pricing.md`, write a new
   `prices/openai-api-<date>.json` with the same structure, the retrieval
   time and the source's sha256, and add spot-check tests for it. The tool
   uses the newest table by default; pass `--prices` to reproduce an old
   report with the table it used (its sha256 is in every report).

## Limits

- No cache-write counts from Codex or the Agents API. For models that bill
  writes separately, those totals are lower bounds.
- Codex logs carry the requested model and the configured tier, so Codex
  totals are at best estimates.
- Not priced: tool-call fees, container sessions, regional or FedRAMP
  uplift, audio, image and realtime tokens, fine-tuned models, and models
  not on the pinned table. Each appears as a gap, not as 0.
- Usage reported by the Agents API can change after it is first read;
  re-run the report before quoting a final number.
- Codex cloud tasks, ChatGPT and other OpenAI surfaces without local or
  API usage data can't be measured with this tool.

## Tests

```bash
python3 -m unittest discover -s <skill>/tests
```

Synthetic data only. The tests cover cached and reasoning tokens nested in
input and output, the prompt-caching guide's own cost example, cache
writes with and without a lifetime split, Chat Completions and Agents API
shapes, per-response Codex records, resumed and repeated logs,
`token_count` deltas and resumed `token_count` files, cumulative ledger
streams and counter resets, missing usage and missing input files, splits and tiers, unknown models and snapshot names,
long-context rates, promotional end dates, requested versus observed
models, retries, subagents and unattributed calls, billing labels,
privacy, determinism, re-pricing from `records` output with subagent
attribution intact, and the published example report.
Pliki w paczce (12)
  • SKILL.md 14 KB
  • openai_usage.py 38 KB
  • prices/openai-api-2026-11-06.json 27 KB
  • reference/example-report.md 4 KB
  • tests/test_openai_usage.py 27 KB
  • tests/fixtures/example/attribution.json 1 KB
  • tests/fixtures/example/ledger.jsonl 1 KB
  • tests/fixtures/example/codex/sessions/2026/11/06/rollout-2026-11-06T10-00-00-00000000-0000-4000-8000-00000000000a.jsonl 6 KB
  • tests/fixtures/example/codex/sessions/2026/11/06/rollout-2026-11-06T10-10-00-00000000-0000-4000-8000-00000000000b.jsonl 4 KB
  • tests/fixtures/example/codex/sessions/2026/11/06/rollout-2026-11-06T10-20-00-00000000-0000-4000-8000-00000000000c.jsonl 5 KB
  • tests/fixtures/example/codex/sessions/2026/11/06/rollout-2026-11-06T10-25-00-00000000-0000-4000-8000-00000000000d.jsonl 3 KB
  • tests/fixtures/example/codex/sessions/2026/11/06/rollout-2026-11-06T10-40-00-00000000-0000-4000-8000-00000000000e.jsonl 1 KB

Wersje

W bazie nie ma innych skilli o nazwie openai-usage.

Migawka bazy z 13.11.2026 · wersja paczki 894e36db86ee (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100cost-estimate
    Szacuje koszt zadania przed jego rozpoczęciem: analizuje złożoność, przewiduje zużycie tokenów i porównuje koszt we wszystkich modelach Claude.
  • 100cost-tracking
    Śledzi i raportuje zużycie tokenów OpenAI Codex, wydatki i budżety z lokalnej bazy kosztów, także w podziale na projekty, narzędzia, sesje i daty.
  • 100openai-api
    Wspiera budowę na API OpenAI: dobór aktualnych modeli, wzorce Responses API, wskazówki dla modeli Codex, streaming, ustrukturyzowane wyjścia, ponawianie i zarządzanie kluczami.
  • 100lanshu-openai-media-api
    Generuje tekst i obrazy oraz transkrybuje dźwięk przez API OpenAI w automatyzacjach agentów, z rejestrem zużycia.
  • 100usage
    Pokazuje zużycie tokenów i koszt API tej rozmowy lub wszystkich, z kontekstem i limitami planu.
  • 100tokenmeter
    Otwiera lokalny panel Tokenmeter, który pokazuje zużycie tokenów, koszty, okna limitów i chybienia cache dla Claude Code i Codex.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.