Skip to content
Screaming Data
Documentation menu

Guide

Response format

Every /v1 endpoint returns the same envelope. Requests carry one or more tasks, and both the request and each task have their own status code, processing time and cost.

The envelope

A POST body is an array of task objects, and the response has one task per element, in the same order. GET endpoints return exactly one task. A request rejected as a whole (for example, failed authentication) has an empty tasks array. This is the response to a task_post with two tasks, one at normal and one at high priority:

Response envelope
{
  "version": "1.0.0",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0391 sec.",
  "cost": 0.0045,
  "tasks_count": 2,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "09241235-4e1c-4b6a-9d8f-2c7a51f0e3b1",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0042 sec.",
      "cost": 0.0015,
      "result_count": 0,
      "path": [
        "v1",
        "amazon",
        "product",
        "task_post"
      ],
      "data": {
        "api": "amazon",
        "function": "product",
        "asin": "B0EXAMPLE1",
        "marketplace": "com",
        "priority": 1,
        "tag": "catalog-sync",
        "postback_url": "https://example.com/webhooks/postback"
      },
      "result": null
    },
    {
      "id": "09241235-7a02-4f3e-8c11-5b9d0e6a4c27",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0038 sec.",
      "cost": 0.003,
      "result_count": 0,
      "path": [
        "v1",
        "amazon",
        "product",
        "task_post"
      ],
      "data": {
        "api": "amazon",
        "function": "product",
        "asin": "B0EXAMPLE2",
        "marketplace": "uk",
        "priority": 2,
        "tag": "launch-watch",
        "pingback_url": "https://example.com/webhooks/pingback?id=$id&tag=$tag"
      },
      "result": null
    }
  ]
}

Envelope fields

version
string

Version of the API that produced the response.

status_code
integer

Status of the request as a whole. See Status codes.

status_message
string

Human-readable status.

time
string

Processing time, for example 0.0421 sec.

cost
number

Total USD charged for this request — the sum of the task costs.

tasks_count
integer

Number of tasks in tasks.

tasks_error
integer

Number of tasks whose status_code is an error (40000 and above).

tasks
array of objects

One task per element of the request body; GET endpoints return exactly one task.

Task fields

id
string (uuid)

Task id. The first 8 characters encode the creation time as MMDDHHmm (UTC).

status_code
integer

Status of this task.

status_message
string

Human-readable status of this task.

time
string

Processing time of this task.

cost
number

USD charged for this task.

result_count
integer

Number of elements in result.

path
array of strings

Path of the request, split into segments.

data
object

Echo of the task parameters plus api and function.

result
array· nullable

Result objects, or null when the task has no result (yet).

Task ids

Task ids are UUIDs. Their first eight characters encode when the task was created, as MMDDHHmm in UTC — for example 09241235-… was created on 24 September at 12:35. Sorting ids as text therefore sorts tasks roughly by creation time within a year.

Cost

  • cost is the exact amount charged, in US dollars. The top-level value is the sum of the task costs.
  • Tasks are charged when they are posted. Collecting results (task_get, tasks_ready) is free.
  • Failed tasks are refunded automatically: products that do not exist (40402) and pages that could not be read (50301) cost nothing. Refunds are credited back to your balance.
  • List prices are on the pricing page; volume rates are available on request. The rates that apply to your account are returned by user_data as rates.

HTTP status

HTTPWhen
200The request was processed. Individual tasks may still have error codes — always check each task.
400The body is not valid JSON or not an array of tasks (40000), has more than 100 tasks (40001), or a query or path parameter is invalid (40501).
401Authentication failed, the key is revoked or the account is disabled (40100, 40101, 40102).
402The balance does not cover the request (40200).
404Unknown endpoint, task id or key id (40400).
405The endpoint does not accept this HTTP method (40000).
413The body is larger than 1 MiB (40000).
429Rate limit exceeded (40202). Wait for the number of seconds in the Retry-After header.
500Internal error (50000). The body is still an envelope. Retry with backoff.

Conventions

  • JSON, UTF-8. Field names are snake_case.
  • Timestamps are ISO 8601 in UTC (2026-09-24T12:35:41Z); dates are YYYY-MM-DD.
  • Product prices are in the currency of the marketplace (price.currency); costs and balances are in USD.
  • A field that cannot be read reliably is null. Values are never guessed.
  • New fields may be added to responses at any time; ignore fields you do not know.
  • Every response has an X-Request-Id header. Include it, or the task id, when you contact support.