Submit design extraction
Design extraction
Submit design extraction
Run the design extractors against a URL. Returns immediately with a taskId; poll GET /v1/tasks/ for the result.
POST
Submit design extraction
For an overview of what each extractor returns, see Design extraction.
Response —
Submit response —
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.
Submit + wait (recommended)
Both SDKs wrap submit + poll into a singleclient.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)
Result schema
Thedesign.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.
