# Usage Track tokens, cost, and limits from every response. Every chat and embedding response includes a `usage` block with that call's token counts. For cost, query your key's rows from `/v1/usage`, below. ## The response `usage` block A successful chat completion or embedding call returns something like this: ```json { ... "usage": { "prompt_tokens": 412, "completion_tokens": 188, "total_tokens": 600 } } ``` | Field | Meaning | | --- | --- | | `prompt_tokens` | Tokens you sent (system prompt + messages, or input text). | | `completion_tokens` | Tokens the model generated in its response. | | `total_tokens` | `prompt_tokens + completion_tokens`. This is what counts against rate limits. | For running totals, add these up as you handle responses. ## Per-key totals in the dashboard The **Usage** tab on each API key page in the PrivateMind app shows that key's total requests, tokens and spend, updated in real time. ## Query your own usage `GET /v1/usage` returns the individual usage rows for **your own key**: only the calls that key made. Authenticate with that same `PMIND…` key, with no special header. ```bash curl -s "https://api.privatemind.com/v1/usage?from=2026-06-01&limit=100" \ -H "Authorization: Bearer $PMIND_KEY" ``` ```json { "success": true, "data": [ { "id": 90431, "model": "fast", "prompt_tokens": 1200, "cached_prompt_tokens": 320, "completion_tokens": 280, "cost_usd": 0.0041, "latency_ms": 1840, "status_code": 200, "api": "openai", "created_at": "2026-06-08T10:12:04Z", "metadata": { "project": "load-company-data", "stage": "webcrawl" } } ], "pagination": { "limit": 100, "offset": 0, "has_more": false } } ``` Query parameters, all optional: | Param | Meaning | | --- | --- | | `model` | Only rows for this model id. | | `metadata` | Tag filter, a URL-encoded JSON object: `metadata={"project":"x"}`. Matches rows whose tags contain every pair you list. See [Tagging requests](https://docs.privatemind.com/usage.html#tagging-requests). | | `from` / `to` | RFC 3339 datetime or `YYYY-MM-DD` date. Defaults to the last 30 days. | | `limit` / `offset` | Page size (default 100, max 1000) and offset. `pagination.has_more` is `true` when another page exists. | ## Break usage down by tag, model, or day `GET /v1/usage/summary` totals the rows for you, so "tokens per project" is one call. It takes the same auth and filters as `/v1/usage`, plus a required `group_by`: ```bash # Spend per project curl -s "https://api.privatemind.com/v1/usage/summary?group_by=metadata.project" \ -H "Authorization: Bearer $PMIND_KEY" # Sub-costs within one project curl -s 'https://api.privatemind.com/v1/usage/summary?group_by=metadata.stage&metadata={"project":"load-company-data"}' \ -H "Authorization: Bearer $PMIND_KEY" ``` ```json { "success": true, "group_by": "metadata.project", "data": [ { "group_value": "load-company-data", "requests": 4120, "prompt_tokens": 5680000, "cached_prompt_tokens": 910000, "completion_tokens": 1240000, "total_tokens": 6920000, "cost_usd": 18.42 }, { "group_value": "sentiment-batch", "requests": 1300, "prompt_tokens": 980000, "cached_prompt_tokens": 0, "completion_tokens": 210000, "total_tokens": 1190000, "cost_usd": 4.10 }, { "group_value": null, "requests": 88, "prompt_tokens": 40000, "cached_prompt_tokens": 0, "completion_tokens": 9000, "total_tokens": 49000, "cost_usd": 0.20 } ], "pagination": { "limit": 100, "offset": 0, "has_more": false } } ``` `group_by` accepts: | Value | Groups by | | --- | --- | | `model` | Model id | | `day` | UTC calendar date of the request | | `hour` | UTC hour of the request, rendered `YYYY-MM-DDTHH:00:00Z` | | `key_id` | The key that made the call | | `user_id` | The user the key belongs to; for a self-scoped key this is always you | | `workspace` | Traffic source (`chat`, `embeddings`, …) | | `api` | The API the call used: `openai`, `anthropic` ([Messages API](https://docs.privatemind.com/messages-api.html)) or `responses` ([Responses API](https://docs.privatemind.com/responses-api.html)) | | `metadata.` | A request-tag value, e.g. `metadata.project` | | `day,` | UTC date and one of `model`, `workspace`, `api`, `key_id` or `user_id` together, e.g. `day,model` for a daily series per model | | `hour,` | UTC hour and one of the same dimensions, e.g. `hour,model` for an hourly series per model | The `null` group holds untagged traffic. Groups are sorted by cost, except `day,` and `hour,`, which add a `day` or `hour` field to each row and sort by that, then by group value. The window can span at most 366 days, or 31 days when grouping by hour. Split longer ranges into smaller windows. > [!NOTE] > `cost_usd` on the summary is a rounded sum, fine for reporting. For exact figures, such as to reconcile an invoice, add up the per-row `cost_usd` from `/v1/usage`. ## Tagging requests Label any chat completion with a `metadata` map in OpenAI's format, then filter or group your usage by those labels. The map takes up to 16 string pairs, with keys up to 64 characters and values up to 512: ```bash curl -s "https://api.privatemind.com/v1/chat/completions" \ -H "Authorization: Bearer $PMIND_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "fast", "messages": [{"role": "user", "content": "…"}], "metadata": {"project": "load-company-data", "stage": "webcrawl"} }' ``` Tags are stored on the usage row and **never forwarded to the model**. One request can carry several tags, so the call above counts under both `project=load-company-data` and `stage=webcrawl`. A map that breaks these limits, or has a non-string value, returns `400`. > [!TIP] > Tags are stored and queryable. Don't put anything sensitive (emails, message contents, personal data) in them. ## Where next - [Chat completions](https://docs.privatemind.com/chat-completions.html): the `metadata` field you set tags with. - [Rate limits & budgets](https://docs.privatemind.com/rate-limits.html): how `total_tokens` maps to rate-limit buckets, and how to read limit headers. - [Authentication](https://docs.privatemind.com/authentication.html): how to use your `PMIND…` API key.