Analyze Website Traffic Sources with Similarweb

POST/v1/similarweb/traffic-sources

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. The 200 response has exactly two traffic-source modules - geography_1 and marketing_mix_2. geography_1.data.Data contains country rows with Country and Share, plus optional UsersShare, ShareList, AvgVisitDuration, PagePerVisit, BounceRate and Rank fields. marketing_mix_2.data.Data.Total is keyed by the requested domain and contains numeric channel shares including Direct, Search - Organic, Search - Paid and Referrals; additional provider channels may be present. Both modules retain their status/error_code envelope.

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/traffic-sources" \
  -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

SimilarwebTrafficSourcesResponse

Response for POST /v1/similarweb/traffic-sources. The two module keys are stable; a failed or not_run module keeps the same envelope with data null and an optional error_code.

tool string required
task string required
status string required: Allowed: "success", "partial", "failed"
query SimilarwebTrafficSourcesQuery required
modules object required
limitations array of string
billing SeoBillingSummary

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

{
  "tool": "similarweb",
  "task": "traffic-sources",
  "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": {
    "geography_1": {
      "status": "success",
      "data": {
        "Data": [
          {
            "Rank": 12,
            "Share": 0.2,
            "Country": 840,
            "AvgVisitDuration": 30,
            "BounceRate": 0.3
          }
        ],
        "TotalCount": 1,
        "Filters": {},
        "TotalTopLevelCount": 1,
        "FromAlternativeSources": false
      },
      "error_code": null
    },
    "marketing_mix_2": {
      "status": "success",
      "data": {
        "Data": {
          "Total": {
            "example.com": {
              "Direct": 0.4,
              "Search - Organic": 0.3,
              "Search - Paid": 0.1,
              "Referrals": 0.2
            }
          }
        }
      },
      "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"
}

SimilarwebTrafficSourcesResponse

object

Response for POST /v1/similarweb/traffic-sources. The two module keys are stable; a failed or not_run module keeps the same envelope with data null and an optional error_code.

tool string required
task string required
status string required: Allowed: "success", "partial", "failed"
query SimilarwebTrafficSourcesQuery required
modules object required
limitations array of string
billing SeoBillingSummary

Complete schema

{
  "type": "object",
  "description": "Response for POST /v1/similarweb/traffic-sources. The two module keys are stable; a failed or not_run module keeps the same envelope with data null and an optional error_code.",
  "properties": {
    "tool": {
      "type": "string",
      "const": "similarweb"
    },
    "task": {
      "type": "string",
      "const": "traffic-sources"
    },
    "status": {
      "type": "string",
      "enum": [
        "success",
        "partial",
        "failed"
      ]
    },
    "query": {
      "$ref": "#/components/schemas/SimilarwebTrafficSourcesQuery"
    },
    "modules": {
      "type": "object",
      "properties": {
        "geography_1": {
          "$ref": "#/components/schemas/SimilarwebTrafficSourcesGeographyModule"
        },
        "marketing_mix_2": {
          "$ref": "#/components/schemas/SimilarwebTrafficSourcesMarketingMixModule"
        }
      },
      "required": [
        "geography_1",
        "marketing_mix_2"
      ],
      "additionalProperties": false
    },
    "limitations": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "billing": {
      "$ref": "#/components/schemas/SeoBillingSummary"
    }
  },
  "required": [
    "tool",
    "task",
    "status",
    "query",
    "modules"
  ],
  "additionalProperties": false
}

SimilarwebTrafficSourcesQuery

object

domain string required
country integer required: 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

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "minLength": 3,
      "maxLength": 253
    },
    "country": {
      "type": "integer",
      "const": 999,
      "default": 999
    },
    "start_date": {
      "type": "string",
      "format": "date"
    },
    "end_date": {
      "type": "string",
      "format": "date"
    },
    "latest": {
      "type": "string",
      "const": "28d",
      "default": "28d"
    },
    "web_source": {
      "type": "string",
      "const": "Total",
      "default": "Total"
    },
    "comparison_domains": {
      "type": "array",
      "maxItems": 4,
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "domain",
    "country",
    "start_date",
    "end_date"
  ],
  "additionalProperties": false
}

SimilarwebTrafficSourcesGeographyModule

