SpideyDataAPI Reference
OpenAPI YAMLProduct Console
API navigation Fetch
FetchExtractBrowserCrawlRunsYouTubeRedditGoogle MapsWeChatBlackHatWorldGoogle TrendsGoogle AdsTwitterSimilarwebSemrushSEO APISERP
Endpoints1
FetchEndpoints

Fetch a Web Page by URL

POST/v1/fetch

Fetches one URL through required managed proxy egress and returns a public page result. Bounded identity refresh never silently falls back to the server exit.

On this page

Request example

Replace placeholders with your values. Use your Team API key for authenticated requests.

API base https://kieapi.com
curl -X POST "https://kieapi.com/v1/fetch" \
  -H "Authorization: Bearer $SPIDER_API_KEY" \
  -H 'Idempotency-Key: docs-example-01' \
  -H "Content-Type: application/json" \
  -d '{
  "url": "<value>"
}'

Authentication

BearerAuth

Parameters

Idempotency-Key header ยท string
Caller-generated key for replay-safe creation. Reusing the key with the same request body returns the stored response; reusing it with a different body or while the original request is in progress returns 409.

Request body required

application/json

FetchRequest

url string (uri) required

Responses

200 Fetch completed.

application/json

PageRunResponse

run PublicRun required
result PublicPageResult required
400 Request validation failed.

application/json

PublicErrorResponse

error PublicError required
401 Missing or invalid API key.

application/json

PublicErrorResponse

error PublicError required
402 The Team does not have enough available Credits for the maximum reservation.

application/json

PublicErrorResponse

error PublicError required
403 Authenticated principal cannot access this resource.

application/json

PublicErrorResponse

error PublicError required
408 Work timed out.

application/json

PublicErrorResponse

error PublicError required
409 The idempotency key is already in progress or belongs to a different request body. In-progress Browser Session creation returns Retry-After.

application/json

PublicErrorResponse

error PublicError required
429 Monthly quota was exhausted.

application/json

PublicErrorResponse

error PublicError required
502 Upstream fetch or network failure.

application/json

PublicErrorResponse

error PublicError required
503 Required runtime service is unavailable.

application/json

PublicErrorResponse

error PublicError required

Schemas

Field definitions and complete validation rules for this API. Follow a type link to its definition.

FetchRequest

object

url string (uri) required
Complete schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "url"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri"
    }
  }
}

PageRunResponse

object

run PublicRun required
result PublicPageResult required
Complete schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "run",
    "result"
  ],
  "properties": {
    "run": {
      "$ref": "#/components/schemas/PublicRun"
    },
    "result": {
      "$ref": "#/components/schemas/PublicPageResult"
    }
  }
}

PublicRun

object

id string required
type PublicRunType required
status PublicStatus required
created_at string | null (date-time)
completed_at string | null (date-time)
cost_units integer | null
quota PublicQuotaReservation required
Complete schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "type",
    "status",
    "quota"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "type": {
      "$ref": "#/components/schemas/PublicRunType"
    },
    "status": {
      "$ref": "#/components/schemas/PublicStatus"
    },
    "created_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "completed_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "cost_units": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "quota": {
      "$ref": "#/components/schemas/PublicQuotaReservation"
    }
  }
}

PublicRunType

string

Complete schema
{
  "type": "string",
  "enum": [
    "fetch",
    "browser_scrape",
    "crawl"
  ]
}

PublicStatus

string

Complete schema
{
  "type": "string",
  "enum": [
    "queued",
    "running",
    "paused",
    "completed",
    "failed",
    "low_quality",
    "budget_exhausted",
    "expired"
  ]
}

PublicQuotaReservation

object

resource string required

Allowed: "scrape", "crawl"

quantity_reserved integer required
Complete schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "resource",
    "quantity_reserved"
  ],
  "properties": {
    "resource": {
      "type": "string",
      "enum": [
        "scrape",
        "crawl"
      ]
    },
    "quantity_reserved": {
      "type": "integer",
      "minimum": 1
    }
  }
}

PublicPageResult

object

