generated: '2026-08-13'
method: searched
source: >-
  https://docs.dataforseo.com/v3/, https://docs.dataforseo.com/v3/auth/,
  https://docs.dataforseo.com/v3/appendix/errors/,
  https://docs.dataforseo.com/v3/appendix/webhook_resend/,
  https://docs.dataforseo.com/v3/appendix/sandbox/, and openapi/*.yml

summary: >-
  DataForSEO is a task-oriented data API, not a resource CRUD API. Almost every
  endpoint is POST, almost every response is HTTP 200, and the real result is
  carried in a numeric status_code inside a fixed envelope. Three delivery modes
  exist for the same data — Standard (post a task, poll or receive a webhook),
  Priority (same, faster queue) and Live (synchronous) — and the choice is a
  cost/latency trade, not a different contract.

authentication:
  style: http-basic
  header: 'Authorization: Basic base64(login:password)'
  docs: https://docs.dataforseo.com/v3/auth/
  credentials_source: https://app.dataforseo.com/api-access
  notes:
    - No token exchange or separate auth call — credentials go on every request.
    - Credentials cannot be passed as URL parameters.
    - The API password is generated by DataForSEO and differs from the account password.
    - >-
      OAuth 2.0 exists but only on the MCP surface (mcp.dataforseo.com, AS at
      data.dataforseo.com). The REST API itself is Basic-only. See
      authentication/dataforseo-authentication.yml and scopes/dataforseo-scopes.yml.
  artifact: authentication/dataforseo-authentication.yml

request_model:
  content_type: application/json
  encoding: UTF-8
  body_shape: >-
    A JSON ARRAY of task objects, not a single object. Each element is one task.
  batch_limit: 100
  batch_limit_error: 40006
  live_batch_limit: 1
  live_batch_limit_error: 40000
  response_formats:
    - json (default)
    - xml (append `.xml` to the request path)
  compression: "gzip (default when using the official clients; Content-Encoding: gzip)"

task_lifecycle:
  modes:
    - id: standard
      pattern: POST task_post -> (webhook | GET tasks_ready) -> GET task_get/{id}
      turnaround: ~5 minutes
    - id: priority
      pattern: same as standard, priority queue
      turnaround: ~1 minute
    - id: live
      pattern: single synchronous POST to a /live/ path
      turnaround: seconds
  operations:
    task_post: 'POST .../task_post — enqueue up to 100 tasks'
    tasks_ready: 'GET .../tasks_ready — list completed, uncollected task ids'
    tasks_fixed: 'GET .../tasks_fixed — list re-parsed tasks not yet collected'
    task_get: 'GET .../task_get/{regular|advanced|html}/{id} — collect the result'
    id_list: 'POST .../id_list — task ids + metadata for a time window'
    errors: 'POST .../errors — tasks that errored in the last 7 days'
  pending_codes: [40601, 40602]
  result_retention:
    standard_and_priority: 30 days
    html: 7 days
    live: not stored
  expired_code: 40403

idempotency:
  supported: false
  note: >-
    DataForSEO documents NO idempotency key. There is no Idempotency-Key header
    and no idempotency parameter anywhere in the 554 operations under openapi/,
    and the string "idempoten" does not occur in the docs index, the auth page,
    the error reference or the MCP server README (checked 2026-08-13).
  adjacent_mechanisms:
    - mechanism: client-supplied task id
      field: id
      detail: >-
        A task `id` is unique per client, per search engine, per search type and
        per function; reusing one across those boundaries returns 40001-40004.
        This prevents id collisions — it does not make a retried POST safe.
    - mechanism: duplicate-task limits
      codes: [40205, 40206]
      detail: >-
        Per-hour and per-day duplicate task limits (configurable in the account
        dashboard) throttle repeated identical tasks. This is spend protection,
        not an idempotency guarantee: a retry inside the limit is charged again.
    - mechanism: tag
      field: tag
      detail: Free-form client label echoed back on results and webhooks; useful for reconciliation.
  guidance_for_agents: >-
    Because retries are billable and there is no idempotency key, an agent
    should record the task `id` it generated before POSTing, and on any network
    failure poll tasks_ready / id_list for that id BEFORE re-posting.

pagination:
  style: offset-limit
  params:
    limit: maximum results to return
    offset: number of results to skip
  response_fields: [result_count, items_count, total_count]
  note: >-
    Applied per endpoint on the task/POST body rather than as query strings; the
    exact parameter set varies by API family (Backlinks and Labs additionally
    expose `filters`, `order_by` and `backlinks_status_type`). No cursor or
    link-header pagination exists.

filtering_and_sorting:
  filters: >-
    Many Labs / Backlinks / OnPage endpoints accept a `filters` array using a
    field/operator/value triple form, plus `order_by` for sorting. See the
    per-endpoint documentation.
  supported_operators_docs: https://docs.dataforseo.com/v3/

error_semantics:
  envelope: status_code + status_message (top level and per task)
  http_note: >-
    HTTP 200 is returned for nearly everything; only 401, 402, 404 and 500 are
    used at the HTTP layer. Branch on status_code, not on HTTP status.
  artifact: errors/dataforseo-problem-types.yml

rate_limit_signaling:
  documented_limit: 2000 API calls per minute per account
  exhaustion_signal: status_code 40202 inside an HTTP 200 response
  concurrency_signal: status_code 40209 (max 30 simultaneous queries per user)
  cost_limit_signal: status_code 40203
  balance_signal: status_code 40210 (insufficient funds) / HTTP 402
  headers_observed: none
  headers_note: >-
    No X-RateLimit-* or RateLimit-* headers were present on a live
    unauthenticated response from api.dataforseo.com (probed 2026-08-13). An
    agent must read status_code 40202 to detect throttling.
  artifact: rate-limits/dataforseo-rate-limits.yml

cost_accounting:
  fields: [cost, time]
  detail: >-
    Every response carries a top-level `cost` (USD, float) and per-task `cost`,
    so spend is observable inline on every call — unusual and useful for agents
    operating under a budget. Balance is prepaid; see plans/ and finops/.

request_tracing:
  request_id_header: none
  correlation: >-
    Correlate by the task `id` (UUID) and the client-supplied `tag`. There is no
    per-request trace/correlation header.

versioning:
  scheme: uri-path
  current: v3
  detail: Every path is prefixed /v3/. No date or header versioning.
  artifact: lifecycle/dataforseo-lifecycle.yml

webhooks:
  fields: [postback_url, pingback_url, postback_data]
  resend: POST /v3/appendix/webhook_resend (up to 100 task ids, not double-charged)
  artifact: asyncapi/dataforseo-webhooks.yml

sandbox:
  host: https://sandbox.dataforseo.com
  detail: Swap the hostname; identical paths and payloads, free, dummy data.
  artifact: sandbox/dataforseo-sandbox.yml

ai_optimized_responses:
  detail: >-
    DataForSEO publishes AI-optimized response variants for LLM consumption; the
    v3 MCP server's api_request tool calls `.ai` paths by default.
  docs: https://docs.dataforseo.com/v3/appendix/ai_optimized_response/