object

status string required: Allowed: "success", "failed", "not_run"
data SimilarwebTrafficSourcesGeographyData or null
error_code string or null

Complete schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success",
        "failed",
        "not_run"
      ]
    },
    "data": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/SimilarwebTrafficSourcesGeographyData"
        },
        {
          "type": "null"
        }
      ]
    },
    "error_code": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "status"
  ]
}

SimilarwebTrafficSourcesGeographyData

object

Data array of SimilarwebTrafficSourcesGeographyRow required
TotalCount integer
TotalTopLevelCount integer
Filters object
FromAlternativeSources boolean

Complete schema

{
  "type": "object",
  "properties": {
    "Data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SimilarwebTrafficSourcesGeographyRow"
      }
    },
    "TotalCount": {
      "type": "integer",
      "minimum": 0
    },
    "TotalTopLevelCount": {
      "type": "integer",
      "minimum": 0
    },
    "Filters": {
      "type": "object",
      "additionalProperties": true
    },
    "FromAlternativeSources": {
      "type": "boolean"
    }
  },
  "required": [
    "Data"
  ],
  "additionalProperties": false
}

SimilarwebTrafficSourcesGeographyRow

object

Country-level traffic distribution row returned by Similarweb.

Country integer required: Similarweb country identifier.
Share number required: Share of visits attributed to the country.
UsersShare number
ShareList object
AvgVisitDuration number
PagePerVisit number
BounceRate number
Rank integer

Complete schema

{
  "type": "object",
  "description": "Country-level traffic distribution row returned by Similarweb.",
  "properties": {
    "Country": {
      "type": "integer",
      "description": "Similarweb country identifier."
    },
    "Share": {
      "type": "number",
      "description": "Share of visits attributed to the country."
    },
    "UsersShare": {
      "type": "number"
    },
    "ShareList": {
      "type": "object",
      "additionalProperties": {
        "type": "number"
      }
    },
    "AvgVisitDuration": {
      "type": "number"
    },
    "PagePerVisit": {
      "type": "number"
    },
    "BounceRate": {
      "type": "number"
    },
    "Rank": {
      "type": "integer"
    }
  },
  "required": [
    "Country",
    "Share"
  ],
  "additionalProperties": false
}

SimilarwebTrafficSourcesMarketingMixModule

object

status string required: Allowed: "success", "failed", "not_run"
data SimilarwebTrafficSourcesMarketingMixData or null
error_code string or null

Complete schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success",
        "failed",
        "not_run"
      ]
    },
    "data": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/SimilarwebTrafficSourcesMarketingMixData"
        },
        {
          "type": "null"
        }
      ]
    },
    "error_code": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "status"
  ]
}

SimilarwebTrafficSourcesMarketingMixData

object

Data object required

Complete schema

{
  "type": "object",
  "properties": {
    "Data": {
      "type": "object",
      "properties": {
        "Total": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/components/schemas/SimilarwebTrafficSourcesMarketingMixChannelShares"
          }
        }
      },
      "required": [
        "Total"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "Data"
  ],
  "additionalProperties": false
}

SimilarwebTrafficSourcesMarketingMixChannelShares

object

Numeric visit shares keyed by the provider channel name.

Direct number required
Search - Organic number required
Search - Paid number required
Referrals number required
Social - Paid number
Social - Organic number
Email number
Display Ads number
Gen AI number
Affiliates number

Complete schema

{
  "type": "object",
  "description": "Numeric visit shares keyed by the provider channel name.",
  "properties": {
    "Direct": {
      "type": "number"
    },
    "Search - Organic": {
      "type": "number"
    },
    "Search - Paid": {
      "type": "number"
    },
    "Referrals": {
      "type": "number"
    },
    "Social - Paid": {
      "type": "number"
    },
    "Social - Organic": {
      "type": "number"
    },
    "Email": {
      "type": "number"
    },
    "Display Ads": {
      "type": "number"
    },
    "Gen AI": {
      "type": "number"
    },
    "Affiliates": {
      "type": "number"
    }
  },
  "required": [
    "Direct",
    "Search - Organic",
    "Search - Paid",
    "Referrals"
  ],
  "additionalProperties": {
    "type": "number"
  }
}

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