Get Website Referral Data with Similarweb

POST/v1/similarweb/referrals

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 Similarweb login rejection permits one normal managed-account login and one bounded read replay, sharing the existing authentication recovery budget. A persistent rejection returns a safe authentication error; generic HTML, permission and quota errors do not trigger this recovery. 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. Verified Similarweb node API quota exhaustion cools only that node for Retry-After and permits at most four alternate eligible nodes within the same time and traffic budget. Subscription/node metadata is reused only inside that request and authentication generation. Other quota or rate limits, permission, verification, 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.

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

Authentication

BearerAuth

Parameters

Idempotency-Key header · string required

Request body required

application/json

SimilarwebPerformanceInput

domain string required
country integer: Default: 999
start_date string (date) required
end_date string (date) required
latest string: Default: "28d"
web_source string: Default: "Total"
comparison_domains array of string

Responses

200 Successful Response

application/json

SimilarwebReferralsResponse

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

{
  "tool": "similarweb",
  "task": "referrals",
  "status": "success",
  "query": {
    "domain": "example.com",
    "country": 999,
    "start_date": "2026-08-21",
    "end_date": "2026-09-17",
    "latest": "28d",
    "web_source": "Total",
    "comparison_domains": []
  },
  "modules": {
    "top_referrals_1": {
      "status": "success",
      "data": {
        "Data": [
          {
            "Domain": "peer.example",
            "Category": "Technology",
            "Favicon": "https://peer.example/icon",
            "Share": 0.2
          }
        ],
        "TotalCount": 1,
        "Filters": {},
        "TotalTopLevelCount": 1,
        "FromAlternativeSources": false
      },
      "error_code": null
    },
    "referring_categories_2": {
      "status": "success",
      "data": {
        "Data": [
          {
            "Category": "Technology",
            "Share": 0.2
          }
        ],
        "TotalCount": 1,
        "Filters": {},
        "TotalTopLevelCount": 1,
        "FromAlternativeSources": false
      },
      "error_code": null
    },
    "referral_destinations_3": {
      "status": "success",
      "data": {
        "Data": [
          {
            "Domain": "peer.example",
            "Category": "Technology",
            "HasAdsense": false,
            "Favicon": "https://peer.example/icon",
            "Share": 0.2
          }
        ],
        "TotalCount": 1,
        "Filters": {},
        "TotalTopLevelCount": 1,
        "FromAlternativeSources": false
      },
      "error_code": null
    }
  },
  "limitations": [],
  "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.

SimilarwebPerformanceInput

object

domain string required
country integer: Default: 999
start_date string (date) required
end_date string (date) required
latest string: Default: "28d"
web_source string: Default: "Total"
comparison_domains array of string

Complete schema

{
  "properties": {
    "domain": {
      "type": "string",
      "maxLength": 253,
      "minLength": 3,
      "title": "Domain"
    },
    "country": {
      "type": "integer",
      "const": 999,
      "title": "Country",
      "default": 999
    },
    "start_date": {
      "type": "string",
      "format": "date",
      "title": "Start Date"
    },
    "end_date": {
      "type": "string",
      "format": "date",
      "title": "End Date"
    },
    "latest": {
      "type": "string",
      "const": "28d",
      "title": "Latest",
      "default": "28d"
    },
    "web_source": {
      "type": "string",
      "const": "Total",
      "title": "Web Source",
      "default": "Total"
    },
    "comparison_domains": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "maxItems": 4,
      "title": "Comparison Domains"
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "domain",
    "start_date",
    "end_date"
  ],
  "title": "SimilarwebPerformanceInput"
}

SimilarwebReferralsResponse

SeoResponse and object

Complete schema

{
  "allOf": [
    {
      "$ref": "#/components/schemas/SeoResponse"
    },
    {
      "type": "object",
      "properties": {
        "tool": {
          "type": "string",
          "const": "similarweb",
          "description": "Server-selected tool identity; not a request parameter."
        },
        "task": {
          "type": "string",
          "const": "referrals"
        },
        "query": {
          "$ref": "#/components/schemas/SimilarwebPerformanceInput"
        },
        "modules": {
          "type": "object",
          "properties": {
            "top_referrals_1": {
              "$ref": "#/components/schemas/SeoModuleResult"
            },
            "referring_categories_2": {
              "$ref": "#/components/schemas/SeoModuleResult"
            },
            "referral_destinations_3": {
              "$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
    }
  }
}