Skip to main content
POST
Submit task

Request body

endUserId
string
required
Opaque identifier for the user this task runs on behalf of. See End users. Must be ≤ 256 characters.
task
string
required
The natural-language prompt. Must be non-empty after trimming.
sessionId
string
Pass a previous task’s sessionId to continue a conversation. Omit to start a new session (server mints one and returns it).
startUrl
string
If you know the specific page to start from, pass the URL. Skips the agent’s URL-discovery step.
schema
object
A JSON Schema describing the shape of structured data you want back. When set, the completed task’s structured_content field contains the conforming object.
maxSteps
number
default:"25"
Upper bound on agent steps before the task is forced to finalize. Server clamps to min(maxSteps, 25).
include_html_dump
boolean
default:"false"
If true, the last page’s raw HTML is returned on the final task record as html_dump.

Response — 201 Created

taskId
string
Newly-created task identifier.
sessionId
string
Either the session you passed in, or a newly-minted one if you omitted sessionId.
status
string
Always "pending" on submission. Poll GET /v1/tasks/{taskId} for terminal state.
createdAt
string (ISO 8601)
Task creation timestamp.

Example

Response
The Python and TypeScript SDKs also offer tasks.run(...) which submits + polls + returns the completed task in one call. Prefer it over submit + manual polling unless you’re building your own streaming UI.

Errors