url string (uri) required
final_url string | null (uri)
status PublicStatus required
title string | null
content PublicContent required
structured StructuredExtractionResult or null
artifacts array of PublicArtifactLink required
audit PublicAudit required
usage PublicUsage required
Complete schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "url",
    "status",
    "content",
    "artifacts",
    "audit",
    "usage"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri"
    },
    "final_url": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri"
    },
    "status": {
      "$ref": "#/components/schemas/PublicStatus"
    },
    "title": {
      "type": [
        "string",
        "null"
      ]
    },
    "content": {
      "$ref": "#/components/schemas/PublicContent"
    },
    "structured": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredExtractionResult"
        },
        {
          "type": "null"
        }
      ]
    },
    "artifacts": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/PublicArtifactLink"
      }
    },
    "audit": {
      "$ref": "#/components/schemas/PublicAudit"
    },
    "usage": {
      "$ref": "#/components/schemas/PublicUsage"
    },
    "diagnostics": {
      "$ref": "#/components/schemas/PublicPageDiagnostics"
    }
  }
}

PublicContent

object

markdown string | null
html string | null
metadata object
links array of string (uri)
Complete schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "markdown": {
      "type": [
        "string",
        "null"
      ]
    },
    "html": {
      "type": [
        "string",
        "null"
      ]
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "links": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      }
    }
  }
}

StructuredExtractionResult

object

type string required

Allowed: "json_css"

source string required

Allowed: "crawl4ai"

schema_name string | null
items array of object required
item_count integer required
Complete schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "type",
    "source",
    "items",
    "item_count"
  ],
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "json_css"
      ]
    },
    "source": {
      "type": "string",
      "enum": [
        "crawl4ai"
      ]
    },
    "schema_name": {
      "type": [
        "string",
        "null"
      ]
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "item_count": {
      "type": "integer",
      "minimum": 0
    },
    "usage": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredExtractionUsage"
        },
        {
          "type": "null"
        }
      ]
    },
    "error": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredExtractionError"
        },
        {
          "type": "null"
        }
      ]
    }
  }
}

StructuredExtractionUsage

object

provider string required

Allowed: "server_configured"

prompt_tokens integer | null
completion_tokens integer | null
total_tokens integer | null
Complete schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "provider"
  ],
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "server_configured"
      ]
    },
    "prompt_tokens": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "completion_tokens": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "total_tokens": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    }
  }
}

StructuredExtractionError

object

code string required

Allowed: "structured_extraction_failed"

message string required
Complete schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "code",
    "message"
  ],
  "properties": {
    "code": {
      "type": "string",
      "enum": [
        "structured_extraction_failed"
      ]
    },
    "message": {
      "type": "string"
    }
  }
}

ArtifactKey

string

Complete schema
{
  "type": "string",
  "enum": [
    "markdown",
    "html",
    "raw_html",
    "screenshot_png",
    "recording_mp4",
    "recording_webm",
    "structured_json"
  ]
}

PublicAudit

object

engine_winner string | null
engines_attempted array of string
fallback_reasons array of string
fallback_events array of string
retry_stats object
quality_score number | null
block_reason string | null
Sanitized execution stop category. Known response guard outcomes include body_size_limit, redirect_limit, and blocked_target; all are non-retryable. blocked_target prevents Browser fallback. body_size_limit uses the current server runtime default of 10 MiB (10485760 bytes), which is not caller-configurable in public v1. The response body and internal transport error text are never exposed by this field.
Complete schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "engine_winner": {
      "type": [
        "string",
        "null"
      ]
    },
    "engines_attempted": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "fallback_reasons": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "fallback_events": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "retry_stats": {
      "type": "object",
      "additionalProperties": true
    },
    "quality_score": {
      "type": [
        "number",
        "null"
      ]
    },
    "block_reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Sanitized execution stop category. Known response guard outcomes include body_size_limit, redirect_limit, and blocked_target; all are non-retryable. blocked_target prevents Browser fallback. body_size_limit uses the current server runtime default of 10 MiB (10485760 bytes), which is not caller-configurable in public v1. The response body and internal transport error text are never exposed by this field."
    }
  }
}

PublicUsage

object

cost_units integer | null
budget_exhausted boolean
Complete schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "cost_units": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "budget_exhausted": {
      "type": "boolean"
    }
  }
}

PublicPageDiagnostics

object

Public page diagnostics are sanitized aggregate fields for page-level extraction, browser debug, browser failure, and quality explainability. They do not expose raw selectors, raw debug events, profile data, proxy data, CDP URLs, DICloak/provider internals, or raw audit attempt rows.

