---
title: Task chains
description: Start a task after other tasks finish, feed it their outputs, and
  get a periodic check-in on long tasks.
url: https://hexelstudio.com/docs/harness/chains
---

A task can wait for other tasks, take values from their outputs, and post a periodic digest while it runs.

```bash
hexel harness task create "Audit the api repo" --agent auditor
# Task tsk_1 queued ...
hexel harness task create "Summarise the audit" --agent writer \
  --after tsk_1 --input-from report=tsk_1.outputs.text
```

## Fields

| Field | Description |
| --- | --- |
| `after` | 1 to 20 task ids this task starts after. Each must be a task you can see, in the same workspace and environment, and not already failed, cancelled or out of budget (`409 dependency_failed`). |
| `inputs_from` | 1 to 32 inputs taken from those tasks' outputs: `{"<name>": "<task_id>.outputs.<key>[.<key>...]"}`. Each task named is waited on as if it were in `after` (at most 20 tasks in all). |
| `checkin` | `{"every_s": n}`: a `task.digest` event every `n` seconds (3600 to 2592000) while the task is not finished. |

A task's outputs are `{text, result}`: `<task_id>.outputs.text` is the agent's last message, and `<task_id>.outputs.result.<field>` a field of its structured result (a key of digits indexes a list). An input name is an identifier of up to 64 characters that is not also a key of `inputs`.

The values `inputs_from` names are read in your runtime when the task starts; they never pass through the harness's control plane.

## How a chained task runs

1. It is created `waiting` with `waiting_reason: dependency`, and its stream gets `task.dependency` `{waiting_on}`.
2. Within seconds of the last of its dependencies succeeding, it is `queued` and starts.
3. If one of them fails, is cancelled, runs out of budget or is deleted, it ends `failed` with `end_reason: dependency_failed`, and so does every task after it in turn.

While it waits, it cannot be paused (`409 waiting_on_dependencies`; cancel it instead), and its retry or resume is refused (`409 dependency_unmet`) until every task it starts after has succeeded. A chained task counts toward your organization's running tasks from the moment it is created.

`GET /harness/tasks/{id}` shows a task's `chain: {after, inputs_from, checkin}`.

## Check-ins

A check-in is a `task.digest` event: `{state, runs, steps, cost: {usd, tokens}, waiting_reason?, since}`. `runs` counts the task's runs (sub-agents included), `steps` its model calls, and `since` is when the previous digest (or the task) was written. Send them to a [webhook](https://hexelstudio.com/docs/harness/webhooks) to hear from a long task without following it.

```bash
hexel harness task create "Watch the release" --agent watcher --checkin-every 6h
```

`inputs_from` is not available in a [zero-retention](https://hexelstudio.com/docs/harness/data-retention#zero-retention) environment (`409 inputs_from_unavailable`): the outputs it names are erased.
