Usage

Customer-facing usage telemetry for your own API key. Date-range breakdown of request counts, status codes, formats, daily activity, and credits charged. Useful for billing reconciliation, alerting, and custom dashboards without screen-scraping the internal admin UI.

Endpoint

GET https://api.brandmappr.com/api/v1/usage

Auth via the x-api-key header. You only see your own key's usage. Not credit-charged — reading your own usage data is free.

Parameters

Parameter	Type	Default	Description
`from`	ISO timestamp	`now - 30 days`	Window start
`to`	ISO timestamp	`now`	Window end

The window is capped at 366 days to prevent unbounded scans.

Example request

curl "https://api.brandmappr.com/api/v1/usage?from=2026-05-01T00:00:00Z&to=2026-05-24T23:59:59Z" \
  -H "x-api-key: bm_live_YOUR_KEY"

Response shape

{
  "api_key_id": "8c34c5f3-…",
  "billing_model": "credits",
  "range": {
    "from": "2026-05-01T00:00:00.000Z",
    "to": "2026-05-24T23:59:59.000Z",
    "days": 23
  },
  "summary": {
    "total_requests": 1247,
    "error_count": 18,
    "error_rate_percent": 1.44,
    "total_credits_charged": 1583
  },
  "by_status": {
    "200": 1229,
    "402": 12,
    "404": 6
  },
  "by_format": {
    "png": 854,
    "json": 391,
    "csv": 2
  },
  "by_day": [
    { "date": "2026-05-01", "requests": 41, "errors": 0, "credits": 51 },
    { "date": "2026-05-02", "requests": 67, "errors": 1, "credits": 82 }
    // ...
  ]
}

Field reference

by_status — map of HTTP status code to count. "unknown" is used for rows in usage_logs that predate migration 028 (which added the status_code column).
by_format — map of format_requested to count. "unknown" is used for rows that don't have a format recorded (rare; legacy).
by_day — daily time series sorted oldest first. credits is the sum of credits_charged for that day. Useful for charting.

Use cases

Billing reconciliation — total credits_charged against your Stripe invoices.
Alerting — daily cron that hits /usage?from=… and pages if error_rate_percent > 5 or total_requests drops below a threshold.
Dashboards — feed by_day into a Grafana / Datadog / Looker panel. Mirrors what the internal admin dashboard shows.

Notes

The endpoint paginates internally in 5000-row chunks, so heavy keys with months of data return reliably.
For real-time monitoring, prefer a smaller window (last 24h) and poll every minute. For billing analytics, monthly windows are cheap enough.

Status