Complete schema
{
  "type": "object",
  "additionalProperties": false,
  "description": "Public page diagnostics are sanitized aggregate fields for page-level extraction, browser debug, browser failure, and quality explainability. They do not expose raw selectors, raw debug events, profile data, proxy data, CDP URLs, DICloak/provider internals, or raw audit attempt rows.\n",
  "properties": {
    "adaptive_extraction": {
      "$ref": "#/components/schemas/PublicAdaptiveExtractionDiagnostics"
    },
    "browser_debug": {
      "$ref": "#/components/schemas/PublicBrowserDebugDiagnostics"
    },
    "browser_failure": {
      "$ref": "#/components/schemas/PublicBrowserFailureDiagnostics"
    },
    "content_quality": {
      "$ref": "#/components/schemas/PublicContentQualityDiagnostics"
    }
  }
}

PublicAdaptiveExtractionDiagnostics

object

Public sanitized aggregate for adaptive extraction diagnostics. This summarizes selector-memory behavior without exposing raw selectors, selector memory records, or provider internals.

enabled boolean

Default: false

used boolean

Default: false

action string

Allowed: "disabled", "none", "saved", "reused", "relocated", "skipped_low_quality", "no_candidate"

Default: "disabled"

confidence number | null
Complete schema
{
  "type": "object",
  "additionalProperties": false,
  "description": "Public sanitized aggregate for adaptive extraction diagnostics. This summarizes selector-memory behavior without exposing raw selectors, selector memory records, or provider internals.\n",
  "properties": {
    "enabled": {
      "type": "boolean",
      "default": false
    },
    "used": {
      "type": "boolean",
      "default": false
    },
    "action": {
      "type": "string",
      "enum": [
        "disabled",
        "none",
        "saved",
        "reused",
        "relocated",
        "skipped_low_quality",
        "no_candidate"
      ],
      "default": "disabled"
    },
    "confidence": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0,
      "maximum": 1
    }
  }
}

PublicBrowserDebugDiagnostics

object

Public sanitized browser debug capture summary. It exposes only whether browser debug capture produced a summary plus aggregate network and console counts. Raw URLs, headers, cookies, bearer tokens, proxy credentials, CDP URLs, response bodies, status/resource/console-level buckets, and raw debug events are not public fields.

enabled boolean

Default: false

network_event_count integer

Default: 0

console_message_count integer

Default: 0

Complete schema
{
  "type": "object",
  "additionalProperties": false,
  "description": "Public sanitized browser debug capture summary. It exposes only whether browser debug capture produced a summary plus aggregate network and console counts. Raw URLs, headers, cookies, bearer tokens, proxy credentials, CDP URLs, response bodies, status/resource/console-level buckets, and raw debug events are not public fields.\n",
  "properties": {
    "enabled": {
      "type": "boolean",
      "default": false
    },
    "network_event_count": {
      "type": "integer",
      "minimum": 0,
      "default": 0
    },
    "console_message_count": {
      "type": "integer",
      "minimum": 0,
      "default": 0
    }
  }
}

PublicBrowserFailureDiagnostics

object

Public sanitized browser failure summary. It exposes only stable failure category, stage, attempt count, lease-acquired state, and an allowlisted error code. Raw URLs, proxy credentials, profile ids, identity ids, CDP URLs, provider payloads, and raw audit rows are not public fields.

present boolean

Default: false

category string

Allowed: "none", "capacity", "network_tunnel_failed", "network_error", "timeout", "anti_bot_challenge", "content_quality", "budget_exhausted", "render_error", "other"

Default: "none"

stage string

Allowed: "none", "capacity", "browser_open", "navigation", "render", "quality", "unknown"

Default: "none"

attempt_count integer

Default: 0

browser_lease_acquired boolean | null

Default: null

error_code string | null

Default: null

Complete schema
{
  "type": "object",
  "additionalProperties": false,
  "description": "Public sanitized browser failure summary. It exposes only stable failure category, stage, attempt count, lease-acquired state, and an allowlisted error code. Raw URLs, proxy credentials, profile ids, identity ids, CDP URLs, provider payloads, and raw audit rows are not public fields.\n",
  "properties": {
    "present": {
      "type": "boolean",
      "default": false
    },
    "category": {
      "type": "string",
      "enum": [
        "none",
        "capacity",
        "network_tunnel_failed",
        "network_error",
        "timeout",
        "anti_bot_challenge",
        "content_quality",
        "budget_exhausted",
        "render_error",
        "other"
      ],
      "default": "none"
    },
    "stage": {
      "type": "string",
      "enum": [
        "none",
        "capacity",
        "browser_open",
        "navigation",
        "render",
        "quality",
        "unknown"
      ],
      "default": "none"
    },
    "attempt_count": {
      "type": "integer",
      "minimum": 0,
      "default": 0
    },
    "browser_lease_acquired": {
      "type": [
        "boolean",
        "null"
      ],
      "default": null
    },
    "error_code": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 96,
      "default": null
    }
  }
}

