Core conceptsResponses

Responses

Every endpoint returns the same JSON envelope, so one parser handles the whole API. Success and failure are distinguished by the top-level success boolean.

Success envelope

success

{
  "success": true,
  "data": { /* endpoint-specific payload */ },
  "message": "Success"
}

Paginated responses

list endpoints

{
  "success": true,
  "data": [ /* items */ ],
  "pagination": { "page": 1, "limit": 20, "total": 134, "pages": 7 }
}

The render object

Screenshot, PDF, extract, and job-poll responses all return this shape in data:

Field	Type	Description
`id`string	string	Render identifier, e.g. `rnd_8fk2m1c4`.
`type`string	string	Which primitive produced it. Options: `screenshot`, `pdf`, `extract`.
`status`string	string	Current state. Options: `queued`, `processing`, `done`, `failed`.
`url`string \| null	string \| null	Hosted artifact URL (screenshot/pdf). `null` for extract.
`url_expires_at`string \| null	string \| null	ISO timestamp when the artifact URL lapses (≈365 days).
`content`string \| null	string \| null	Extracted markdown/text/html. `null` for screenshot/pdf.
`meta`object	object	Engine metadata: dimensions, page count, word count, format, chunks, etc.
`render_ms`number	number	Server-measured render time in milliseconds.
`credits_used`number	number	Credits charged. `0` on a cache hit or failure.
`cached`boolean	boolean	Whether the result was served from cache.
`error`object \| null	object \| null	`{ code, message }` when `status` is `failed`.
`created_at`string	string	ISO creation timestamp.
`completed_at`string	string	ISO completion timestamp.

Error envelope

failure

{
  "success": false,
  "error": {
    "code": "FEATURE_NOT_AVAILABLE",
    "message": "'inject_js' requires a higher plan (not available on hobby).",
    "details": null,
    "request_id": "req_7c0f1a2b"
  }
}

Always log request_id

Every error carries a stable machine code and a request_id. Include the request_id in support tickets — it pinpoints the exact request in our logs. See the full error reference.