Track spend

Every response and every piece of adaptation work a mind does is charged to that mind. Instead of estimating cost from response tokens and your own price table, read the platform's figure and stop when a run reaches its budget.

Summarize usage for a set of minds

Pass each mind ID as its own mind_id parameter, up to 50 per request:

curl "https://api.pluralmatter.com/v1/usage/summary?mind_id=mind_example&mind_id=mind_fork_example&since=2026-09-01T00:00:00Z" \
  --header "Authorization: Bearer $PLURALMATTER_API_KEY"

The response reports the window it applied, a total, and one row per mind:

{
  "currency": "USD",
  "since": "2026-09-01T00:00:00.000Z",
  "until": "2026-09-02T10:15:00.000Z",
  "total": {
    "customer_charge_usd": "0.300070000",
    "input_tokens": 108,
    "output_tokens": 24,
    "cache_read_tokens": 30,
    "cache_write_tokens": 40,
    "requests": 2
  },
  "minds": [
    {
      "mind_id": "mind_example",
      "customer_charge_usd": "0.300070000",
      "input_tokens": 108,
      "output_tokens": 24,
      "cache_read_tokens": 30,
      "cache_write_tokens": 40,
      "requests": 2
    },
    {
      "mind_id": "mind_fork_example",
      "customer_charge_usd": "0.000000000",
      "input_tokens": 0,
      "output_tokens": 0,
      "cache_read_tokens": 0,
      "cache_write_tokens": 0,
      "requests": 0
    }
  ]
}

Reading the figures

customer_charge_usd is the amount you are charged, as a string with exactly nine decimal places. Parse it as a decimal rather than a float so small per-request amounts add up exactly.

The charge includes the mind's own adaptation work recorded under your requests, not only the response you received. That makes it the right figure for a spend cap: it is what appears on your bill, at the prices in force when each request ran.

requests counts distinct requests. A response and the work it triggered count once.

Choosing a window

since is inclusive and until is exclusive. Both are ISO-8601 instants with an explicit offset. until defaults to now and since to 30 days earlier; the window may cover at most 90 days. Set since to the moment a run started to read only that run's spend.

Which minds are included

The key sees the minds in its own project. Minds outside that project, unknown IDs, and repeated IDs are left out of minds and total rather than reported as errors, so check that every mind you asked for is present when the set matters. A mind with no usage in the window is returned with zero values.

The summary is cheap to poll, so a scheduler can call it on every tick for the minds it is running.