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

# Tasks

> Submit work to a fleet, track lifecycle states, cancel, and replay.

A task is the unit of work in Hexel. You describe what you want done — "summarize this week's support tickets," "draft a quarterly report from these data sources" — and the platform figures out how: planning steps, choosing agents, executing, and recording the result. Use a task when the work involves planning, coordination, or multiple agents. If you just need a single model call with no orchestration overhead, call the agent directly instead.

A task is a unit of work submitted to a fleet. The platform plans it, runs it across the fleet's agents, and records the result. This page covers submitting tasks, their lifecycle, and management operations.

## Task lifecycle

<img src="https://mintcdn.com/hexelstudio-2127951d/utVkRjxsT1DGYlO5/assets/diagrams/task-lifecycle.png?fit=max&auto=format&n=utVkRjxsT1DGYlO5&q=85&s=44cc3ca4595a2e0f1372522a95ccd70f" alt="Task lifecycle states" width="1536" height="1024" data-path="assets/diagrams/task-lifecycle.png" />

| State         | Meaning                                                                        |
| ------------- | ------------------------------------------------------------------------------ |
| `pending`     | Accepted; awaiting dispatch. Task stays here until the platform dispatches it. |
| `planning`    | Plan is being generated.                                                       |
| `plan_review` | Awaiting approval before execution.                                            |
| `executing`   | Workflow is running across the fleet.                                          |
| `completed`   | Finished successfully (terminal).                                              |
| `failed`      | Encountered an error (terminal).                                               |
| `cancelled`   | Cancelled by user or policy (terminal).                                        |

## Submit a task

<Tabs>
  <Tab title="Python">
    ```python theme={"dark"}
    task = client.orchestrator.task.create(
        fleet_id="YOUR_FLEET_ID",
        environment_id="YOUR_ENVIRONMENT_ID",
        workspace_id="YOUR_WORKSPACE_ID",
        input="Summarize this week's support tickets",
        context='{"since": "2026-06-01"}',
    )
    print(task["id"], task["state"])  # pending
    ```
  </Tab>

  <Tab title="curl">
    ```bash theme={"dark"}
    curl -X POST https://api.hexelstudio.com/orchestrator/v1/tasks \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "fleet_id": "YOUR_FLEET_ID",
        "environment_id": "YOUR_ENVIRONMENT_ID",
        "workspace_id": "YOUR_WORKSPACE_ID",
        "input": "Summarize this week'\''s support tickets",
        "context": "{\"since\": \"2026-06-01\"}"
      }'
    ```
  </Tab>
</Tabs>

### Request parameters

<ParamField body="fleet_id" type="string" required>
  The fleet to execute this task.
</ParamField>

<ParamField body="environment_id" type="string" required>
  The environment scope.
</ParamField>

<ParamField body="workspace_id" type="string" required>
  The workspace scope.
</ParamField>

<ParamField body="input" type="string" required>
  The work to perform, as natural language text. Describe the outcome, not step-by-step instructions.
</ParamField>

<ParamField body="context" type="string">
  Additional structured context as a JSON-encoded string. Not a raw object.
</ParamField>

### Response

<ResponseField name="id" type="string">
  Unique task identifier.
</ResponseField>

<ResponseField name="state" type="string">
  Current lifecycle state.
</ResponseField>

<ResponseField name="fleet_id" type="string">
  Fleet this task was submitted to.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

## List tasks

```python theme={"dark"}
tasks = client.orchestrator.task.list()
```

```bash theme={"dark"}
curl "https://api.hexelstudio.com/orchestrator/v1/tasks?page=1&page_size=20" \
  -H "Authorization: Bearer $TOKEN"
```

## Get a task

```python theme={"dark"}
task = client.orchestrator.task.get("YOUR_TASK_ID")
```

## Cancel a task

Cancels a task in `pending`, `planning`, or `executing` state.

