generated: '2026-10-07'
method: searched
source:
- https://litescrape.com/docs/reference
- https://litescrape.com/docs/key-status
- https://litescrape.com/pricing
- live unauthenticated probes of https://api.litescrape.com/api/google/search and /api/keys/status (401, 2026-10-07)
description: Cross-cutting behaviour of the Litescrape REST API at api.litescrape.com as the reference documents it, with the request/response conventions an agent needs before calling it.
base_url: https://api.litescrape.com
api_style: REST over HTTPS; GET with query parameters for every search, maps, reviews and app-store endpoint; JSON responses; POST bodies only for Fetch and Screenshot options and PATCH for the key ZDR setting.
authentication:
  scheme: Bearer API key in the Authorization header
  key_prefix: ls_live_
  docs: https://litescrape.com/docs/key-status
  detail: authentication/litescrape-authentication.yml
  note: '"Send Authorization: Bearer YOUR_API_KEY in the request headers. Never place your key in the URL or browser bundle." (key-status page). The MCP server also accepts ?api_key= in HTTP mode.'
idempotency:
  coverage: na
  mechanism: null
  header: null
  retention: null
  docs: https://litescrape.com/docs/reference
  note: The API has no mutating business surface. Every search, maps, reviews, shopping and app-store endpoint is a read; Fetch and Screenshot accept POST only to carry page options and return a fresh render; the single state change is PATCH /api/keys/zdr, which sets a boolean key setting and is idempotent by construction. No Idempotency-Key header is documented and none is needed.
reversibility:
  coverage: na
  note: No write surface to reverse. The one setting write, PATCH /api/keys/zdr, is undone by sending {"zdr_enabled":false}; enabling it removes completed batch results (ZDR policy), which the policy states and does not promise to restore.
dry_run_mode: none
pagination:
  style: mixed (offset and opaque continuation token, by upstream engine)
  request_params:
    start: Google Search, Google Local and DuckDuckGo result offset (DuckDuckGo 0 through 10,000; Google Local through 10,000)
    first: Bing Search offset (response pagination.next carries the ready URL, e.g. ...&first=11)
    num: Result count where the engine supports it (search and google_search 1 to 10 per MCP changelog 0.3.0)
    next_page_token: Opaque continuation token for Google Reviews and Google Maps Posts ("Pass the token back unchanged"; 16 to 4,096 characters)
  response_fields:
    pagination.next: Bing Search next-page URL
    pagination.next_page_token: Google Reviews continuation token
  docs: https://litescrape.com/docs/reference
field_expansion:
  supported: false
  note: '"The endpoint returns the complete parsed response; shape it in your client." (SerpAPI parameter map). MCP tools accept result_groups to keep only named result groups.'
metadata:
  supported: false
request_tracing:
  request_id_header: x-request-id
  body_field: request_id
  description: Every response carries an x-request-id header and every error body a request_id (observed on live 401 probes 2026-10-07; "Every JSON error includes a machine-readable code, request ID, and retry guidance.").
versioning:
  scheme: unversioned
  mechanism: No version segment in paths (/api/<engine>/<surface>) and no version header. Endpoint maturity is labelled on the docs index (Google Ads, Google Play, Apple App Store, Fetch and Screenshot are "Alpha").
  detail: lifecycle/litescrape-lifecycle.yml
  changelog: changelog/litescrape-changelog.yml
error_envelope:
  media_type: application/json
  rfc9457: false
  shape: '{ "error": <message>, "error_code": <snake_case code>, "status_code": <int>, "request_id": <hex>, "retryable": <bool>, "search_parameters": {...} }'
  retry_guidance: '"Fix 400-level request errors before retrying." Retry 503 "after Retry-After when retryable is true".'
  detail: errors/litescrape-problem-types.yml
  docs: https://litescrape.com/docs/reference#errors
rate_limit_signaling:
  signal_status: 429
  retry_after: Retry-After on 503 when retryable is true
  headers_documented: none (no X-RateLimit-* or RateLimit headers documented; none observed on live 401 responses)
  concurrency: concurrency_limit field of GET /api/keys/status (25 by default) is the documented way to size client concurrency
  detail: rate-limits/litescrape-rate-limits.yml
  docs: https://litescrape.com/docs/key-status
billing_conventions:
  per_call: '"One request, one call" at $0.15 per 1,000 for every endpoint; "You pay for HTTP 200 responses only."'
  balance: GET /api/keys/status returns remaining_calls, concurrency_limit, status, zdr_enabled and credit-expiry information
  exhaustion: 402 "Key needs a one-time Stripe top-up"