{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/spicrawl-com/json-schema/spicrawl-com-request-log-page-schema.json",
  "title": "RequestLogPage",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/spicrawl-com-requests-api-openapi.yml#/components/schemas/RequestLogPage",
  "type": "object",
  "required": [
    "data",
    "page"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/RequestLogEntry"
      },
      "description": "Records, newest first. Can be shorter than `limit` even when `has_more` is true."
    },
    "page": {
      "$ref": "#/$defs/RequestLogPageInfo"
    }
  },
  "$defs": {
    "RequestLogBlock": {
      "type": "object",
      "description": "Present only when a bot challenge was detected. Use `vendor` to pick a countermeasure (e.g. stealth rendering or residential exit).",
      "properties": {
        "vendor": {
          "type": "string",
          "description": "Anti-bot vendor, e.g. `akamai`, `cloudflare`."
        },
        "signal": {
          "type": "string",
          "description": "Observable marker that triggered detection, so you can confirm it in the response."
        },
        "rule": {
          "type": "string",
          "description": "Which detection path fired."
        }
      }
    },
    "RequestLogEntry": {
      "type": "object",
      "required": [
        "id",
        "created_at",
        "project_id",
        "status",
        "url",
        "proxy",
        "spans",
        "credits_micro"
      ],
      "description": "One API request as recorded in the ephemeral request log. Numeric fields with `omitempty` are absent when zero.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Request id; the same value as the `X-Request-Id` header and problem `request_id`."
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "description": "When the request arrived, RFC 3339 with fractional seconds, UTC."
        },
        "project_id": {
          "type": "string",
          "description": "Project whose API key made the request. Always present; tells rows apart in an `all_projects=true` list."
        },
        "engine": {
          "type": "string",
          "description": "Rendering tier that served it (`fetch`, `js` or `browser`). Empty for requests refused before a tier was chosen."
        },
        "status": {
          "type": "string",
          "enum": [
            "success",
            "failed",
            "timeout",
            "blocked",
            "rejected",
            "cancelled"
          ],
          "description": "Terminal outcome. Only `success` is ever charged."
        },
        "http_status": {
          "type": "integer",
          "description": "Target's HTTP status. Absent when no response was received."
        },
        "error_code": {
          "type": "string",
          "description": "Problem code returned to the caller, e.g. `ERR::UPSTREAM::CHALLENGE`. Absent on success."
        },
        "error_detail": {
          "type": "string",
          "description": "The problem detail sentence the caller received (may be truncated). Read it for the specific cause."
        },
        "attempts": {
          "type": "integer",
          "minimum": 0,
          "description": "Dispatch attempts including retries. Absent when zero."
        },
        "url": {
          "type": "string",
          "description": "Target URL as requested."
        },
        "url_host": {
          "type": "string",
          "description": "Target host. Absent when unknown."
        },
        "proxy": {
          "$ref": "#/$defs/RequestLogProxy"
        },
        "spans": {
          "$ref": "#/$defs/RequestLogSpans"
        },
        "blocked": {
          "$ref": "#/$defs/RequestLogBlock"
        },
        "bytes_in": {
          "type": "integer",
          "format": "int64",
          "minimum": 0,
          "description": "Bytes received from the target. Absent when zero."
        },
        "bytes_out": {
          "type": "integer",
          "format": "int64",
          "minimum": 0,
          "description": "Bytes sent to the target. Absent when zero."
        },
        "proxy_bytes": {
          "type": "integer",
          "format": "int64",
          "minimum": 0,
          "description": "Bytes carried through a proxy exit. Absent when zero."
        },
        "credits_micro": {
          "type": "integer",
          "format": "int64",
          "minimum": 0,
          "description": "Credits charged in micro-credits (1 credit = 1000000). Always 0 for non-success statuses."
        },
        "features": {
          "type": "object",
          "additionalProperties": true,
          "description": "Features the request used, as recorded by the router. Free-form; absent when none."
        }
      }
    },
    "RequestLogPageInfo": {
      "type": "object",
      "required": [
        "retention_hours",
        "retained_since",
        "has_more"
      ],
      "properties": {
        "retention_hours": {
          "type": "integer",
          "minimum": 1,
          "description": "How long records are kept for this organization (24 by default). An empty page means nothing within this window."
        },
        "retained_since": {
          "type": "string",
          "format": "date-time",
          "description": "Oldest instant still readable. Anything earlier has expired."
        },
        "has_more": {
          "type": "boolean",
          "description": "True when more records may exist. Continue with the next_before pair; an extra empty page is possible."
        },
        "next_before": {
          "type": "string",
          "format": "date-time",
          "description": "Send back as `before`. Present only when `has_more` is true."
        },
        "next_before_id": {
          "type": "string",
          "description": "Send back as `before_id` together with `before`. Present only when `has_more` is true."
        }
      }
    },
    "RequestLogProxy": {
      "type": "object",
      "description": "What was requested versus what actually served. Never contains an exit IP or credentials. Every field is absent when unknown.",
      "properties": {
        "source": {
          "type": "string",
          "enum": [
            "pool",
            "custom",
            "direct"
          ],
          "description": "Where the exit came from: the managed pool, your own proxy, or no proxy."
        },
        "endpoint_id": {
          "type": "string",
          "description": "Pool exit id, e.g. `dc-198.51.100.7-6646`. Not an exit IP. Absent for custom and direct."
        },
        "provider": {
          "type": "string",
          "description": "Proxy provider name."
        },
        "requested_tier": {
          "type": "string",
          "description": "Tier the request asked for, e.g. `datacenter`, `residential`."
        },
        "requested_country": {
          "type": "string",
          "description": "Country the request asked for."
        },
        "country": {
          "type": "string",
          "description": "Country the exit actually served from. Compare with `requested_country` to spot geo mismatches."
        },
        "sticky": {
          "type": "boolean",
          "description": "True when the exit was pinned. Absent when false."
        },
        "reason": {
          "type": "string",
          "enum": [
            "caller_proxy",
            "configured_direct",
            "no_pool_available",
            "session_proxy_unavailable"
          ],
          "description": "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": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Every exit the request touched, in attempt order. Several entries mean retries moved exits."
        }
      }
    },
    "RequestLogSpans": {
      "type": "object",
      "required": [
        "admission_ms",
        "dispatch_ms",
        "worker_ms",
        "queue_ms",
        "engine_ms",
        "upstream_ms",
        "extract_ms",
        "total_ms"
      ],
      "description": "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`.",
      "properties": {
        "admission_ms": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "description": "Ingress to dispatch: auth, rate limit, quota, concurrency. Null when the request never reached dispatch."
        },
        "dispatch_ms": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "description": "Worker round trip as timed by the API, including transport. `dispatch_ms - worker_ms` is transport overhead."
        },
        "worker_ms": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "description": "The worker's own handler time."
        },
        "queue_ms": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "description": "Wait for a slot inside the worker. High values mean capacity shortage, not a slow page."
        },
        "engine_ms": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "description": "Engine occupancy, the metered compute. Null on the fetch tier."
        },
        "upstream_ms": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "description": "Time talking to the target."
        },
        "extract_ms": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "description": "Extraction time; null when no extraction ran."
        },
        "total_ms": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "description": "What the caller experienced inside the handler, excluding writing the body."
        }
      }
    }
  }
}