Skip to main content

Run a task

In an SDK, tasks.run creates the task and polls until it ends. A task that fails is returned, not raised, so check status.
The curl call returns 202 with the task’s id. Follow a task shows how to poll it. client.tasks needs Python or JavaScript 1.23.0, Browser 1.9.0, Elixir 1.12.0, Swift 0.14.0, Android or C 0.30.0.

Follow a task

POST /v1/tasks returns the task as queued. Its status then moves on its own. A task ends as completed, failed or cancelled. With curl, poll GET /v1/tasks/{id} until it does. Set TASK_ID to the id from the create call.
In an SDK, tasks.create returns the queued task at once, and tasks.wait polls it until it ends.

Set the environment

environment says where the agent works. browser, a cloud browser on Moss, is the only type.

Choose a model

moss-fast, moss-balanced and moss-advanced go up in accuracy and cost. model also takes a model from Models, including the open models z-ai/glm-5.3, z-ai/glm-5.3-flash, moonshotai/kimi-k3, deepseek/deepseek-v4.1-flash, deepseek/deepseek-v4.1-flash-1017, minimax/minimax-m3.1-flash and qwen/qwen3.8-flash. Without model, a task runs on moss-balanced. To run the model calls on your own key, send it in X-Moss-Provider-Key. In the SDKs, pass api_key to tasks.run in Python, or apiKey in its second argument in JavaScript. Both need SDK 1.24.0. A key set on the client is not used for tasks. Set model to one your key can run. moss-* models don’t take your key.

Set limits

The default runtime is 1,200 s on moss-fast and 3,600 s on moss-advanced. A task that reaches max_runtime_seconds fails with time_limit. A task that reaches max_cost_usd without an answer fails with budget_exceeded. max_cost_usd caps model calls only. On your own key, it counts only the 20% fee. Calls already running when the cap is reached still finish and bill.

Read the result

usage.cost has model_usd, browser_usd, traffic_usd and total_usd. To get the answer as an object, send output_schema, a JSON Schema with type object. Without one, result.output and verification.passed are null.
A task whose answer does not match the schema still ends completed. Check verification.passed before you use result.output.

Download files

A finished task keeps its screenshots and the files the agent wrote for 7 days.
  • GET /v1/tasks/{id}/files lists them, each with path and bytes. In an SDK, call tasks.files.list.
  • GET /v1/tasks/{id}/files/{path} returns one file. In an SDK, call tasks.files.content.
Both routes return 409 until the task ends, and 410 once the files are removed.

Cancel a task

POST /v1/tasks/{id}/cancel stops a task. In an SDK, call tasks.cancel. A queued task is cancelled at once. A running task returns cancel_requested: true and ends cancelled soon after. A finished task is unchanged.

Errors

A failed task has an error.code. A project can have 20 tasks queued. One more returns 429 with code too_many_queued_tasks. The Tasks API reference lists every status and code. Errors and limits covers authentication and usage errors.

Billing

A task bills its model calls and its cloud browser time and traffic, even if it fails or is cancelled. Pricing has the prices.