Get API key

Usage

View as Markdown

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.

cURL
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.
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:

cURL
# 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) 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.

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:

cURL
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