PublicContentQualityDiagnostics

object

Public sanitized aggregate for content quality diagnostics. The score is normalized to 0..1 and does not expose raw extractor internals, provider internals, or audit rows.

score number | null
confidence string

Allowed: "unknown", "low", "medium", "high"

Default: "unknown"

Complete schema
{
  "type": "object",
  "additionalProperties": false,
  "description": "Public sanitized aggregate for content quality diagnostics. The score is normalized to 0..1 and does not expose raw extractor internals, provider internals, or audit rows.\n",
  "properties": {
    "score": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0,
      "maximum": 1
    },
    "confidence": {
      "type": "string",
      "enum": [
        "unknown",
        "low",
        "medium",
        "high"
      ],
      "default": "unknown"
    }
  }
}

PublicErrorResponse

object

error PublicError required
Complete schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "$ref": "#/components/schemas/PublicError"
    }
  }
}

PublicError

object

code string required

Allowed: "seoapi_price_pending", "seoapi_unavailable", "seoapi_busy", "seoapi_not_found", "seoapi_rate_limited", "seoapi_budget_exceeded", "seoapi_idempotency_conflict", "seoapi_insufficient_credits", "seoapi_admission_failed", "seoapi_execution_interrupted", "seoapi_delivery_unknown", "seoapi_response_invalid", "seoapi_model_unsupported", "seoapi_model_options_invalid", "seoapi_provider_rejected", "seo_price_pending", "seo_provider_blocked", "seo_local_rate_limited", "seo_fallback_unavailable", "seo_fallback_budget_exceeded", "seo_pagination_expired", "seo_delivery_uncertain", "seo_auth_required", "seo_initialization_required", "seo_permission_denied", "seo_verification_required", "seo_rate_limited", "seo_upstream_unavailable", "seo_transport_failed", "seo_invalid_response", "seo_rpc_error", "seo_period_unavailable", "seo_account_unavailable", "seo_session_busy", "seo_configuration_required", "validation_error", "invalid_request", "unsupported_feature", "authentication_required", "permission_denied", "not_found", "run_not_found", "crawl_not_found", "artifact_not_found", "session_not_found", "profile_not_found", "profile_in_use", "profile_not_ready", "profile_not_cloneable", "profile_limit_reached", "profile_proxy_conflict", "proxy_not_found", "proxy_unavailable", "invalid_session_options", "invalid_query_options", "invalid_cursor", "idempotency_key_required", "browser_session_limit_reached", "browser_capacity_exhausted", "browser_start_timeout", "browser_runtime_unavailable", "session_not_active", "controller_already_connected", "browser_relay_unavailable", "precondition_required", "precondition_failed", "timeout", "run_not_ready", "artifact_expired", "quota_exceeded", "insufficient_credits", "billing_reconciliation_required", "rate_limited", "fetch_failed", "render_failed", "maps_rate_limited", "maps_challenge", "maps_schema_changed", "maps_invalid_response", "maps_transport_failed", "maps_page_budget_exhausted", "google_trends_rate_limited", "google_trends_challenge", "google_trends_explore_failed", "google_trends_widget_missing", "google_trends_related_failed", "google_trends_invalid_response", "google_trends_transport_failed", "google_trends_collection_failed", "google_ads_account_context_missing", "google_ads_batch_failed", "google_ads_browser_context_missing", "google_ads_browser_unavailable", "google_ads_collection_failed", "google_ads_page_failed", "google_ads_protocol_drift", "google_ads_rate_limited", "google_ads_timeout", "twitter_provider_unavailable", "twitter_provider_rejected", "twitter_submission_unknown", "wechat_transport_failed", "wechat_rate_limited", "wechat_invalid_response", "wechat_redirect_rejected", "wechat_verification_required", "wechat_parse_failed", "blackhatworld_search_failed", "blackhatworld_no_results", "reddit_read_failed", "idempotency_conflict", "idempotency_in_progress", "service_unavailable", "internal_error"

