Get Organic Search Positions with Semrush

POST/v1/semrush/organic-positions

Local account admission returns HTTP 429 seo_local_rate_limited with Retry-After. Before any business HTTP attempt, retryable is true and the same key/body can resume after cooldown. After any business attempt (including redirects or earlier children), retryable is false and the saved delivery stays terminal. Retry-After describes account cooldown, not permission to replay. Previously settled failures require a new key for a deliberate new attempt after cooldown. Operator or admin role required (403 permission_denied). Same-key saved delivery replays bypass quota; retryable pre-execution seo_session_busy allows same-key retry. After 402 insufficient_credits, top up and retry the same key. Pending settlement recovers without upstream replay. Platform-provided account; complete module delivery required for Credits capture. Partial delivery is not charged. No upstream credentials accepted. Managed-account HTTP initialization runs before business execution; readiness requires validated business data. A recognized stale Semrush login rejection permits one normal managed-account login and one bounded read replay, sharing the existing authentication recovery budget. Production availability and charging require separate verification. Catalog-disabled nodes, tool HTTP 5xx and connection failures permit at most two alternate eligible nodes within one request-wide recovery budget (60 seconds by default). A disabled node returns seo_upstream_unavailable, not seo_permission_denied; subscription and tier checks still apply. Background maintenance permits at most one HTTP attempt per shared account per Asia/Shanghai day, only during 00:00-00:05, using an existing session for a free Semrush Keyword Overview check. It skips missed windows and expired context, with no background login, renewal, node scan, retries or redirect follow-up. Provider cooldowns take precedence. Customer requests recover expired sessions on demand without waiting for background checks, with at most one token refresh and one normal login, tool initialization, then one bounded replay of the original read. A successful business result immediately clears an ordinary authentication hold. Only verified provider bans retain the three-success observation requirement. A rejected login requires operator correction; repeated business authentication failure backs off without permanently disabling the account. Login or another task succeeding does not establish this task's health. Failed recovery emits an operator incident; customers are not charged for probes or incomplete delivery. Failed nodes cool for 300 seconds across workers; successful nodes stay selected. Permission, verification, quota, generic HTML, RPC and schema errors do not trigger node rotation. In-flight read recovery uses the original reservation and captures only once after full validation; stored failed, partial or uncertain deliveries are never re-executed. Account HTTP requests share persisted budgets, defaulting to 10/minute and 120/hour; operators can adjust them in Admin without restart. Verified temporary bans return seo_provider_blocked and stop all account traffic until a leased business probe after the provider deadline plus 60 seconds. Recovery needs three successes over ten minutes. Organic positions and keyword overview accept source_policy auto (default) or primary_only. Automatic DataForSEO backup returns tool dataforseo and source metadata. Organic positions allow_latest_fallback defaults true; false keeps strict historical dates. Backup dates do not satisfy the requested historical date. Backup supports listed country/language defaults, USD and no device-specific filtering; mobile and non-USD requests do not fallback. Snapshots last six hours; start at page one, keep source pinned, and page at most 1000 cached backup rows. total is provider total, available_rows is retained count. Expired/out-of-range pages return seo_pagination_expired. Matching stale snapshots up to 24 hours old are explicitly marked. Missing values remain null. Idempotency and complete-page Credits pricing are unchanged.

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/semrush/organic-positions" \
  -H "Authorization: Bearer $SPIDER_API_KEY" \
  -H 'Idempotency-Key: docs-example-01' \
  -H "Content-Type: application/json" \
  -d '{
  "domain": "<value>",
  "date": "<value>"
}'

Authentication

BearerAuth

Parameters

Idempotency-Key header · string required

Request body required

application/json

SemrushPositionsInput

domain string required

source_policy string

Allowed: "auto", "primary_only"

Default: "auto"

allow_latest_fallback boolean

Default: true

database string

Default: "us"

device string

Allowed: "desktop", "mobile"

Default: "desktop"

date string (date) required

page integer

Default: 1

page_size integer

Default: 100

Responses

