Usage

/usage is not the same as /billing/usage (which tracks email sends). This endpoint returns API request analytics — useful for traffic attribution by client kind (direct curl vs MCP server vs SDK).

Get usage stats

GET /usage?since=7d
Authorization: Bearer <key>

Query	Default	Notes
since	7d	Either Nd (last N days) or an ISO 8601 timestamp.

Response

{
  "since": "2026-04-21T00:00:00Z",
  "total": 1342,
  "by_kind": {
    "direct": 824,
    "mcp":    501,
    "sdk":    17
  },
  "by_kind_per_day": {
    "direct": { "2026-04-27": 124, "2026-04-28": 89 },
    "mcp":    { "2026-04-27": 78,  "2026-04-28": 65 }
  },
  "top_paths": [
    { "client_kind": "direct", "method": "GET",  "path": "/campaigns",                  "count": 312 },
    { "client_kind": "mcp",    "method": "POST", "path": "/campaigns/:id/dispatch",     "count": 187 },
    { "client_kind": "direct", "method": "GET",  "path": "/campaigns/:id/send_forecast", "count": 64 }
  ]
}

Field reference

• total — total authenticated requests in the window.
• by_kind — counts by client_kind of the calling API key (direct / mcp / sdk). Helps you understand whether traffic is coming from human curl, an LLM via the MCP server, or an SDK integration.
• by_kind_per_day — daily buckets per kind, useful for charting trends.
• top_paths — top 50 (method, path, kind) tuples ordered by count descending. Path includes the route template — concrete IDs are normalized to :id.
• since — echoed window start so you can confirm the parser interpreted your input correctly.

Notes

• Public/anonymous routes (tracking pixels, unsubscribe pages, inbound webhooks) are not counted.
• Authenticated routes that fail authentication are not counted (no API key → no log).
• Health probes to GET /status are not counted.
• Logs are kept indefinitely — no automatic pruning. We may add a retention setting in the future.