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:
{
...
"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.
curl -s "https://api.privatemind.com/v1/usage?from=2026-06-01&limit=100" \
-H "Authorization: Bearer $PMIND_KEY"{
"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. |
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:
# 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"{
"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) or responses (Responses API) |
metadata.<key> |
A request-tag value, e.g. metadata.project |
day,<dim> |
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,<dim> |
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,<dim> and hour,<dim>, 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.
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:
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.
Tags are stored and queryable. Don't put anything sensitive (emails, message contents, personal data) in them.
Where next
- Chat completions: the
metadatafield you set tags with. - Rate limits & budgets: how
total_tokensmaps to rate-limit buckets, and how to read limit headers. - Authentication: how to use your
PMIND…API key.