generated: '2026-08-13'
method: searched
source: >-
  https://docs.similarweb.com/api-v5/getting-started/authentication,
  https://docs.similarweb.com/api-v5/guides/error-handling-and-troubleshooting,
  https://docs.similarweb.com/api-v5/guides/rest-api-data-version-migration,
  https://developers.similarweb.com/docs/rate-limit,
  https://developers.similarweb.com/docs/data-credits-unpublished-whats-new-in-v40,
  openapi/*.yml
description: >-
  Cross-cutting request/response semantics for the Similarweb REST and Batch APIs, read from
  the provider's own guides and reconciled against the OpenAPI in this repo and against a
  live unauthenticated probe of api.similarweb.com.

authentication:
  style: api-key
  header: api-key
  query_parameter: api_key
  note: >-
    Both a header and a query parameter are accepted; the docs use the `api-key` header in
    every example. Keys are generated by account admins from Settings > Account in the
    Similarweb platform; up to 3 active keys per user; keys do not expire. As of API V5 a
    SINGLE key works for both the REST and Batch surfaces (V4 required separate keys).
  docs: https://docs.similarweb.com/api-v5/getting-started/authentication
  see_also: authentication/similarweb-authentication.yml

idempotency:
  supported: false
  note: >-
    Similarweb documents no idempotency key, no request de-duplication window and no
    Idempotency-Key parameter, and none appears in any OpenAPI in this repo. The write
    surface is small and mostly configuration (create integration, subscribe webhook,
    request report); the Batch API's own retry mechanism is a server-side `retry` endpoint
    keyed on an existing report_id (retryRequest) rather than a client-supplied
    idempotency key. Recorded as an honest absence — no Idempotency pointer is emitted.

pagination:
  style: offset
  introduced: API v4
  parameters:
  - {name: limit, description: how many results to return}
  - {name: offset, description: number of results to skip}
  - {name: sort, description: metric to order results by}
  - {name: asc, description: order ascending or descending}
  scope: >-
    Documented as available on 60+ endpoints. The provider's marker for a paginated endpoint
    is a `v4` (or later) segment in the URL path.
  docs: https://developers.similarweb.com/docs/data-credits-unpublished-whats-new-in-v40

field_selection:
  supported: true
  note: >-
    API V5 introduced multi-metric requests — a single call can select several metrics
    instead of one metric per call as in V4 and earlier. This is the closest thing
    Similarweb has to sparse fieldsets.
  docs: https://docs.similarweb.com/api-v5/getting-started/what-s-new-in-v5

request_tracing:
  request_id_header: null
  note: >-
    No request-id or correlation header is documented, and none was observed on a live
    unauthenticated response. Observed response headers on a 401 from
    api.similarweb.com were: date, server (Kestrel), strict-transport-security, and the
    CloudFront edge headers (x-cache, via, x-amz-cf-id, x-amz-cf-pop). The CloudFront
    x-amz-cf-id is the only per-request identifier available and it is infrastructure, not
    an API contract.

versioning:
  scheme: uri-path
  current: v5
  observed_versions: [v1, v2, v3, v4, v5]
  note: >-
    Version is a path segment and it varies PER ENDPOINT rather than per API — v1, v2, v3,
    v4 and v5 paths are all live simultaneously. V5 is the current generation; legacy
    endpoints have a published sunset date of 2026-10-06.
  see_also: lifecycle/similarweb-lifecycle.yml

error_envelope:
  format: non-standard
  rfc9457: false
  note: >-
    Errors are NOT RFC 9457 problem+json. A live unauthenticated request to
    api.similarweb.com returned HTTP 401 with the plain-text body `invalid API key` and
    content type text/plain. Documented errors mix HTTP status codes (400/401/403/429/500)
    with Similarweb-specific numeric codes (101/102/103) carried in the response body.
  see_also: errors/similarweb-problem-types.yml

rate_limit_signaling:
  documented_limit: 10 requests per second
  status_on_exhaustion: 429
  response_headers: []
  retry_after: false
  note: >-
    Similarweb publishes the limit in prose but emits NO rate-limit response headers — no
    X-RateLimit-*, no RateLimit-*, no Retry-After were documented or observed. An agent
    cannot read remaining quota from a response; it must throttle client-side to 10 rps.
  see_also: rate-limits/similarweb-rate-limits.yml

metering:
  model: data-credits
  note: >-
    Consumption is metered in data credits, not calls. Credit cost per request is a product
    of domains x endpoint price x granularity x country filters x historical range x results
    requested. Rate-limited (429) requests consume no credits. The Batch API exposes a
    `request-validate` operation (validateRequest) so a caller can price a query before
    running it — the nearest equivalent to a dry-run in this API.
  docs: https://docs.similarweb.com/api-v5/guides/data-credits-calculations

async_pattern:
  applies_to: Batch API
  flow: >-
    POST a report request (requestReport) -> receive a report_id -> poll
    GET /batch/v4/request-status (getRequestStatus) or subscribe a webhook -> when status
    becomes `complete`, collect the output from the configured S3 / GCS / Snowflake
    destination.
  statuses: [processing, complete, internal_error]
  see_also: asyncapi/similarweb-webhooks.yml