```python theme={"dark"}
client.orchestrator.task.cancel("YOUR_TASK_ID")
```

## Replay a task

Re-runs a completed or failed task from its recorded execution.

```python theme={"dark"}
client.orchestrator.task.replay("YOUR_TASK_ID")
```

## Stream a task

Follow execution in real time via SSE. See [Streaming & Replay](/docs/orchestration/streaming-and-replay) for event types.

```python theme={"dark"}
for event in client.orchestrator.task.stream("YOUR_TASK_ID"):
    print(event["type"], event.get("data"))
```

## Rate limits

100 requests per organization per minute. Pagination: `page` >= 1, `page_size` 1–100 (default 20).

<AccordionGroup>
  <Accordion title="Common errors">
    | Code  | Meaning                                             |
    | ----- | --------------------------------------------------- |
    | `404` | Task not found.                                     |
    | `409` | Task already in a terminal state (cannot cancel).   |
    | `422` | Missing required field or invalid `context` format. |
    | `429` | Rate limit exceeded.                                |
  </Accordion>

  <Accordion title="context field format">
    The `context` field must be a JSON-encoded **string**, not a raw JSON object. Serialize your structured data before passing it:

    ```python theme={"dark"}
    import json
    context = json.dumps({"since": "2026-06-01", "team": "support"})
    ```
  </Accordion>
</AccordionGroup>

## Errors

| HTTP  | Message                           | When                                                                |
| ----- | --------------------------------- | ------------------------------------------------------------------- |
| `400` | `fleet_id required` (and similar) | A required field is missing or `context` isn't a valid JSON string. |
| `403` | `compute entitlement required`    | Your organization isn't entitled to run tasks.                      |
| `404` | `task not found`                  | The task ID doesn't exist or isn't in your scope.                   |
| `429` | `rate limit exceeded`             | More than 100 requests in a minute. Back off and retry.             |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Task stays in pending and never starts">
    A submitted task remains `pending` until it's dispatched. If it never advances, confirm the `fleet_id` references a fleet that has agents attached, and that your organization has an active compute entitlement.
  </Accordion>

  <Accordion title="Submit returns 403 compute entitlement required">
    The organization lacks the compute entitlement needed to run tasks. Check your plan in the [Console](https://console.hexelstudio.com).
  </Accordion>

  <Accordion title="context is being rejected">
    `context` must be a JSON-encoded string, not a raw object. Serialize it before sending (for example, `json.dumps(...)`).
  </Accordion>

  <Accordion title="Task failed — how do I find out why?">
    Stream the task or [replay](/docs/orchestration/streaming-and-replay) it to see where execution failed, then adjust the `input` or `context`.
  </Accordion>
</AccordionGroup>

## Security

| Concern      | Guidance                                                                                                                                                  |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Scoping      | Tasks are scoped to the organization, workspace, and environment in the request body.                                                                     |
| Entitlement  | Submitting a task requires a compute entitlement on your plan. Returns `403` if missing.                                                                  |
| Input safety | Treat `input` and `context` as untrusted inside your agents. Do not place secrets in them — pass credentials through configured tool connections instead. |
| Permission   | Submitting requires the appropriate `orchestrator:task:write` RBAC permission.                                                                            |

## Related pages

<CardGroup cols={2}>
  <Card title="Fleets" icon="layer-group" href="/docs/orchestration/fleets">
    Where tasks run.
  </Card>

  <Card title="Approvals" icon="user-check" href="/docs/orchestration/approvals">
    Gate execution with approval.
  </Card>

  <Card title="Streaming & Replay" icon="play" href="/docs/orchestration/streaming-and-replay">
    Follow and reproduce tasks.
  </Card>

  <Card title="Tasks & Workflows" icon="sitemap" href="/docs/concepts/tasks-and-workflows">
    The underlying concept.
  </Card>
</CardGroup>

## Next steps

Continue to [Fleets](/docs/orchestration/fleets).