---
title: "Fork a finished root run at a step into a new task"
url: https://hexelstudio.com/docs/api/harness/runs/fork
---

# Fork a finished root run at a step into a new task

**POST** `/harness/runs/{id}/fork`

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

- `step: integer`

- `instruction: optional string`

  A new instruction for the fork.

- `model: optional string`

  Another model the agent's bundle allows.

- `version: optional integer`

  Another version of the agent.

## Returns

`201` The forked task. (`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/runs/{id}/fork' \
  --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 '{
  "step": 0,
  "instruction": "string",
  "model": "string",
  "version": 0
}'
```

### 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"
}
```
