Skip to main content
POST
Submit design extraction
For an overview of what each extractor returns, see Design extraction.

Request body

string
required
The page to extract from. Must be a valid http:// or https:// URL.
string
required
Opaque identifier for the user this extraction runs on behalf of. See End users. Must be ≤ 256 characters.
string[]
Subset of extractors to run. Valid values: "images", "fonts", "colors", "icons", "tokens", "logo". Omit (or pass an empty array) to run all six. Unknown names are silently dropped; if the resulting list is empty the request returns 400.
boolean
Optional. Defaults to false. When true, the browser session is launched through the residential proxy/IP rotation pool. Use this for sites that rate-limit, geo-vary, or block normal cloud traffic.

Response — 202 Accepted

string
Identifier for the extraction. Poll GET /v1/tasks/{taskId} until status === "completed".
string
Always a freshly-minted session — design extractions are single-turn and don’t chain like agent tasks.
string
Always "pending" on submission.
string[]
The extractors that will actually run (echoed back so callers know exactly what to expect on the result).
boolean
Echoes whether this extraction was submitted with IP rotation enabled.
string (ISO 8601)
Submission timestamp.
Both SDKs wrap submit + poll into a single client.design.run(...) call. Most integrators should use this — it returns the completed task with design.results populated and never needs you to think about the task lifecycle.
task.design carries the full result shape (response schema).

Async primitives

If you need to queue extractions and poll on your own schedule (cron jobs, batch processors), the underlying primitives are available:
client.tasks.get(taskId) is the same call you’d use for an agent task — design tasks ride the same task record and the design field is populated automatically.

Submit response — 202 Accepted

Get-task response (completed)

Typical extractions finish in 5–15 seconds. Recommended poll interval if you’re driving the loop yourself: 2 seconds.

Result schema

The design.results object contains one key per requested extractor. Top-level shape per extractor: See Design extraction for what each field means and the URL TTL caveat.

Errors