Usage

Request#

Authenticate with your API key in the x-api-key header (see Authentication).

Parameters#

• periodstringdefault 30dpattern ^(24h|7d|30d|90d)$

  Aggregation window: 24 hours, 7, 30, or 90 days.

Example request#

curl "https://api.scrapercompany.com/v1/usage?period=30d" \
  -H "x-api-key: $SCRAPERCOMPANY_API_KEY"

Response#

200 — Customer-scoped request volume, error rate, bytes, and latency.

{
  "key": {
    "name": "example-production",
    "prefix": "sk_example1",
    "rate_limit_per_min": 600,
    "role": "customer"
  },
  "period": {
    "name": "30d",
    "start": "2026-07-11T19:00:00+00:00",
    "end": "2026-08-10T19:00:00+00:00"
  },
  "totals": {
    "requests": 1842,
    "successful": 1804,
    "errors": 38,
    "rate_limited": 2,
    "response_bytes": 18742311,
    "avg_duration_ms": 482,
    "p95_duration_ms": 2210
  },
  "by_status": [
    {
      "status": 200,
      "requests": 1804
    },
    {
      "status": 422,
      "requests": 36
    }
  ],
  "by_endpoint": [
    {
      "method": "POST",
      "path": "/v1/calendar",
      "requests": 1290,
      "errors": 12,
      "avg_duration_ms": 391,
      "p95_duration_ms": 884
    }
  ],
  "by_day": [
    {
      "date": "2029-01-01",
      "requests": 74,
      "errors": 1,
      "response_bytes": 812204
    }
  ]
}

Response fields#

Fields marked required are always present; others appear when they apply.

• keyobjectrequired
  Show 4 child fieldsHide child fields

  • key.namestringrequired
  • key.prefixstringrequired

    First characters of the key, for display.

  • key.rate_limit_per_minintegerrequired

    This key's requests-per-minute limit.

  • key.rolestringrequired
• periodobjectrequired
  Show 3 child fieldsHide child fields

  • period.namestringrequired

    One of24h7d30d90d

  • period.startstring (date-time)required
  • period.endstring (date-time)required
• totalsobjectrequired
  Show 7 child fieldsHide child fields

  • totals.requestsintegerrequired
  • totals.successfulintegerrequired
  • totals.errorsintegerrequired
  • totals.rate_limitedintegerrequired
  • totals.response_bytesintegerrequired
  • totals.avg_duration_msintegerrequired
  • totals.p95_duration_msintegerrequired
• by_statusarray of objectrequired
  Show 2 child fieldsHide child fields

  • by_status[].statusintegerrequired
  • by_status[].requestsintegerrequired
• by_endpointarray of objectrequired

  Top 50 endpoints by request count.

  Show 6 child fieldsHide child fields

  • by_endpoint[].methodstringrequired
  • by_endpoint[].pathstringrequired
  • by_endpoint[].requestsintegerrequired
  • by_endpoint[].errorsintegerrequired
  • by_endpoint[].avg_duration_msintegerrequired
  • by_endpoint[].p95_duration_msintegerrequired
• by_dayarray of objectrequired
  Show 4 child fieldsHide child fields

  • by_day[].datestring (date)required
  • by_day[].requestsintegerrequired
  • by_day[].errorsintegerrequired
  • by_day[].response_bytesintegerrequired

Errors#

Errors return a JSON body with a detail field. Failed requests are not charged. See Errors for the full list and retry advice.

Try it#

1. Export your key: export SCRAPERCOMPANY_API_KEY=sk_... (no key yet? request access).
2. Copy the cURL example above and run it in a terminal.
3. Or open the interactive playground on api.scrapercompany.com, paste your key and pick this endpoint.