/v1/usage

Current period counts against the plan's caps so you can alert on headroom before we refuse you. Unlimited caps are null with a limit_note, never a magic zero. Redis down is 503 dependency_unavailable — we never invent a count.

Authentication

Authorization: Bearer spw_…

Requires usage:read.

Worked example

choice remembered on every block

curl https://spoolway.com/api/v1/usage \
  -H "Authorization: Bearer spw_…"

200 — Free plancaptured LOCAL

{
  "data": {
    "period": {
      "timezone": "UTC",
      "day": "2026-08-06",
      "month": "2026-08"
    },
    "plan": "Free",
    "daily": {
      "used": 7,
      "limit": 1000,
      "remaining": 993,
      "limit_note": null
    },
    "monthly": {
      "used": 42,
      "limit": 10000,
      "remaining": 9958,
      "limit_note": "signal only — exceeding the monthly figure does not reject sends"
    }
  }
}

200 — unlimited planTeam · limits null with notes

{
  "data": {
    "period": {
      "timezone": "UTC",
      "day": "2026-08-06",
      "month": "2026-08"
    },
    "plan": "Team",
    "daily": {
      "used": 3,
      "limit": null,
      "remaining": null,
      "limit_note": "unlimited — plan has no daily send cap"
    },
    "monthly": {
      "used": 11,
      "limit": null,
      "remaining": null,
      "limit_note": "unlimited — plan has no monthly volume cap"
    }
  }
}

Null, not zero

HONESTY NOTE — NEVER INVENT A COUNTUnlimited caps return limit: null, remaining: null, and a limit_note that says why — never 0 as a stand-in. On Free/Pro the monthly figure is a signal only (see limit_note); daily reject when exceeded. If Redis cannot answer, the endpoint is 503 with type: dependency_unavailable and Retry-After: 30 — not a zero that would look like headroom.

Responses & failures

403 without usage:read. 503 when the counter dependency is down — honour Retry-After; do not treat absence of a body as unlimited headroom.