Extract Structured Data from HTML

POST/v1/extract

Runs allowlisted Crawl4AI structured extraction against caller-supplied HTML. This endpoint does not fetch the URL, open a browser, persist artifacts, or create a run.

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/extract" \
  -H "Authorization: Bearer $SPIDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "<value>",
  "html": "<value>",
  "extraction": {
    "type": "json_css"
  }
}'

Authentication

BearerAuth

Request body required

application/json

ExtractRequest

url string (uri) required
html string required
extraction StructuredExtractionRequest required

Responses

200 Structured extraction completed.

application/json

ExtractResponse

url string (uri) required
structured StructuredExtractionResult required
usage PublicUsage required

400 Request validation failed.

application/json

PublicErrorResponse

error PublicError required

401 Missing or invalid API key.

application/json

PublicErrorResponse

error PublicError required

403 Authenticated principal cannot access this resource.

application/json

PublicErrorResponse

error PublicError required

429 Temporary rate limit.

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.

ExtractRequest

object

url string (uri) required
html string required
extraction StructuredExtractionRequest required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "url",
    "html",
    "extraction"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri"
    },
    "html": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000000
    },
    "extraction": {
      "$ref": "#/components/schemas/StructuredExtractionRequest"
    }
  }
}

StructuredExtractionRequest

object

type string required: Allowed: "json_css", "llm"
schema JsonCssExtractionSchema
raw_crawl4ai_schema object | null: Allowlisted raw Crawl4AI JsonCssExtractionStrategy schema. Only JSON schema keys for name, baseSelector, baseFields, fields, selector, source, default, scalar/list/nested field types, regex, and safe transforms are accepted. function/expression hooks are rejected.
computed_fields array of StructuredComputedField: Default: []
llm StructuredLLMExtractionOptions or null

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "type"
  ],
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "json_css",
        "llm"
      ]
    },
    "schema": {
      "$ref": "#/components/schemas/JsonCssExtractionSchema"
    },
    "raw_crawl4ai_schema": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": true,
      "description": "Allowlisted raw Crawl4AI JsonCssExtractionStrategy schema. Only JSON schema keys for name, baseSelector, baseFields, fields, selector, source, default, scalar/list/nested field types, regex, and safe transforms are accepted. function/expression hooks are rejected.\n"
    },
    "computed_fields": {
      "type": "array",
      "maxItems": 100,
      "default": [],
      "items": {
        "$ref": "#/components/schemas/StructuredComputedField"
      }
    },
    "llm": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredLLMExtractionOptions"
        },
        {
          "type": "null"
        }
      ]
    }
  }
}

JsonCssExtractionSchema

object

name string | null
base_selector string required
fields array of StructuredExtractionField required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "base_selector",
    "fields"
  ],
  "properties": {
    "name": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 128
    },
    "base_selector": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024
    },
    "fields": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "items": {
        "$ref": "#/components/schemas/StructuredExtractionField"
      }
    }
  }
}

StructuredExtractionField

object

name string required
selector string | null
type string required: Allowed: "text", "html", "attribute", "regex", "nested", "list", "nested_list"
attribute string | null
pattern string | null
group integer | null
transform string | null: Allowed: "strip", "lowercase", "uppercase"
fields array of StructuredExtractionField or null

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "name",
    "type"
  ],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "selector": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 1024
    },
    "type": {
      "type": "string",
      "enum": [
        "text",
        "html",
        "attribute",
        "regex",
        "nested",
        "list",
        "nested_list"
      ]
    },
    "attribute": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 128
    },
    "pattern": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 1024
    },
    "group": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "transform": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "strip",
        "lowercase",
        "uppercase"
      ]
    },
    "fields": {
      "anyOf": [
        {
          "type": "array",
          "minItems": 1,
          "maxItems": 100,
          "items": {
            "$ref": "#/components/schemas/StructuredExtractionField"
          }
        },
        {
          "type": "null"
        }
      ]
    }
  }
}

StructuredComputedField

object

name string required

operation string required

Allowed: "template", "join", "first_non_empty"

Default: "template"

sources array of string

Default: []

template string | null

separator string

Default: ""

default string | null

transform string | null

Allowed: "strip", "lowercase", "uppercase"

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "name",
    "operation"
  ],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "operation": {
      "type": "string",
      "enum": [
        "template",
        "join",
        "first_non_empty"
      ],
      "default": "template"
    },
    "sources": {
      "type": "array",
      "maxItems": 20,
      "default": [],
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z_][A-Za-z0-9_]*(?:\\.[A-Za-z_][A-Za-z0-9_]*|\\[[0-9]{1,4}\\])*$"
      }
    },
    "template": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 2048
    },
    "separator": {
      "type": "string",
      "maxLength": 128,
      "default": ""
    },
    "default": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 2048
    },
    "transform": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "strip",
        "lowercase",
        "uppercase"
      ]
    }
  }
}

StructuredLLMExtractionOptions

object

name string | null

instruction string

schema object | null

JSON Schema-style target shape sent to the server-configured LLM.

extraction_type string

Allowed: "schema", "block"

Default: "schema"

input_format string

Allowed: "html", "markdown", "text", "fit_html"

Default: "html"

chunk_token_threshold integer

Default: 4096

overlap_rate number

Default: 0.1

apply_chunking boolean

Default: true

force_json_response boolean

Default: true

temperature number | null

max_tokens integer | null

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "name": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 128
    },
    "instruction": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
    },
    "schema": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": true,
      "description": "JSON Schema-style target shape sent to the server-configured LLM."
    },
    "extraction_type": {
      "type": "string",
      "enum": [
        "schema",
        "block"
      ],
      "default": "schema"
    },
    "input_format": {
      "type": "string",
      "enum": [
        "html",
        "markdown",
        "text",
        "fit_html"
      ],
      "default": "html"
    },
    "chunk_token_threshold": {
      "type": "integer",
      "minimum": 128,
      "maximum": 200000,
      "default": 4096
    },
    "overlap_rate": {
      "type": "number",
      "minimum": 0,
      "maximum": 0.5,
      "default": 0.1
    },
    "apply_chunking": {
      "type": "boolean",
      "default": true
    },
    "force_json_response": {
      "type": "boolean",
      "default": true
    },
    "temperature": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0,
      "maximum": 2
    },
    "max_tokens": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "maximum": 128000
    }
  }
}

ExtractResponse

object

url string (uri) required
structured StructuredExtractionResult required
usage PublicUsage required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "url",
    "structured",
    "usage"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri"
    },
    "structured": {
      "$ref": "#/components/schemas/StructuredExtractionResult"
    },
    "usage": {
      "$ref": "#/components/schemas/PublicUsage"
    }
  }
}

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
usage StructuredExtractionUsage or null
error StructuredExtractionError or null

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"
    }
  }
}

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"
    }
  }
}

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
    }
  }
}