---
title: "Create a task"
url: https://hexelstudio.com/docs/api/harness/tasks/create
---

# Create a task

**POST** `/harness/tasks`

Billing and limits are checked first (refusals keep billing's codes, for example
`402 insufficient_balance`, `429 too_many_running_tasks`). A
task can start `after` other tasks and take `inputs_from` their outputs.


## Headers

- `Authorization: string`

  `Bearer <token>`. A Hexel Studio access token for your organization.

- `X-Workspace-Id: string`

  The workspace the request acts in (`ws_...`). It never grants access by itself.

- `X-Environment-Id: string`

  The environment the request acts in (`env_...`). It never grants access by itself.

## Body parameters

- `goal: string`

- `agent: string`

  name, name@channel or name@v<n>.

- `inputs: optional object`

  At most 256 KiB.

- `budget: optional Budget`

  What a task may spend; it narrows the agent's own budgets. `max_estimate_usd` is accepted on create only.

  - `max_usd: optional number`

  - `max_steps: optional integer`

  - `max_tokens: optional integer`

  - `max_wall_clock_s: optional number`

  - `max_estimate_usd: optional number`

- `sandbox_template: optional string`

- `after: optional array of string`

  1 to 20 tasks this one starts after.

- `inputs_from: optional map[string]`

  {"<name>": "<task_id>.outputs.<key>..."}.

- `checkin: optional object`

  A task.digest every every_s seconds (3600 to 2592000).

  - `every_s: integer`

## Returns

`200` A trigger fire's task that already exists (a replayed fire). (`Task`)

- `agent: string`

- `agent_id: string`

- `budget: any`

  Any JSON value.

- `bundle_digest: string`

- `cost_usd: number`

- `created_at: string`

- `created_by: string`

- `end_reason: optional string`

- `environment_id: string`

- `erased_at: optional string`

- `goal: string`

- `goal_digest: optional string`

- `held_at: optional string`

- `id: string`

- `inputs: any`

  Any JSON value.

- `inputs_digest: optional string`

- `last_seq: integer`

- `org_id: string`

- `outputs: optional object`

  - `text: optional string`

    The agent's last message.

  - `result: optional any`

    The structured result, when the agent gave one.

- `run_id: string`

- `sandbox_template: optional string`

- `state: string`

  One of: `"queued"`, `"running"`, `"waiting"`, `"paused"`, `"succeeded"`, `"failed"`, `"budget_exhausted"`, `"cancelled"`

- `swarm_id: optional string`

- `tokens_in: integer`

- `tokens_out: integer`

- `updated_at: string`

- `version: integer`

- `waiting_reason: optional string`

- `workspace_id: string`

## Errors

- `default` 

## Example

```bash
curl --request POST \
  --url 'https://api.hexelstudio.com/v1/harness/tasks' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'X-Workspace-Id: X_WORKSPACE_ID' \
  --header 'X-Environment-Id: X_ENVIRONMENT_ID' \
  --header 'Content-Type: application/json' \
  --data '{
  "goal": "string",
  "agent": "string",
  "inputs": {},
  "budget": {
    "max_usd": 0,
    "max_steps": 0,
    "max_tokens": 0,
    "max_wall_clock_s": 0,
    "max_estimate_usd": 0
  },
  "sandbox_template": "string",
  "after": [
    "string"
  ],
  "inputs_from": {
    "key": "string"
  },
  "checkin": {
    "every_s": 0
  }
}'
```

### Response (200)

```json
{
  "agent": "string",
  "agent_id": "string",
  "budget": "string",
  "bundle_digest": "string",
  "cost_usd": 0,
  "created_at": "2026-01-01T00:00:00Z",
  "created_by": "string",
  "end_reason": "string",
  "environment_id": "string",
  "erased_at": "2026-01-01T00:00:00Z",
  "goal": "string",
  "goal_digest": "string",
  "held_at": "2026-01-01T00:00:00Z",
  "id": "string",
  "inputs": "string",
  "inputs_digest": "string",
  "last_seq": 0,
  "org_id": "string",
  "outputs": {
    "text": "string",
    "result": "string"
  },
  "run_id": "string",
  "sandbox_template": "string",
  "state": "queued",
  "swarm_id": "string",
  "tokens_in": 0,
  "tokens_out": 0,
  "updated_at": "2026-01-01T00:00:00Z",
  "version": 0,
  "waiting_reason": "string",
  "workspace_id": "string"
}
```

### Response (201)

```json
{
  "agent": "string",
  "agent_id": "string",
  "budget": "string",
  "bundle_digest": "string",
  "cost_usd": 0,
  "created_at": "2026-01-01T00:00:00Z",
  "created_by": "string",
  "end_reason": "string",
  "environment_id": "string",
  "erased_at": "2026-01-01T00:00:00Z",
  "goal": "string",
  "goal_digest": "string",
  "held_at": "2026-01-01T00:00:00Z",
  "id": "string",
  "inputs": "string",
  "inputs_digest": "string",
  "last_seq": 0,
  "org_id": "string",
  "outputs": {
    "text": "string",
    "result": "string"
  },
  "run_id": "string",
  "sandbox_template": "string",
  "state": "queued",
  "swarm_id": "string",
  "tokens_in": 0,
  "tokens_out": 0,
  "updated_at": "2026-01-01T00:00:00Z",
  "version": 0,
  "waiting_reason": "string",
  "workspace_id": "string"
}
```
