Tasks - Hexel Studio

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

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

Python
curl

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

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\"}"
  }'

Request parameters

string

required

The fleet to execute this task.

string

required

The environment scope.

string

required

The workspace scope.

string

required

The work to perform, as natural language text. Describe the outcome, not step-by-step instructions.

string

Additional structured context as a JSON-encoded string. Not a raw object.

Response

string

Unique task identifier.

string

Current lifecycle state.

string

Fleet this task was submitted to.

string

ISO 8601 creation timestamp.

List tasks

tasks = client.orchestrator.task.list()

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

Get a task

task = client.orchestrator.task.get("YOUR_TASK_ID")

Cancel a task

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

client.orchestrator.task.cancel("YOUR_TASK_ID")

Replay a task

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

client.orchestrator.task.replay("YOUR_TASK_ID")

Stream a task

Follow execution in real time via SSE. See Streaming & Replay for event types.

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

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.

context field format

The context field must be a JSON-encoded string, not a raw JSON object. Serialize your structured data before passing it:

import json
context = json.dumps({"since": "2026-06-01", "team": "support"})

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

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.

Submit returns 403 compute entitlement required

The organization lacks the compute entitlement needed to run tasks. Check your plan in the Console.

context is being rejected

context must be a JSON-encoded string, not a raw object. Serialize it before sending (for example, json.dumps(...)).

Task failed — how do I find out why?

Stream the task or replay it to see where execution failed, then adjust the input or context.

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.

Fleets

Where tasks run.

Approvals

Gate execution with approval.

Streaming & Replay

Follow and reproduce tasks.

Tasks & Workflows

The underlying concept.

Next steps

Continue to Fleets.

​Task lifecycle

​Submit a task

​Request parameters

​Response

​List tasks

​Get a task

​Cancel a task

​Replay a task

​Stream a task

​Rate limits

​Errors

​Troubleshooting

​Security

​Related pages

Fleets

Approvals

Streaming & Replay

Tasks & Workflows

​Next steps

Task lifecycle

Submit a task

Request parameters

Response

List tasks

Get a task

Cancel a task

Replay a task

Stream a task

Rate limits

Errors

Troubleshooting

Security

Related pages

Next steps