> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moss.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Tasks

> Tasks are asynchronous agent runs hosted by Moss. Each task defines a goal, a cloud browser environment, and configurable limits on runtime and cost, allowing agents to execute workflows independently of your application.

## 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`.

```bash curl theme={null}
curl https://inference.moss.dev/v1/tasks \
  -H "Authorization: Bearer $MOSS_PROJECT_ID:$MOSS_PROJECT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Find the opening hours of the city library.",
    "environment": {"type": "browser"},
    "limits": {"max_runtime_seconds": 600, "max_cost_usd": 2}
  }'
```

```python Python theme={null}
import asyncio
import os

from moss import MossInference

client = MossInference(os.environ["MOSS_PROJECT_ID"], os.environ["MOSS_PROJECT_KEY"])


async def main():
    task = await client.tasks.run(
        goal="Find the opening hours of the city library.",
        environment={"type": "browser"},
        limits={"max_runtime_seconds": 600, "max_cost_usd": 2},
    )
    if task.status == "completed":
        print(task.result.output_text)
    else:
        print(task.status, task.error)


asyncio.run(main())
```

```typescript JavaScript theme={null}
import { MossInference } from '@moss-js/moss'

const client = new MossInference(process.env.MOSS_PROJECT_ID!, process.env.MOSS_PROJECT_KEY!)
const task = await client.tasks.run({
  goal: 'Find the opening hours of the city library.',
  environment: { type: 'browser' },
  limits: { max_runtime_seconds: 600, max_cost_usd: 2 },
})
console.log(task.status, task.status === 'completed' ? task.result?.output_text : task.error)
```

The curl call returns `202` with the task's `id`. [Follow a task](#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.

| `status` | Meaning |
| - | - |
| `queued` | Waiting to start. |
| `running` | The agent is working. `usage` updates as it goes. |
| `completed` | The agent ended with an answer. |
| `failed` | The task failed. `error.code` says why. |
| `cancelled` | You cancelled it. |

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.

```bash theme={null}
curl https://inference.moss.dev/v1/tasks/$TASK_ID \
  -H "Authorization: Bearer $MOSS_PROJECT_ID:$MOSS_PROJECT_KEY"
```

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.

```json theme={null}
{
  "type": "browser",
  "start_url": "https://example.com"
}
```

| Field | Required | Notes |
| - | - | - |
| `type` | yes | `browser`. Any other value returns `400`. |
| `start_url` | no | An `http` or `https` URL to start from. |

## Choose a model

`moss-fast`, `moss-balanced` and `moss-advanced` go up in accuracy and cost. `model` also takes a model from [Models](https://docs.moss.dev/docs/inference/models.md), 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](https://docs.moss.dev/docs/inference/bring-your-own-key.md), 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.

| Your key | Runs |
| - | - |
| OpenAI | `openai/*` |
| Anthropic | `anthropic/*` |
| Google | `google/*` |

## Set limits

| Limit | Default | Range |
| - | - | - |
| `limits.max_runtime_seconds` | 1,800 s | 60 to 7,200 s |
| `limits.max_cost_usd` | \$2 | $0.01 to $50 |

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

| Field | Notes |
| - | - |
| `result.output_text` | The agent's final answer. |
| `result.output` | The answer as an object. |
| `verification.passed` | Whether the answer matches the schema. |
| `usage.cost` | What the task cost so far. |

`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`.

```json theme={null}
{
  "type": "object",
  "properties": {
    "opens": {"type": "string"},
    "closes": {"type": "string"}
  },
  "required": ["opens", "closes"]
}
```

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`.

```bash theme={null}
curl https://inference.moss.dev/v1/tasks/$TASK_ID/files \
  -H "Authorization: Bearer $MOSS_PROJECT_ID:$MOSS_PROJECT_KEY"
```

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`.

| `code` | Meaning |
| - | - |
| `time_limit` | The task reached `max_runtime_seconds`. |
| `budget_exceeded` | The task reached `max_cost_usd` without an answer. |
| `no_answer` | The agent ended without an answer. |
| `provider_key_rejected` | The vendor refused your `X-Moss-Provider-Key`. |
| Anything else | The task could not finish. Create it again. |

A project can have 20 tasks queued. One more returns `429` with `code` `too_many_queued_tasks`.

The [Tasks API reference](https://docs.moss.dev/docs/api-reference/v1/inference/tasks.md#errors) lists every status and code. [Errors and limits](https://docs.moss.dev/docs/inference/errors-and-limits.md) 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](https://docs.moss.dev/docs/inference/pricing.md#browser-tasks) has the prices.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.