SpideyDataAPI Reference
OpenAPI YAMLProduct Console
API navigation SERP
FetchExtractBrowserCrawlRunsYouTubeRedditGoogle MapsWeChatBlackHatWorldGoogle TrendsGoogle AdsTwitterSimilarwebSemrushSEO APISERP
Google6
Ecosia1
Bing1
Yahoo1
DuckDuckGo1
Baidu1
Async tasks1
SERPGoogle

Enqueue a Google Organic SERP Task

POST/v1/serp/google/organic/tasks

Start an asynchronous Google organic search. Returns HTTP 202 with a task id. Poll GET /v1/serp/tasks/{task_id} for status and results; callbacks are not supported. Reserves 2 Credits on creation, captures on completion and releases on terminal failure. Polling is free. Reuse the same Idempotency-Key after a lost creation response.

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/serp/google/organic/tasks" \
  -H "Authorization: Bearer $SPIDER_API_KEY" \
  -H 'Idempotency-Key: docs-example-01' \
  -H "Content-Type: application/json" \
  -d '{
  "q": "<value>"
}'

Authentication

BearerAuth

Parameters

Idempotency-Key header ยท string
Caller-generated key, up to 128 characters, that identifies one API Market write and its billing event. Reuse the same key only when retrying the same logical request. Replays do not create another reservation or capture.

Request body required

application/json

SerpGoogleOrganicRequest

q string required
country string

Default: "US"

hl string

Default: "en"

device string

Allowed: "desktop", "mobile", "tablet"

Default: "desktop"

Responses

202 Task accepted.

application/json

SerpJobResponse

job SerpJob 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
409 Billing settlement requires reconciliation, or the idempotency key was reused for a different logical request.

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.

SerpGoogleOrganicRequest

object

q string required
country string

Default: "US"

hl string

Default: "en"

device string

Allowed: "desktop", "mobile", "tablet"

Default: "desktop"

Complete schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "q"
  ],
  "properties": {
    "q": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512
    },
    "country": {
      "type": "string",
      "minLength": 2,
      "maxLength": 8,
      "default": "US"
    },
    "hl": {
      "type": "string",
      "minLength": 2,
      "maxLength": 16,
      "default": "en"
    },
    "device": {
      "type": "string",
      "enum": [
        "desktop",
        "mobile",
        "tablet"
      ],
      "default": "desktop"
    }
  }
}

SerpJobResponse

object

job SerpJob required
Complete schema
{
  "type": "object",
  "required": [
    "job"
  ],
  "properties": {
    "job": {
      "$ref": "#/components/schemas/SerpJob"
    }
  }
}

SerpJob

object

id string required
kind string required

Allowed: "google_organic", "google_news", "google_images"

status string required

Allowed: "queued", "running", "completed", "failed"

request SerpJobRequest required
result object
attempt_count integer

Default: 0

max_attempts integer

Default: 3

created_at string (date-time)
updated_at string (date-time)
started_at string (date-time)
finished_at string (date-time)
Complete schema
{
  "type": "object",
  "required": [
    "id",
    "kind",
    "status",
    "request"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "kind": {
      "type": "string",
      "enum": [
        "google_organic",
        "google_news",
        "google_images"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "running",
        "completed",
        "failed"
      ]
    },
    "request": {
      "$ref": "#/components/schemas/SerpJobRequest"
    },
    "result": {
      "type": "object",
      "additionalProperties": true,
      "nullable": true
    },
    "error": {
      "$ref": "#/components/schemas/SerpJobError",
      "nullable": true
    },
    "attempt_count": {
      "type": "integer",
      "default": 0
    },
    "max_attempts": {
      "type": "integer",
      "default": 3
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true
    },
    "started_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true
    },
    "finished_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true
    }
  }
}

SerpJobRequest

object

q string required
country string

Default: "US"

hl string

Default: "en"

device string

Allowed: "desktop", "mobile", "tablet"

Default: "desktop"

Complete schema
{
  "type": "object",
  "required": [
    "q"
  ],
  "properties": {
    "q": {
      "type": "string"
    },
    "country": {
      "type": "string",
      "default": "US"
    },
    "hl": {
      "type": "string",
      "default": "en"
    },
    "device": {
      "type": "string",
      "enum": [
        "desktop",
        "mobile",
        "tablet"
      ],
      "default": "desktop"
    }
  }
}

SerpJobError

object

code string required
message string required
retryable boolean

Default: false

Complete schema
{
  "type": "object",
  "required": [
    "code",
    "message"
  ],
  "properties": {
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "retryable": {
      "type": "boolean",
      "default": false
    }
  }
}

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