Create a Google Trends Related Queries Job

POST/v1/google-trends/related-queries

Accepts one complete Trends grain and queues asynchronous collection. Browser profile, CDP, Cookie, reCAPTCHA, and widget-token details stay internal. A valid completed job costs 20 Credits, including an empty normalized result; polling and internal retries are free. Widget acquisition and Related Search share a managed sticky proxy; bounded network retries rotate the identity after rate-limit cooldown.

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/google-trends/related-queries" \
  -H "Authorization: Bearer $SPIDER_API_KEY" \
  -H 'Idempotency-Key: docs-example-01' \
  -H "Content-Type: application/json" \
  -d '{
  "keyword": "<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

GoogleTrendsRelatedQueriesRequest

keyword string required

geo string

Default: ""

timeframe string

Default: "today 12-m"

category integer

Default: 0

property string

Allowed: "", "images", "news", "youtube", "froogle"

Default: ""

hl string

Default: "en-US"

tz integer

Default: 0

Responses

202 Google Trends job accepted.

application/json

GoogleTrendsJobResponse

job GoogleTrendsJob 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 Monthly quota was exhausted.

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.

GoogleTrendsRelatedQueriesRequest

object

keyword string required

geo string

Default: ""

timeframe string

Default: "today 12-m"

category integer

Default: 0

property string

Allowed: "", "images", "news", "youtube", "froogle"

Default: ""

hl string

Default: "en-US"

tz integer

Default: 0

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "keyword"
  ],
  "properties": {
    "keyword": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "geo": {
      "type": "string",
      "maxLength": 16,
      "default": ""
    },
    "timeframe": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "default": "today 12-m"
    },
    "category": {
      "type": "integer",
      "minimum": 0,
      "default": 0
    },
    "property": {
      "type": "string",
      "enum": [
        "",
        "images",
        "news",
        "youtube",
        "froogle"
      ],
      "default": ""
    },
    "hl": {
      "type": "string",
      "minLength": 2,
      "maxLength": 20,
      "default": "en-US"
    },
    "tz": {
      "type": "integer",
      "minimum": -840,
      "maximum": 840,
      "default": 0
    }
  }
}

GoogleTrendsJobResponse

object

job GoogleTrendsJob required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "job"
  ],
  "properties": {
    "job": {
      "$ref": "#/components/schemas/GoogleTrendsJob"
    }
  }
}

GoogleTrendsJob

object

Public-safe job state. It never includes browser, profile, CDP, Cookie, reCAPTCHA, or widget-token fields.

id string required
kind string required: Allowed: "related_queries"
status string required: Allowed: "queued", "running", "completed", "failed"
request GoogleTrendsRelatedQueriesRequest required
result GoogleTrendsRelatedQueriesResult or null
error GoogleTrendsJobError or null
attempt_count integer required
max_attempts integer required
created_at string | null (date-time)
updated_at string | null (date-time)
started_at string | null (date-time)
finished_at string | null (date-time)

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "kind",
    "status",
    "request",
    "attempt_count",
    "max_attempts"
  ],
  "description": "Public-safe job state. It never includes browser, profile, CDP, Cookie, reCAPTCHA, or widget-token fields.",
  "properties": {
    "id": {
      "type": "string"
    },
    "kind": {
      "type": "string",
      "enum": [
        "related_queries"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "running",
        "completed",
        "failed"
      ]
    },
    "request": {
      "$ref": "#/components/schemas/GoogleTrendsRelatedQueriesRequest"
    },
    "result": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/GoogleTrendsRelatedQueriesResult"
        },
        {
          "type": "null"
        }
      ]
    },
    "error": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/GoogleTrendsJobError"
        },
        {
          "type": "null"
        }
      ]
    },
    "attempt_count": {
      "type": "integer",
      "minimum": 0
    },
    "max_attempts": {
      "type": "integer",
      "minimum": 1
    },
    "created_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "updated_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "started_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "finished_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    }
  }
}

GoogleTrendsRelatedQueriesResult

object

top array of GoogleTrendsRankedQuery required
rising array of GoogleTrendsRankedQuery required
cache_hit boolean required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "top",
    "rising",
    "cache_hit"
  ],
  "properties": {
    "top": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/GoogleTrendsRankedQuery"
      }
    },
    "rising": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/GoogleTrendsRankedQuery"
      }
    },
    "cache_hit": {
      "type": "boolean"
    }
  }
}

GoogleTrendsRankedQuery

object

query string required
value number | null
formatted_value string | null
link string | null

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string"
    },
    "value": {
      "type": [
        "number",
        "null"
      ]
    },
    "formatted_value": {
      "type": [
        "string",
        "null"
      ]
    },
    "link": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}

GoogleTrendsJobError

object

code string required
message string required
retryable boolean required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "code",
    "message",
    "retryable"
  ],
  "properties": {
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "retryable": {
      "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
    }
  }
}