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

> Reference for the Tasks routes: create a task, get it, cancel it, and list or download its files.

`POST /v1/tasks` gives an agent a goal to work on in an environment on Moss. [Tasks](https://docs.moss.dev/docs/inference/tasks.md) explains the API and shows how to run a task in a cloud browser.

## Base URL

```text theme={null}
https://inference.moss.dev/v1
```

## Authentication

```text theme={null}
Authorization: Bearer <project_id>:<project_key>
```

## Routes

| Route | What it does | Returns |
| - | - | - |
| `POST /v1/tasks` | Creates a task. | `202` and the [task](#response) |
| `GET /v1/tasks/{id}` | Gets a task's status, result and usage. | `200` and the task |
| `POST /v1/tasks/{id}/cancel` | Cancels a task. | `200` and the task |
| `GET /v1/tasks/{id}/files` | Lists a finished task's files. | A list of files |
| `GET /v1/tasks/{id}/files/{path}` | Downloads one file. | The file |

[Cancellation](#cancellation) and [Files](#files) cover the last three routes.

## Request

| Header | Notes |
| - | - |
| `Idempotency-Key` | Optional. 1 to 255 visible ASCII characters, valid for 24 hours per project. |
| `X-Moss-Provider-Key` | Optional. Your [own vendor key](https://docs.moss.dev/docs/inference/bring-your-own-key.md). |

The same `Idempotency-Key` and body returns the first task, with `Idempotent-Replayed: true`. The same key with another body returns `422` `idempotency_key_reused`.

[Choose a model](https://docs.moss.dev/docs/inference/tasks.md#choose-a-model) lists the models each vendor key can run.

An unknown top-level field returns `400`. The body limit is 256 KiB, and a larger body returns `413`.

| Field | Default | Notes |
| - | - | - |
| `goal` | required | A string, up to 20,000 characters. |
| `environment.type` | required | Where the agent works. Only `browser`. |
| `environment.start_url` | none | An `http` or `https` URL. |
| `model` | `moss-balanced` | A task model, or a model from [Models](https://docs.moss.dev/docs/inference/models.md). |
| `effort` | `medium` | `low`, `medium` or `high`. |
| `output_schema` | none | A JSON Schema, up to 20,000 bytes. |
| `limits.max_runtime_seconds` | 1800 | 60 to 7200. |
| `limits.max_cost_usd` | 2 | 0.01 to 50. It caps model calls only. |
| `metadata` | none | An object, up to 4,000 bytes. |

The task models are `moss-fast`, `moss-balanced` and `moss-advanced`. `model` also takes a model from [Models](https://docs.moss.dev/docs/inference/models.md). Any other `model` returns `400` `model_not_found`, which lists the names. Any other `environment.type` returns `400`.

`output_schema` takes a schema with `type` `object`. The default `max_runtime_seconds` is 1200 on `moss-fast` and 3600 on `moss-advanced`.

```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"},
    "model": "moss-balanced",
    "limits": {"max_runtime_seconds": 600, "max_cost_usd": 2}
  }'
```

## Response

| Field | Meaning |
| - | - |
| `id` | `task_` followed by 32 hex characters. |
| `object` | `task` |
| `status` | `queued`, `running`, `completed`, `failed` or `cancelled`. |
| `goal`, `environment`, `output_schema`, `limits`, `model`, `effort`, `metadata` | From the [request](#request). |
| `byok` | Whether the task ran on your key. |
| `result` | `{output_text, output}` or `null`. `output` is an object when you sent `output_schema`, otherwise `null`. |
| `verification` | `{method, passed, problems}`. `passed` is `null` without `output_schema`. A task whose answer does not match still ends `completed`. |
| `usage` | `model_calls`, `input_tokens`, `cached_input_tokens`, `output_tokens`, `cost_usd`, `steps`, `browser_minutes`, `browser_seconds`, `browser_traffic_mb` and `cost`. Updated during the run. Traffic fields can be `null` until a few hours after the task ends. |
| `usage.cost` | `{model_usd, browser_usd, traffic_usd, total_usd}` |
| `error` | `{code, message}`. See [Errors](#errors). |
| `cancel_requested` | Whether a cancel was requested. |
| `created_at`, `started_at`, `finished_at`, `files_expire_at` | ISO-8601 UTC timestamps. |

## Cancellation

`POST /v1/tasks/{id}/cancel` returns the task. A queued task is cancelled at once. A running task returns `cancel_requested: true` and ends `cancelled` soon after. A finished task is unchanged.

## Files

`GET /v1/tasks/{id}/files` returns `{"object": "list", "data": [...]}`, where each item has `path` and `bytes`. `GET /v1/tasks/{id}/files/{path}` returns the file.

Both routes return `409` `task_not_finished` until the task ends, and `410` `files_expired` 7 days after it ends.

## Errors

The body is `{"error": {...}}` with `message`, `type`, `code` and `request_id`.

| HTTP | `code` or `type` | When |
| - | - | - |
| `400` | `invalid_request_error`, `model_not_found`, `model_not_enabled` | The request or the model is not valid. |
| `401` | `authentication_error` | The project id or key is not valid. |
| `403` | `tasks_not_enabled` | The project does not have access. |
| `404` | `not_found_error` | The task does not exist. |
| `409` | `task_not_finished` | The task has not ended. |
| `410` | `files_expired` | The files were removed. |
| `413` | `invalid_request_error` | The body is over 256 KiB. |
| `422` | `idempotency_key_reused` | The key was used with another body. |
| `429` | `too_many_queued_tasks` | The project has 20 tasks queued. Wait for `Retry-After`. |
| `429` | `usage_limit_exceeded` | The project reached a usage limit. |
| `503` | `tasks_unavailable` | Tasks are down for now. Wait for `Retry-After`. |

A failed task has `error.code` `time_limit`, `budget_exceeded`, `no_answer` or `provider_key_rejected`. Anything else means create it again. [Tasks](https://docs.moss.dev/docs/inference/tasks.md#errors) explains each one.


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