--- title: "List recent requests in the key's project, or in every project of its organization" method: GET path: "/v1/requests" tags: ["Requests"] --- # List recent requests in the key's project, or in every project of its organization `GET /v1/requests` ## Request - Base URL: `https://api.spicrawl.com` - URL: `https://api.spicrawl.com/v1/requests` - Auth: HTTP bearer Per-request records from the ephemeral request log, newest first, for the API key's project (every key in that project, not only this key). With `all_projects=true` and a key carrying the `read` scope, the records of every project in the key's organization (archived projects included), merged into one newest-first list under the same cursor. Every record carries `project_id`. Records expire after `page.retention_hours`; for durable billing totals use `GET /v1/usage`. Totals here will not match an invoice. Pitfalls: - Page with BOTH `before` and `before_id` copied from `page.next_before` / `page.next_before_id`. `before` alone re-returns the boundary record and cannot break same-millisecond ties; `before_id` alone does not bound the page at all. - A cursor older than the retention window returns 410 `ERR::REQUEST::BEYOND_RETENTION`. Restart from the first page. - An empty `data` means "nothing in the last `retention_hours`", not "never". Check `retained_since`. - A page can be shorter than `limit` while `has_more` is true. Keep paging until `has_more` is false. - `limit` is clamped silently: missing, non-numeric or non-positive gives 50, above 200 gives 200. - `all_projects=true` without the `read` scope is 403 `ERR::AUTH::INSUFFICIENT_SCOPE`, naming `read`. The default list needs no scope beyond a valid key. The organization is always the key's own; no parameter names another. - Keep `all_projects=true` on every page of one walk: the cursor pages whichever list it came from. ## Query parameters - `all_projects` 'true' | 'false' - `limit` integer - `status` 'success' | 'failed' | 'timeout' | 'blocked' | 'rejected' | 'cancelled' - `only_errors` 'true' | 'false' - `before` string, date-time - `before_id` string ## Response `200` One page of request records plus the retention facts needed to interpret it. - RequestLogPage - `data` RequestLogEntry[], required: Records, newest first. Can be shorter than `limit` even when `has_more` is true. - `id` string, required: Request id; the same value as the `X-Request-Id` header and problem `request_id`. - `created_at` string, date-time, required: When the request arrived, RFC 3339 with fractional seconds, UTC. - `project_id` string, required: Project whose API key made the request. Always present; tells rows apart in an `all_projects=true` list. - `engine` string: Rendering tier that served it (`fetch`, `js` or `browser`). Empty for requests refused before a tier was chosen. - `status` 'success' | 'failed' | 'timeout' | 'blocked' | 'rejected' | 'cancelled', required: Terminal outcome. Only `success` is ever charged. - `http_status` integer: Target's HTTP status. Absent when no response was received. - `error_code` string: Problem code returned to the caller, e.g. `ERR::UPSTREAM::CHALLENGE`. Absent on success. - `error_detail` string: The problem detail sentence the caller received (may be truncated). Read it for the specific cause. - `attempts` integer: Dispatch attempts including retries. Absent when zero. - `url` string, required: Target URL as requested. - `url_host` string: Target host. Absent when unknown. - `proxy` RequestLogProxy, required: What was requested versus what actually served. Never contains an exit IP or credentials. Every field is absent when unknown. - `source` 'pool' | 'custom' | 'direct': Where the exit came from: the managed pool, your own proxy, or no proxy. - `endpoint_id` string: Pool exit id, e.g. `dc-198.51.100.7-6646`. Not an exit IP. Absent for custom and direct. - `provider` string: Proxy provider name. - `requested_tier` string: Tier the request asked for, e.g. `datacenter`, `residential`. - `requested_country` string: Country the request asked for. - `country` string: Country the exit actually served from. Compare with `requested_country` to spot geo mismatches. - `sticky` boolean: True when the exit was pinned. Absent when false. - `reason` 'caller_proxy' | 'configured_direct' | 'no_pool_available' | 'session_proxy_unavailable': Why this source was chosen. `session_proxy_unavailable` is a request in a session that records a datacenter exit on a deployment with no proxy pool; it went direct. Absent means unknown (older records), not a default. - `endpoints` string[]: Every exit the request touched, in attempt order. Several entries mean retries moved exits. - `spans` RequestLogSpans, required: Latency breakdown in milliseconds. Every field is always present; null means the stage was not measured, which is different from 0. Spans are measured by different processes and do not sum to `total_ms`. - `admission_ms` integer, nullable, required: Ingress to dispatch: auth, rate limit, quota, concurrency. Null when the request never reached dispatch. - `dispatch_ms` integer, nullable, required: Worker round trip as timed by the API, including transport. `dispatch_ms - worker_ms` is transport overhead. - `worker_ms` integer, nullable, required: The worker's own handler time. - `queue_ms` integer, nullable, required: Wait for a slot inside the worker. High values mean capacity shortage, not a slow page. - `engine_ms` integer, nullable, required: Engine occupancy, the metered compute. Null on the fetch tier. - `upstream_ms` integer, nullable, required: Time talking to the target. - `extract_ms` integer, nullable, required: Extraction time; null when no extraction ran. - `total_ms` integer, nullable, required: What the caller experienced inside the handler, excluding writing the body. - `blocked` RequestLogBlock: Present only when a bot challenge was detected. Use `vendor` to pick a countermeasure (e.g. stealth rendering or residential exit). - `vendor` string: Anti-bot vendor, e.g. `akamai`, `cloudflare`. - `signal` string: Observable marker that triggered detection, so you can confirm it in the response. - `rule` string: Which detection path fired. - `bytes_in` integer: Bytes received from the target. Absent when zero. - `bytes_out` integer: Bytes sent to the target. Absent when zero. - `proxy_bytes` integer: Bytes carried through a proxy exit. Absent when zero. - `credits_micro` integer, required: Credits charged in micro-credits (1 credit = 1000000). Always 0 for non-success statuses. - `features` object: Features the request used, as recorded by the router. Free-form; absent when none. - `page` RequestLogPageInfo, required - `retention_hours` integer, required: How long records are kept for this organization (24 by default). An empty page means nothing within this window. - `retained_since` string, date-time, required: Oldest instant still readable. Anything earlier has expired. - `has_more` boolean, required: True when more records may exist. Continue with the next_before pair; an extra empty page is possible. - `next_before` string, date-time: Send back as `before`. Present only when `has_more` is true. - `next_before_id` string: Send back as `before_id` together with `before`. Present only when `has_more` is true. ## Other responses - `400`: The request is invalid. Not retryable; fix the request using `code` and `diagnostics.hint`. - `401`: Missing, invalid, revoked or expired key. Not retryable with the same key. - `403`: `all_projects=true` from a key without the `read` scope (`ERR::AUTH::INSUFFICIENT_SCOPE`, naming `read`). - `410`: The resource existed but is past its retention window or was purged. Not retryable. - `500`: Internal error. Retryable when `retryable` is true. --- [API](https://skmtc.dev/spicrawl/apis/spicrawl-api.md) · [All operations](https://skmtc.dev/spicrawl/apis/spicrawl-api/llms.txt) · [OpenAPI document](https://skmtc.dev/spicrawl/apis/spicrawl-api/revisions/c4b4c6f97219?raw)