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

{
  "started": true
}

SDK Usage

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.

Parameters

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

Response

{
  "paused": true
}

SDK Usage

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

{
  "resumed": true
}

SDK Usage

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

{
  "stopped": true
}

SDK Usage

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

{
  "stopped": true
}

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

SDK Usage

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

{
  "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

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

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

SDK Usage

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

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

SDK Usage

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

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

SDK Usage

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

{
  "ok": true
}

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

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

SDK Usage

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

{
  "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

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)

{
  "max_project_spend_usd": 600
}

Response

{
  "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

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)

{
  "budget_usd": 75
}

Response

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

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

SDK Usage

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

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

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

SDK Usage

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