message string required
type string required

Allowed: "auth", "validation", "quota", "rate_limit", "not_found", "execution", "conflict", "internal"

retryable boolean required
request_id string | null
details object
Complete schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "code",
    "message",
    "type",
    "retryable"
  ],
  "properties": {
    "code": {
      "type": "string",
      "enum": [
        "seoapi_price_pending",
        "seoapi_unavailable",
        "seoapi_busy",
        "seoapi_not_found",
        "seoapi_rate_limited",
        "seoapi_budget_exceeded",
        "seoapi_idempotency_conflict",
        "seoapi_insufficient_credits",
        "seoapi_admission_failed",
        "seoapi_execution_interrupted",
        "seoapi_delivery_unknown",
        "seoapi_response_invalid",
        "seoapi_model_unsupported",
        "seoapi_model_options_invalid",
        "seoapi_provider_rejected",
        "seo_price_pending",
        "seo_provider_blocked",
        "seo_local_rate_limited",
        "seo_fallback_unavailable",
        "seo_fallback_budget_exceeded",
        "seo_pagination_expired",
        "seo_delivery_uncertain",
        "seo_auth_required",
        "seo_initialization_required",
        "seo_permission_denied",
        "seo_verification_required",
        "seo_rate_limited",
        "seo_upstream_unavailable",
        "seo_transport_failed",
        "seo_invalid_response",
        "seo_rpc_error",
        "seo_period_unavailable",
        "seo_account_unavailable",
        "seo_session_busy",
        "seo_configuration_required",
        "validation_error",
        "invalid_request",
        "unsupported_feature",
        "authentication_required",
        "permission_denied",
        "not_found",
        "run_not_found",
        "crawl_not_found",
        "artifact_not_found",
        "session_not_found",
        "profile_not_found",
        "profile_in_use",
        "profile_not_ready",
        "profile_not_cloneable",
        "profile_limit_reached",
        "profile_proxy_conflict",
        "proxy_not_found",
        "proxy_unavailable",
        "invalid_session_options",
        "invalid_query_options",
        "invalid_cursor",
        "idempotency_key_required",
        "browser_session_limit_reached",
        "browser_capacity_exhausted",
        "browser_start_timeout",
        "browser_runtime_unavailable",
        "session_not_active",
        "controller_already_connected",
        "browser_relay_unavailable",
        "precondition_required",
        "precondition_failed",
        "timeout",
        "run_not_ready",
        "artifact_expired",
        "quota_exceeded",
        "insufficient_credits",
        "billing_reconciliation_required",
        "rate_limited",
        "fetch_failed",
        "render_failed",
        "maps_rate_limited",
        "maps_challenge",
        "maps_schema_changed",
        "maps_invalid_response",
        "maps_transport_failed",
        "maps_page_budget_exhausted",
        "google_trends_rate_limited",
        "google_trends_challenge",
        "google_trends_explore_failed",
        "google_trends_widget_missing",
        "google_trends_related_failed",
        "google_trends_invalid_response",
        "google_trends_transport_failed",
        "google_trends_collection_failed",
        "google_ads_account_context_missing",
        "google_ads_batch_failed",
        "google_ads_browser_context_missing",
        "google_ads_browser_unavailable",
        "google_ads_collection_failed",
        "google_ads_page_failed",
        "google_ads_protocol_drift",
        "google_ads_rate_limited",
        "google_ads_timeout",
        "twitter_provider_unavailable",
        "twitter_provider_rejected",
        "twitter_submission_unknown",
        "wechat_transport_failed",
        "wechat_rate_limited",
        "wechat_invalid_response",
        "wechat_redirect_rejected",
        "wechat_verification_required",
        "wechat_parse_failed",
        "blackhatworld_search_failed",
        "blackhatworld_no_results",
        "reddit_read_failed",
        "idempotency_conflict",
        "idempotency_in_progress",
        "service_unavailable",
        "internal_error"
      ]
    },
    "message": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": [
        "auth",
        "validation",
        "quota",
        "rate_limit",
        "not_found",
        "execution",
        "conflict",
        "internal"
      ]
    },
    "retryable": {
      "type": "boolean"
    },
    "request_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "details": {
      "type": "object",
      "additionalProperties": true
    }
  }
}