Skip to content
ScreenshotDude

API reference

Usage

Remaining subscription quota, packs, credits, rate limits and key details. Free.

GEThttp://localhost:4000/v1/usage
Credit cost
Free
Async
No
404 billed
—
Plans
All plans

Authenticate with the x-api-key header. See authentication and credits & billing.

Code examples

curl "http://localhost:4000/v1/usage" \
  -H "x-api-key: $SNAPLENS_API_KEY"

Responses

200 — application/json

{
  "remaining": 7450,
  "total_used": 7550,
  "renewal_date": "2026-12-01",
  "period": {
    "start": "2026-11-01",
    "end": "2026-12-01"
  },
  "plan": {
    "id": "pro",
    "name": "Pro",
    "interval": "month"
  },
  "subscription": {
    "used": 7550,
    "total": 15000,
    "remaining": 7450,
    "percent_used": 50.3
  },
  "packs": {
    "count": 1,
    "exhausted_count": 0,
    "all_exhausted": false,
    "total": 5000,
    "used": 0,
    "remaining": 5000,
    "percent_used": 0,
    "current_index": 1,
    "current": {
      "id": "pck_9x2k1m4n7b5v3c8z0l6q1w2e",
      "title": "5K pack",
      "purchased_at": "2026-10-14",
      "expires_at": "2027-10-14",
      "total": 5000,
      "used": 0,
      "remaining": 5000,
      "percent_used": 0,
      "exhausted": false
    },
    "items": [
      {
        "id": "pck_9x2k1m4n7b5v3c8z0l6q1w2e",
        "title": "5K pack",
        "purchased_at": "2026-10-14",
        "expires_at": "2027-10-14",
        "total": 5000,
        "used": 0,
        "remaining": 5000,
        "percent_used": 0,
        "exhausted": false
      }
    ]
  },
  "credits": {
    "given": 0,
    "consumed": 0,
    "remaining": 0,
    "percent_used": 0
  },
  "overage": {
    "used": 0,
    "unit_price": 0.008,
    "enabled": true
  },
  "rate_limit": {
    "per_minute": 500,
    "per_second": 10
  },
  "account": {
    "name": "Acme Inc.",
    "slug": "acme"
  },
  "api_key": {
    "alias": "Production backend",
    "active": true,
    "category": "production",
    "expires": null,
    "quotas": {
      "total": null,
      "daily": 2000,
      "weekly": null,
      "monthly": null
    }
  }
}

Response fields

Field Type Description
remaining number Credits you can still use before overage: subscription + packs + credits ledger.
total_used number Credits used this period (subscription + packs) plus credits consumed from the ledger.
renewal_date date When the subscription quota resets (YYYY-MM-DD).
period.start, period.end date Current billing period.
plan.id, plan.name, plan.interval string Your current plan and billing interval.
subscription.used number Used from subscription quota and packs combined.
subscription.total number Plan quota plus active pack credits.
subscription.remaining number total − used.
subscription.percent_used number Percentage of the combined total used.
packs object | null null when you have no active packs.
packs.count number Packs with credits left.
packs.exhausted_count number Packs fully used.
packs.all_exhausted boolean true when every pack is used up.
packs.total, packs.used, packs.remaining number Totals across non-expired packs.
packs.percent_used number Percentage of pack credits used.
packs.current_index number | null 1-based position of the pack currently being consumed.
packs.current object | null That pack (same shape as an item).
packs.items[] object[] Each pack: id, title, purchased_at, expires_at, total, used, remaining, percent_used, exhausted. Ordered by purchase date.
credits.given, credits.consumed, credits.remaining number Credits ledger balances.
credits.percent_used number Percentage of ledger credits consumed.
overage.used number Overage credits used this period.
overage.unit_price number | null Price per overage credit in USD (null on Free).
overage.enabled boolean Whether requests continue past your balance.
rate_limit.per_minute, rate_limit.per_second number Your plan's rate limits.
account.name, account.slug string Workspace.
api_key.alias string Alias of the key used for this request.
api_key.active boolean Key status.
api_key.category string production, development, staging or custom.
api_key.expires ISO date | null Key expiry.
api_key.quotas object { total, daily, weekly, monthly } — null means unlimited.

/v1/usage is free and isn't counted against credits, but it is subject to rate limits.

Errors

Errors return JSON { "error": "…" }. Failed requests are never billed. Full list in Status codes.

StatusMeaning
401Invalid, inactive or expired API key; plan rate limit (Rate limit exceeded: …) or key quota (…: quota daily)
403IP temporarily blocked after repeated authentication failures
500Unexpected server error — retry with backoff