Get Google Ads Keyword Planner Ideas

POST/v1/google-ads/keyword-ideas

Runs one feature-gated keyword-ideas collection through a server-owned, logged-in shared browser profile. Cookies, XSRF values, account context, raw private RPC vectors, DICloak identifiers, and CDP URLs stay internal. A valid completed request costs 100 Credits, including an empty result; suggestions are not charged per record. Temporary collection startup failures return HTTP 502 with google_ads_browser_unavailable and retryable=true. Failed requests release reserved Credits and are not charged.

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-ads/keyword-ideas" \
  -H "Authorization: Bearer $SPIDER_API_KEY" \
  -H 'Idempotency-Key: docs-example-01' \
  -H "Content-Type: application/json" \
  -d '{
  "keywords": [
    "<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

GoogleAdsKeywordIdeasRequest

keywords array of string required
language_id integer | null
location_ids array of integer
network integer | null: Allowed: 1, 2, null
currency_code string | null
search_volume_types array of integer
limit integer: Default: 100

Responses

200 Normalized keyword ideas and metrics.

application/json

GoogleAdsKeywordIdeasResponse

query GoogleAdsKeywordIdeasQuery required
results array of GoogleAdsKeywordIdea required
result_count integer 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

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.

GoogleAdsKeywordIdeasRequest

object

keywords array of string required
language_id integer | null
location_ids array of integer
network integer | null: Allowed: 1, 2, null
currency_code string | null
search_volume_types array of integer
limit integer: Default: 100

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "keywords"
  ],
  "properties": {
    "keywords": {
      "type": "array",
      "minItems": 1,
      "maxItems": 20,
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 256
      }
    },
    "language_id": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1
    },
    "location_ids": {
      "type": [
        "array",
        "null"
      ],
      "maxItems": 20,
      "items": {
        "type": "integer",
        "minimum": 1
      }
    },
    "network": {
      "type": [
        "integer",
        "null"
      ],
      "enum": [
        1,
        2,
        null
      ]
    },
    "currency_code": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 3,
      "maxLength": 3
    },
    "search_volume_types": {
      "type": [
        "array",
        "null"
      ],
      "maxItems": 6,
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 6
      }
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000,
      "default": 100
    }
  }
}

GoogleAdsKeywordIdeasResponse

object

query GoogleAdsKeywordIdeasQuery required
results array of GoogleAdsKeywordIdea required
result_count integer required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "query",
    "results",
    "result_count"
  ],
  "properties": {
    "query": {
      "$ref": "#/components/schemas/GoogleAdsKeywordIdeasQuery"
    },
    "results": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/GoogleAdsKeywordIdea"
      }
    },
    "result_count": {
      "type": "integer",
      "minimum": 0
    }
  }
}

GoogleAdsKeywordIdeasQuery

object

keywords array of string required
language_id integer | null
location_ids array of integer
network integer | null
currency_code string | null
search_volume_types array of integer

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "keywords"
  ],
  "properties": {
    "keywords": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "language_id": {
      "type": [
        "integer",
        "null"
      ]
    },
    "location_ids": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "integer"
      }
    },
    "network": {
      "type": [
        "integer",
        "null"
      ]
    },
    "currency_code": {
      "type": [
        "string",
        "null"
      ]
    },
    "search_volume_types": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "integer"
      }
    }
  }
}

GoogleAdsKeywordIdea

object

text string required
search_volume integer | null
competition integer | null
search_volume_min integer | null
search_volume_max integer | null
bid_min string | null
bid_max string | null
currency_code string | null
competition_index integer | null

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "text"
  ],
  "properties": {
    "text": {
      "type": "string"
    },
    "search_volume": {
      "type": [
        "integer",
        "null"
      ]
    },
    "competition": {
      "type": [
        "integer",
        "null"
      ]
    },
    "search_volume_min": {
      "type": [
        "integer",
        "null"
      ]
    },
    "search_volume_max": {
      "type": [
        "integer",
        "null"
      ]
    },
    "bid_min": {
      "type": [
        "string",
        "null"
      ]
    },
    "bid_max": {
      "type": [
        "string",
        "null"
      ]
    },
    "currency_code": {
      "type": [
        "string",
        "null"
      ]
    },
    "competition_index": {
      "type": [
        "integer",
        "null"
      ]
    }
  }
}

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