More endpoints
GET /v1/usage

GET /v1/usage

Returns current-period usage and quota for the authenticated tenant.

The period is the current calendar month (YYYY-MM). Counters reset at the start of each month.

Request

GET /v1/usage
x-api-key: YOUR_KEY

No request body.

Example request

curl https://api.superscraper.dev/v1/usage \
  -H "x-api-key: ss_live_xxxxxxxxxxxxxxxxxxxx"

Response

HTTP 200 on success.

Body

FieldTypeDescription
planstringCurrent plan: "free", "starter", "pro", "business", or "enterprise"
pages_scrapednumberPages scraped in the current period
pages_quotanumberMonthly page scrape quota for this plan
llm_extractionsnumberLLM-powered extractions used in the current period
extract_quotanumberMonthly LLM extraction quota for this plan
cost_usdnumberTotal LLM cost incurred (USD) in the current period
year_monthstringCurrent period in YYYY-MM format

Example response

{
  "plan": "pro",
  "pages_scraped": 14823,
  "pages_quota": 100000,
  "llm_extractions": 412,
  "extract_quota": 10000,
  "cost_usd": 0.1148,
  "year_month": "2026-06"
}

Example response, new account (no usage yet)

{
  "plan": "free",
  "pages_scraped": 0,
  "pages_quota": 1000,
  "llm_extractions": 0,
  "extract_quota": 0,
  "cost_usd": 0,
  "year_month": "2026-06"
}

pages_quota and extract_quota are read from the tenant row, not a hardcoded table here, see Pricing for the credit allotments and overage rates per plan, which are the source of truth.

Errors

StatusErrorCause
401UnauthorizedMissing or invalid x-api-key header, or tenantId not set
404Tenant not foundAuthenticated tenant does not exist in the database
500Internal server errorDatabase error

Notes

  • Usage is aggregated in the usage_monthly table. Rows are created on the first request of each month and incremented by the logUsage middleware as requests complete.
  • cost_usd reflects LLM model costs (DeepSeek/Claude/Llama) logged per /v1/extract call. Scrape and enrichment costs are fixed-rate and not included in this figure.
  • This endpoint is also accessible at GET /v1/billing/usage (same implementation, mounted twice for convenience).
POST /v1/enrich/websiteBilling