Cache and usage

CrawlVolt combines monthly billing quotas, short-window request controls and cost telemetry. These mechanisms have different purposes: quotas enforce the commercial plan, request controls protect browser capacity, and telemetry shows what produced the underlying cost.

Render cache

POST /v1/scrape accepts cache_ttl_secs from 0 to 86400 seconds.

• Omit it to use the platform render-cache policy.
• Set it to 0 to force a fresh render.
• Set a positive value to opt into reuse for at most that duration.
• Responses expose from_cache.
• Structured extraction runs after cache lookup, so a cached rendered page can be evaluated against a new deterministic schema.
• Browser actions and persisted sessions always bypass cache because their state is request-specific.

A cache hit still consumes one scrape_page commercial unit. Cost telemetry records zero browser_units for the hit, which lets pricing decisions separate API value from browser-runtime cost.

Request controls

API keys have independent request budgets identified by a one-way hash. User session JWTs share the project budget. Rate limits are shared through Redis when REDIS_URL is configured and otherwise fall back to process memory. Concurrency fairness is enforced per API process; the Bastos browser pool also enforces the deployment-wide engine capacity for that process.

The defaults can be changed with:

• WEBDASH_FREE_REQUESTS_PER_MINUTE
• WEBDASH_PRO_REQUESTS_PER_MINUTE
• WEBDASH_FREE_MAX_CONCURRENT_REQUESTS
• WEBDASH_PRO_MAX_CONCURRENT_REQUESTS

Successful responses include:

x-ratelimit-limit: 30
x-ratelimit-remaining: 29
x-concurrency-limit: 2
x-concurrency-active: 1

429 rate_limit_exceeded and 429 concurrency_limit_exceeded include Retry-After and are not billed.

Usage API

API keys need the v1.usage scope.

curl https://www.crawlvolt.com/v1/usage \
  --header "Authorization: Bearer $CRAWLVOLT_API_KEY"

The response contains the billing period, plan quotas, committed billing usage, remaining units, current request limits and these cost counters:

Telemetry is keyed by the same account-scoped idempotency identity as billing, so retrying the same logical request does not duplicate cost counters. Usage responses are private and return Cache-Control: private, no-store.

Developer operations

GET /v1/usage also returns:

• usage_by_output_format, with monthly operation totals for each requested output format;
• recent_requests, the latest 50 authenticated product calls from the last 30 days;
• the project request-per-minute and concurrency limits.

Each recent request includes its operation, outcome, HTTP status, typed error code, duration, trace request_id, credential type, cache state, browser and action units, output bytes and output formats. Crawl page costs are grouped under the crawl's public request ID, so one crawl remains one API call in the log while preserving its total browser cost.

The request log is separate from billing telemetry. Failed and partial calls can therefore appear in operations without increasing monthly usage. Logs are isolated by account and project; the account dashboard accesses them through a session-only same-origin BFF and never exposes the session JWT to browser code.