200 Successful Response

application/json

SemrushOrganicPositionsResponse

Illustrative complete response (synthetic data; shadow billing, not a live result) example

{
  "tool": "semrush",
  "task": "organic-positions",
  "status": "success",
  "query": {
    "domain": "example.com",
    "source_policy": "auto",
    "allow_latest_fallback": true,
    "database": "us",
    "device": "desktop",
    "date": "2026-09-17",
    "page": 1,
    "page_size": 100
  },
  "modules": {
    "positions": {
      "status": "success",
      "data": {
        "rows": [
          {
            "phrase": "test",
            "position": 1,
            "traffic": 20,
            "trafficPercent": 0.5,
            "volume": 30,
            "url": "https://example.com/"
          }
        ],
        "total": 1,
        "page": 1,
        "page_size": 100,
        "database": "us"
      },
      "error_code": null
    }
  },
  "limitations": [
    "Historical pagination evidence covers pages 1–3; later pages are not verified."
  ],
  "billing": {
    "status": "shadow_captured",
    "credits": 20,
    "price_book_version": "seo-modules-2026-09-30-v1-20"
  }
}

400 ValidationError

application/json

PublicErrorResponse

error PublicError required

401 AuthenticationRequired

application/json

PublicErrorResponse

error PublicError required

402 InsufficientCredits

application/json

PublicErrorResponse

error PublicError required

403 PermissionDenied

application/json

PublicErrorResponse

error PublicError required

409 BillingConflict

application/json

PublicErrorResponse

error PublicError required

429 RateLimitExceeded

application/json

PublicErrorResponse

error PublicError required

502 ExecutionFailed

application/json

PublicErrorResponse

error PublicError required

503 ServiceUnavailable

application/json

PublicErrorResponse

error PublicError required

Schemas

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

SemrushPositionsInput

object

domain string required

source_policy string

Allowed: "auto", "primary_only"

Default: "auto"

allow_latest_fallback boolean

Default: true

database string

Default: "us"

device string

Allowed: "desktop", "mobile"

Default: "desktop"

date string (date) required

page integer

Default: 1

page_size integer

Default: 100

Complete schema

{
  "additionalProperties": false,
  "properties": {
    "domain": {
      "maxLength": 253,
      "minLength": 3,
      "title": "Domain",
      "type": "string"
    },
    "source_policy": {
      "default": "auto",
      "enum": [
        "auto",
        "primary_only"
      ],
      "title": "Source Policy",
      "type": "string"
    },
    "allow_latest_fallback": {
      "default": true,
      "title": "Allow Latest Fallback",
      "type": "boolean"
    },
    "database": {
      "default": "us",
      "pattern": "^[a-z]{2}$",
      "title": "Database",
      "type": "string"
    },
    "device": {
      "default": "desktop",
      "enum": [
        "desktop",
        "mobile"
      ],
      "title": "Device",
      "type": "string"
    },
    "date": {
      "format": "date",
      "title": "Date",
      "type": "string"
    },
    "page": {
      "default": 1,
      "maximum": 100,
      "minimum": 1,
      "title": "Page",
      "type": "integer"
    },
    "page_size": {
      "default": 100,
      "maximum": 100,
      "minimum": 1,
      "title": "Page Size",
      "type": "integer"
    }
  },
  "required": [
    "domain",
    "date"
  ],
  "title": "SemrushPositionsInput",
  "type": "object"
}

SemrushOrganicPositionsResponse

SeoResponse and object

Complete schema

{
  "allOf": [
    {
      "$ref": "#/components/schemas/SeoResponse"
    },
    {
      "type": "object",
      "properties": {
        "tool": {
          "type": "string",
          "description": "Server-selected tool identity; not a request parameter.",
          "enum": [
            "semrush",
            "dataforseo"
          ]
        },
        "task": {
          "type": "string",
          "const": "organic-positions"
        },
        "query": {
          "$ref": "#/components/schemas/SemrushPositionsInput"
        },
        "modules": {
          "type": "object",
          "properties": {
            "positions": {
              "$ref": "#/components/schemas/SeoModuleResult"
            }
          },
          "additionalProperties": false
        }
      }
    }
  ]
}

