# Orchestration: Executor & Budget

**Page:** api/agent/orchestration/executor-budget

[Download Raw Markdown](./api/agent/orchestration/executor-budget.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## Orchestration: Executor & Budget

Control the agent orchestration dispatcher and enforce project-level budget limits. These endpoints let you start, pause, resume, and stop the executor's dispatch loop, manage individual worker sessions, inspect file locks, force dispatch cycles with diagnostics, and track per-entry spend against a global cap.

Use these endpoints when you need to intervene in a running orchestration workflow — for example, pausing dispatch to make manual code changes, locking a specific entry's budget so the orchestrator cannot reallocate it, or auditing how much each entry has spent.

---

## Executor Control

### `POST /api/v1/workspaces/{workspaceID}/orchestration/executor/start`

Start the executor dispatch loop for the workspace. Once started, the executor begins picking up eligible entries and assigning worker sessions.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

#### Response



```json
{
  "started": true
}
```



#### SDK Usage

```ts
await client.agent.orchestration.executorStart({
  workspaceID: "ws_8f3a2b1c9d4e5f6a"
});
```

---

### `POST /api/v1/workspaces/{workspaceID}/orchestration/executor/pause`

Pause executor dispatching. In-flight workers continue running, but no new dispatches will occur until you call [resume](#post-apiv1workspacesworkspaceidorchestrationexecutorsume).

#### Parameters



| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | workspaceID path parameter |


#### Response



```json
{
  "paused": true
}
```



#### SDK Usage

```ts
await client.agent.orchestration.executorPause({
  workspaceID: "ws_8f3a2b1c9d4e5f6a"
});
```

---

### `POST /api/v1/workspaces/{workspaceID}/orchestration/executor/resume`

Resume executor dispatching after a previous pause.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

#### Response



```json
{
  "resumed": true
}
```



#### SDK Usage

```ts
await client.agent.orchestration.executorResume({
  workspaceID: "ws_8f3a2b1c9d4e5f6a"
});
```

---

### `POST /api/v1/workspaces/{workspaceID}/orchestration/executor/stop-all`

Stop all active worker sessions and pause the executor. Useful as an emergency stop when something is going wrong and you need to halt all activity immediately.

#### Parameters



| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | workspaceID path parameter |


#### Response



```json
{
  "stopped": true
}
```



#### SDK Usage

```ts
await client.agent.orchestration.executorStopAll({
  workspaceID: "ws_8f3a2b1c9d4e5f6a"
});
```

---

### `POST /api/v1/workspaces/{workspaceID}/orchestration/executor/workers/{sessionID}/stop`

Stop a specific worker session by its session ID. The executor remains in its current state (paused or running) — this only terminates the targeted session.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |
| `sessionID` | path | string | Yes | Worker session identifier to stop |

#### Response



```json
{
  "stopped": true
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Worker session not found"
  }
}
```



#### SDK Usage

```ts
await client.agent.orchestration.executorStopWorker({
  workspaceID: "ws_8f3a2b1c9d4e5f6a",
  sessionID: "sess_4j6h8g2f1d9s7a5b"
});
```

---

### `POST /api/v1/workspaces/{workspaceID}/orchestration/executor/force-dispatch`

Force an immediate dispatch cycle regardless of schedule, and return detailed diagnostics about the executor's internal state. Useful for debugging stuck workflows.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

#### Response



```json
{
  "dispatched": true,
  "diagnostics": {
    "state": "running",
    "paused": false,
    "initialized": true,
    "trackedSessions": 3,
    "activeSessions": 2,
    "dispatchingCount": 1,
    "entries": {
      "total": 12,
      "pending": 4,
      "blocked": 1,
      "inProgress": 2,
      "done": 4,
      "failed": 1
    },
    "readyToDispatch": 3,
    "blockedReasons": [
      "budget_exceeded"
    ]
  }
}
```



#### SDK Usage

```ts
await client.agent.orchestration.executorForceDispatch({
  workspaceID: "ws_8f3a2b1c9d4e5f6a"
});
```

---

## Executor Status & Inspection

### `GET /api/v1/workspaces/{workspaceID}/orchestration/executor/status`

Get the current executor state and the number of active workers.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

#### Response



```json
{
  "state": "running",
  "paused": false,
  "activeWorkers": 2
}
```



#### SDK Usage

```ts
const status = await client.agent.orchestration.executorGetStatus({
  workspaceID: "ws_8f3a2b1c9d4e5f6a"
});
```

---

### `GET /api/v1/workspaces/{workspaceID}/orchestration/executor/workers`

List all active worker sessions along with their entry assignments and current phase/status.

#### Parameters



| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | workspaceID path parameter |


#### Response



```json
{
  "workers": [
    {
      "sessionID": "sess_4j6h8g2f1d9s7a5b",
      "entryID": "entry_7k9m2n4p8q1r3s5t",
      "phase": "implementation",
      "status": "running"
    },
    {
      "sessionID": "sess_2b4d6f8h1j3l5n7p",
      "entryID": "entry_9r1s3t5u7w9y1a3c",
      "phase": "verification",
      "status": "running"
    }
  ]
}
```



#### SDK Usage

```ts
const { workers } = await client.agent.orchestration.executorGetWorkers({
  workspaceID: "ws_8f3a2b1c9d4e5f6a"
});
```

---

### `GET /api/v1/workspaces/{workspaceID}/orchestration/executor/locks`

Get the current set of file locks held per entry. Locks prevent concurrent workers from editing the same files.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

#### Response



```json
{
  "entry_7k9m2n4p8q1r3s5t": [
    "src/api/handlers.ts",
    "src/api/types.ts"
  ],
  "entry_9r1s3t5u7w9y1a3c": [
    "src/utils/validation.ts"
  ]
}
```



#### SDK Usage

```ts
const locks = await client.agent.orchestration.executorGetLocks({
  workspaceID: "ws_8f3a2b1c9d4e5f6a"
});
```

---

### `POST /api/v1/workspaces/{workspaceID}/orchestration/executor/entries/{entryID}/reverify`

Re-run verification only, skipping the worker implementation phase. Resets `rounds_completed` and triggers verification using the last worker session's output. Useful when code was manually fixed outside the worker loop.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |
| `entryID` | path | string | Yes | Entry identifier to reverify |

#### Response



```json
{
  "ok": true
}
```


```json
{
  "data": {},
  "errors": [
    {
      "propertyNames": ["entryID"],
      "message": "Entry has no prior worker session to reverify"
    }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Entry not found"
  }
}
```



#### SDK Usage

```ts
const result = await client.agent.orchestration.executorReverifyEntry({
  workspaceID: "ws_8f3a2b1c9d4e5f6a",
  entryID: "entry_7k9m2n4p8q1r3s5t"
});
```

---

## Budget Management

### `GET /api/v1/workspaces/{workspaceID}/orchestration/budget`

Get the global budget status including the overall cap, total spent, and a per-entry breakdown of spend, budget, and round-level costs.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

#### Response



```json
{
  "global": {
    "total_budget_usd": 500,
    "max_project_spend_usd": 450,
    "entries_spent_usd": 187.42,
    "orchestrator_spent_usd": 23.18,
    "expansion_spent_usd": 8.55,
    "interceptor_spent_usd": 4.12,
    "total_spent_usd": 223.27
  },
  "entries": [
    {
      "entryID": "entry_7k9m2n4p8q1r3s5t",
      "budget_usd": 50,
      "budget_human_locked": true,
      "spent_usd": 47.83,
      "interceptor_spent_usd": 1.21,
      "rounds": [
        {
          "round": 1,
          "cost": 12.34,
          "improvement_score": 0.42
        },
        {
          "round": 2,
          "cost": 15.67,
          "improvement_score": 0.31
        },
        {
          "round": 3,
          "cost": 19.82,
          "improvement_score": 0.18
        }
      ]
    }
  ]
}
```



#### SDK Usage

```ts
const budget = await client.agent.orchestration.budgetGetStatus({
  workspaceID: "ws_8f3a2b1c9d4e5f6a"
});
```

---

### `PATCH /api/v1/workspaces/{workspaceID}/orchestration/budget`

Update the global budget — specifically the `max_project_spend_usd` ceiling that caps the total spend across the entire workspace.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

#### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `max_project_spend_usd` | number | Yes | New maximum project spend in USD (must be `≥` 0) |

```json
{
  "max_project_spend_usd": 600
}
```

#### Response



```json
{
  "total_budget_usd": 500,
  "max_project_spend_usd": 600,
  "entries_spent_usd": 187.42,
  "orchestrator_spent_usd": 23.18,
  "expansion_spent_usd": 8.55,
  "interceptor_spent_usd": 4.12,
  "total_spent_usd": 223.27
}
```



#### SDK Usage

```ts
const updated = await client.agent.orchestration.budgetUpdateGlobal({
  workspaceID: "ws_8f3a2b1c9d4e5f6a",
  data: {
    max_project_spend_usd: 600
  }
});
```

---

### `PATCH /api/v1/workspaces/{workspaceID}/orchestration/budget/entries/{entryID}`

Edit the budget for a specific entry. Setting a new budget also sets `budget_human_locked` to `true`, preventing the orchestrator from automatically reallocating the entry's spend.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |
| `entryID` | path | string | Yes | Entry identifier |

#### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `budget_usd` | number | Yes | New budget for the entry in USD (must be `≥` 0) |

```json
{
  "budget_usd": 75
}
```

#### Response



```json
{
  "entryID": "entry_7k9m2n4p8q1r3s5t",
  "budget_usd": 75,
  "locked": true
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Entry not found"
  }
}
```



#### SDK Usage

```ts
const result = await client.agent.orchestration.budgetEdit({
  workspaceID: "ws_8f3a2b1c9d4e5f6a",
  entryID: "entry_7k9m2n4p8q1r3s5t",
  data: {
    budget_usd: 75
  }
});
```

---

### `POST /api/v1/workspaces/{workspaceID}/orchestration/budget/entries/{entryID}/lock`

Toggle the `budget_human_locked` flag on an entry. When locked, the orchestrator will not automatically adjust the entry's budget allocation.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |
| `entryID` | path | string | Yes | Entry identifier |

#### Response



```json
{
  "entryID": "entry_7k9m2n4p8q1r3s5t",
  "locked": true
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Entry not found"
  }
}
```



#### SDK Usage

```ts
const result = await client.agent.orchestration.budgetLock({
  workspaceID: "ws_8f3a2b1c9d4e5f6a",
  entryID: "entry_7k9m2n4p8q1r3s5t"
});
```


The `getLocks` endpoint returns file locks (concurrency control), while the `budgetLock` endpoint toggles budget locks (spend control). Despite the similar name, they govern different concerns.