Usage Export for your AI API — every request, token and cost in one CSV
Download every request your workspace makes — model, tokens, cost, status and latency — as a CSV with a fixed header. Built for finance reconciliation and warehouse loads.
Who it is for
Teams that need to reconcile an AI bill, charge usage back to customers, or prove what was spent to a finance team.
The problem it removes
- The invoice shows one number and no attribution.
- Support cannot answer "what did customer X cost us last month?"
- Finance cannot reconcile AI spend against the budget line.
What you get
- CSV with created_at, model, prompt/completion/total tokens, cost_usd, status and latency
- Up to 100,000 rows per request, 50,000 by default
- 90-day window
- X-Plugsky-Rows and X-Plugsky-Truncated headers so a client knows when there is more
- Per-workspace isolation — the bearer key decides the scope
How to use it
1. Add the add-on
Open Dashboard → Billing → Add-ons and activate Usage Export. Checkout is handled by Stripe; access is granted by webhook within seconds.
2. Call the endpoint
Send your workspace API key as a bearer token. The response is text/csv.
3. Load it into your tools
The header row is stable, so a Sheets import or a warehouse load can be scheduled without transformation.
curl -sS "https://plugsky.com/api/addons/usage/export.csv?limit=5000" \
-H "Authorization: Bearer $PLUGSKY_SESSION" \
-o usage.csv
What the CSV contains
The export is deliberately boring: one row per completed request, a fixed header, and no nested objects. That is what makes it loadable by a spreadsheet, a warehouse job or a finance script without a transformation step that someone has to maintain.
| Column | Type | Why it is there |
|---|---|---|
| created_at | timestamp | The billing period boundary; also the join key for a daily series |
| model | text | The model actually served, including fallbacks |
| prompt_tokens | integer | Input size; the number that grows when context is resent |
| completion_tokens | integer | Output size; the number an output cap controls |
| total_tokens | integer | Prompt plus completion, stored rather than derived so it reconciles with the invoice |
| cost_usd | decimal | Recorded cost for the request, to six decimal places |
| status | text | ok, fallback or error — the field that separates paid usage from failed attempts |
| latency_ms | integer | Round-trip time, useful when a slow model is also an expensive one |
How to reconcile a monthly invoice
Reconciliation is four steps, and the fourth is the one that catches problems.
- Export the billing window. Pass
?limit=up to 100,000. The default is 50,000, and theX-Plugsky-Truncatedheader tells you whether the cap was reached. - Sum
cost_usd. Compare it with the invoice total. A small difference is normal if the invoice includes a subscription and the export covers usage only; a large one means the windows do not match. - Filter by status. Failed requests should not be charged. If they carry a cost, that is a finding worth a support ticket.
- Group by model. The largest group is the one to look at first. A model you did not expect to dominate is usually a routing rule doing something unintended.
The export is a record of what the platform stored, not a re-derivation from prices. That distinction matters: if a price changed mid-month, the stored cost per request is still the correct one for that request.
What truncation looks like
The endpoint returns two headers that let a client decide what to do next without parsing the body: X-Plugsky-Rows and X-Plugsky-Truncated. When the row count equals the limit, the truncated header is 1 and the client should narrow the window or page by date rather than assume the file is complete.
Silent truncation is the most common way an export becomes wrong. The headers exist so a scheduled job can fail loudly instead of loading a partial month into a finance system.
Scope, retention and privacy
The bearer credential decides the scope. A workspace key can only export that workspace's rows, and there is no parameter that widens it. The endpoint does not return prompt or completion text — only counts, model, status, cost and latency — so the file can be shared with finance without a redaction step.
The window is 90 days per request. Older rows remain in the platform but are not served by this endpoint; if you need a longer history for an audit, request it through support and we will tell you what is available rather than promising a date.
What it does not do
- No JSON response. The endpoint returns
text/csv. A JSON consumer should convert the file rather than expect a second representation. - No scheduled email. Export is on demand. A cron job or a warehouse connector is the scheduling layer, and the stable header makes that trivial.
- No per-key column. Attribution is by model, status and time. Per-key or per-customer attribution needs a key identifier recorded at request time, which the current usage record does not carry.
- No writes. The endpoint is read-only; it cannot delete or amend usage records.
Those limits are listed because a buyer should know them before paying, not after. If per-key attribution is the actual requirement, say so at support and we will tell you whether it is on the roadmap or not.
Loading it into a spreadsheet or warehouse
For a spreadsheet, save the response as .csv and import with comma delimiters and UTF-8 encoding. created_at parses as an ISO timestamp in most tools; if yours expects a local timezone, convert after import rather than before, so the stored value stays comparable across months.
For a warehouse, schedule a nightly request for the previous day and append. Because created_at is UTC and the row set for a closed day does not change, an append-only load is safe. A full 90-day pull every night also works and is simpler to reason about; the endpoint is cheap enough that the choice is about operational preference, not cost.
When it is not worth $19
If you have one workspace, one model and a bill under a hundred dollars, the platform's own usage screen answers the same question. The export earns its price when the file has to leave the dashboard: a finance reconciliation, a chargeback to a customer, or a warehouse table that other reports join against.
Questions
Do I need a separate API key?
No. The add-on is tied to your workspace and uses the same signed-in session or workspace credential as the rest of the dashboard API.
What happens if I ask for more rows than exist?
You get every available row and X-Plugsky-Truncated: 0. The default cap is 50,000 rows; pass ?limit= up to 100,000.
Does it include failed requests?
Yes. The status column carries ok, fallback and error, so you can separate paid usage from failed attempts.
How far back does it go?
90 days. Older data is available through the standard usage API or on request.
Can I cancel?
Yes, from the billing portal. Access ends at the end of the paid period and the endpoint returns 403 afterwards.
Sources
- Plugsky pricing — plan limits and fair use — checked 21 November 2026
- Stripe subscriptions overview — checked 21 November 2026
- Plugsky privacy policy — checked 21 November 2026
Related add-ons
Spend Guard
A window from 1 to 365 days, grouped by model, by day and by status, so you can find the feature that is eating the budget before the invoice arrives.
AI Cost Index Pro
A dated JSON dataset of Plugsky plan prices, intervals and the live model capability matrix, built for procurement comparison and internal budgeting.
Migration Service
A compatibility review, a shadow-traffic run and a quality diff before cutover, so you change the base URL with evidence instead of hope.
Activate from the dashboard; Stripe handles the subscription and access is granted automatically.
Open billingCompare add-ons