SeoResponse

object

tool string required: Allowed: "similarweb", "semrush", "dataforseo"
task string required
status string required: Allowed: "success", "partial", "failed"
query object required
modules object required
limitations array of string
source SeoSource or null: Default: null
billing SeoBillingSummary

Complete schema

{
  "properties": {
    "tool": {
      "enum": [
        "similarweb",
        "semrush",
        "dataforseo"
      ],
      "title": "Tool",
      "type": "string"
    },
    "task": {
      "title": "Task",
      "type": "string"
    },
    "status": {
      "enum": [
        "success",
        "partial",
        "failed"
      ],
      "title": "Status",
      "type": "string"
    },
    "query": {
      "additionalProperties": true,
      "title": "Query",
      "type": "object"
    },
    "modules": {
      "additionalProperties": {
        "$ref": "#/components/schemas/SeoModuleResult"
      },
      "title": "Modules",
      "type": "object"
    },
    "limitations": {
      "items": {
        "type": "string"
      },
      "title": "Limitations",
      "type": "array"
    },
    "source": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/SeoSource"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "billing": {
      "$ref": "#/components/schemas/SeoBillingSummary"
    }
  },
  "required": [
    "tool",
    "task",
    "status",
    "query",
    "modules"
  ],
  "title": "SeoResponse",
  "type": "object"
}

SeoModuleResult

object

status string required: Allowed: "success", "failed", "not_run"
data object or array of object or null
error_code string or null

Complete schema

{
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success",
        "failed",
        "not_run"
      ],
      "title": "Status"
    },
    "data": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "items": {},
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Data"
    },
    "error_code": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Error Code"
    }
  },
  "type": "object",
  "required": [
    "status"
  ],
  "title": "SeoModuleResult"
}

SeoSource

object

provider string required: Allowed: "semrush", "dataforseo"
requested_tool string: Default: "semrush"
retrieved_at number or null: Default: null
data_date string or null: Default: null
data_date_from string or null: Default: null
requested_date_satisfied boolean or null: Default: null
cache_hit boolean: Default: false
stale boolean: Default: false
fallback_reason string or null: Default: null
location_code integer or null: Default: null
language_code string or null: Default: null
currency string or null: Default: null
device string or null: Default: null
snapshot_kind string or null: Default: null

Complete schema

{
  "properties": {
    "provider": {
      "enum": [
        "semrush",
        "dataforseo"
      ],
      "title": "Provider",
      "type": "string"
    },
    "requested_tool": {
      "const": "semrush",
      "default": "semrush",
      "title": "Requested Tool",
      "type": "string"
    },
    "retrieved_at": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Retrieved At"
    },
    "data_date": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Data Date"
    },
    "data_date_from": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Data Date From"
    },
    "requested_date_satisfied": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Requested Date Satisfied"
    },
    "cache_hit": {
      "default": false,
      "title": "Cache Hit",
      "type": "boolean"
    },
    "stale": {
      "default": false,
      "title": "Stale",
      "type": "boolean"
    },
    "fallback_reason": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Fallback Reason"
    },
    "location_code": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Location Code"
    },
    "language_code": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Language Code"
    },
    "currency": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Currency"
    },
    "device": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Device"
    },
    "snapshot_kind": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Snapshot Kind"
    }
  },
  "required": [
    "provider"
  ],
  "title": "SeoSource",
  "type": "object"
}

SeoBillingSummary

object

status string required
credits integer: Default: 0
price_book_version string or null

Complete schema

{
  "properties": {
    "status": {
      "type": "string",
      "title": "Status"
    },
    "credits": {
      "type": "integer",
      "title": "Credits",
      "default": 0
    },
    "price_book_version": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Price Book Version"
    }
  },
  "type": "object",
  "required": [
    "status"
  ],
  "title": "SeoBillingSummary"
}

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