> ## Documentation Index
> Fetch the complete documentation index at: https://mx-6c34bcc6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Runs API — Submit and Orchestrate Multi-Agent Runs

> Submit multi-agent RunSubmitSpec payloads, kick off queued execution, poll per-step progress, retrieve aggregated results, and export knowledge bundles.

The Runs API orchestrates multi-agent workflows through the WattSwarm run queue. A **run** groups multiple agent steps (each backed by an executor) that all operate on the same shared inputs. Once a run finishes, the kernel aggregates the individual results — resolving ties and null outputs according to the configured policy — and produces a single `final_decision`. Runs are the recommended way to leverage multiple independent agents for higher-confidence swarm decisions.

***

## POST /api/run/submit

Submits a `RunSubmitSpec` and registers the run in the queue. By default the run starts in `CREATED` state; pass `"kickoff": true` in the envelope form to also transition all steps to `QUEUED` immediately.

```bash theme={null}
POST /api/run/submit
```

The endpoint accepts the spec either as a bare `RunSubmitSpec` object or wrapped in an envelope:

```json theme={null}
{
  "kickoff": true,
  "spec": { ... }
}
```

<ParamField body="run_id" type="string" required>
  Stable identifier for this run. Use a UUID or a deterministic slug.
</ParamField>

<ParamField body="task_type" type="string">
  Task type string passed to each executor step. Defaults to `"generic.v1"`.
</ParamField>

<ParamField body="shared_inputs" type="object">
  JSON inputs shared across all agent steps in the run.
</ParamField>

<ParamField body="agents" type="object[]" required>
  List of agent step specifications.

  <Expandable title="agent fields">
    <ParamField body="agent_id" type="string" required>
      Unique identifier for this agent within the run.
    </ParamField>

    <ParamField body="executor" type="string" required>
      Name of the registered executor that will handle this step.
    </ParamField>

    <ParamField body="profile" type="string">
      Executor profile to use. Defaults to `"default"`.
    </ParamField>

    <ParamField body="prompt" type="string" required>
      Prompt or instruction string sent to the executor for this step.
    </ParamField>

    <ParamField body="weight" type="number">
      Relative weight for confidence-weighted aggregation. Defaults to `1.0`.
    </ParamField>

    <ParamField body="priority" type="integer">
      Step scheduling priority. Higher values are dequeued first. Defaults to `0`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="retry" type="object">
  Retry policy applied to failed steps.

  <Expandable title="retry fields">
    <ParamField body="max_attempts" type="integer">
      Maximum execution attempts per step. Defaults to `2`.
    </ParamField>

    <ParamField body="backoff_ms" type="integer">
      Milliseconds to wait between retry attempts. Defaults to `1500`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="aggregation" type="object">
  Controls how individual step results are combined into a final decision.

  <Expandable title="aggregation fields">
    <ParamField body="mode" type="string">
      Aggregation trigger: `"all_done"` (default) — finalize once all steps complete.
    </ParamField>

    <ParamField body="quorum" type="integer">
      Minimum number of agreeing results required for a positive decision.
    </ParamField>
  </Expandable>
</ParamField>

**Complete RunSubmitSpec example:**

```json theme={null}
{
  "run_id": "run-2024-demo-001",
  "task_type": "generic.qa.v1",
  "shared_inputs": {
    "question": "What is the capital of France?"
  },
  "agents": [
    {
      "agent_id": "agent-alpha",
      "executor": "local-agent",
      "profile": "default",
      "prompt": "Answer the question concisely with high confidence.",
      "weight": 1.0,
      "priority": 0
    },
    {
      "agent_id": "agent-beta",
      "executor": "local-agent",
      "profile": "detailed",
      "prompt": "Answer the question with supporting evidence.",
      "weight": 1.5,
      "priority": 0
    }
  ],
  "retry": {
    "max_attempts": 2,
    "backoff_ms": 1500
  },
  "aggregation": {
    "mode": "all_done",
    "quorum": 2
  }
}
```

**Example request:**

```bash theme={null}
curl -X POST http://127.0.0.1:7788/api/run/submit \
  -H "Content-Type: application/json" \
  -d '{
    "kickoff": true,
    "spec": {
      "run_id": "run-2024-demo-001",
      "task_type": "generic.qa.v1",
      "shared_inputs": { "question": "What is the capital of France?" },
      "agents": [
        { "agent_id": "agent-alpha", "executor": "local-agent", "profile": "default", "prompt": "Answer concisely." }
      ]
    }
  }'
```

**Example response:**

```json theme={null}
{
  "ok": true,
  "run_id": "run-2024-demo-001"
}
```

***

## POST /api/run/kickoff/:run\_id

Transitions the run and all its constituent steps from `CREATED` to `QUEUED`, making them eligible for executor pickup. Call this after `/api/run/submit` if you did not pass `"kickoff": true` at submit time, or if you want to delay execution start.

```bash theme={null}
POST /api/run/kickoff/:run_id
```

**Path parameters:**

<ParamField path="run_id" type="string" required>
  The run identifier returned by `/api/run/submit`.
</ParamField>

**Example request:**

```bash theme={null}
curl -X POST http://127.0.0.1:7788/api/run/kickoff/run-2024-demo-001
```

**Example response:**

```json theme={null}
{
  "ok": true,
  "run_id": "run-2024-demo-001"
}
```

***

## GET /api/run/watch/:run\_id

Polls the current status of a run, including step-level counts broken down by state. Call this endpoint periodically until `status` reaches `SUCCEEDED`, `FAILED`, or `CANCELLED`.

```bash theme={null}
GET /api/run/watch/:run_id
```

**Path parameters:**

<ParamField path="run_id" type="string" required>
  The run identifier.
</ParamField>

**Example request:**

```bash theme={null}
curl http://127.0.0.1:7788/api/run/watch/run-2024-demo-001
```

**Example response:**

```json theme={null}
{
  "ok": true,
  "watch": {
    "run_id": "run-2024-demo-001",
    "status": "LEASED",
    "task_type": "generic.qa.v1",
    "created_at": 1718000000000,
    "updated_at": 1718000005000,
    "started_at": 1718000001000,
    "finished_at": null,
    "counts": {
      "created": 0,
      "queued": 0,
      "leased": 1,
      "succeeded": 1,
      "failed": 0,
      "retry_wait": 0,
      "cancelled": 0,
      "remote_dispatched": 0
    }
  }
}
```

**Response fields:**

<ResponseField name="watch.run_id" type="string">
  The run identifier.
</ResponseField>

<ResponseField name="watch.status" type="string">
  Overall run status: `CREATED`, `QUEUED`, `LEASED`, `SUCCEEDED`, `FAILED`, or `CANCELLED`.
</ResponseField>

<ResponseField name="watch.counts" type="object">
  Step-level counts by state. `remote_dispatched` tracks steps sent to remote nodes awaiting gossip results.
</ResponseField>

***

## GET /api/run/result/:run\_id

Returns the aggregated final result of a completed run, including the final decision, final answer, and per-step conclusions.

```bash theme={null}
GET /api/run/result/:run_id
```

**Path parameters:**

<ParamField path="run_id" type="string" required>
  The run identifier.
</ParamField>

**Example request:**

```bash theme={null}
curl http://127.0.0.1:7788/api/run/result/run-2024-demo-001
```

**Example response:**

```json theme={null}
{
  "ok": true,
  "result": {
    "run_id": "run-2024-demo-001",
    "status": "SUCCEEDED",
    "final_decision": "Paris",
    "final_answer": "Paris is the capital of France.",
    "steps": [
      {
        "step_id": "step-agent-alpha-001",
        "agent_id": "agent-alpha",
        "status": "SUCCEEDED",
        "conclusion": "Paris",
        "confidence": 0.98,
        "attempt": 1
      },
      {
        "step_id": "step-agent-beta-001",
        "agent_id": "agent-beta",
        "status": "SUCCEEDED",
        "conclusion": "Paris",
        "confidence": 0.97,
        "attempt": 1
      }
    ],
    "aggregation": {
      "resolution_paths": ["quorum_match"]
    }
  }
}
```

<ResponseField name="result.final_decision" type="string | null">
  The aggregated decision value. `null` if the run did not produce a conclusive result.
</ResponseField>

<ResponseField name="result.final_answer" type="string | null">
  The long-form answer string, if the executor returned one.
</ResponseField>

<ResponseField name="result.steps" type="object[]">
  Per-step outcome details including conclusion, confidence, and attempt number.
</ResponseField>

<ResponseField name="result.aggregation.resolution_paths" type="string[]">
  List of resolution strategies that were applied (e.g. `"quorum_match"`, `"confidence_weighted"`, `"stochastic"`).
</ResponseField>

***

## GET /api/run/events/:run\_id

Returns the structured event log for a run. Useful for debugging step transitions, retries, and aggregation decisions.

```bash theme={null}
GET /api/run/events/:run_id?limit=50
```

**Path parameters:**

<ParamField path="run_id" type="string" required>
  The run identifier.
</ParamField>

**Query parameters:**

<ParamField query="limit" type="integer">
  Maximum number of events to return. Defaults to `50`; minimum `1`.
</ParamField>

**Example request:**

```bash theme={null}
curl "http://127.0.0.1:7788/api/run/events/run-2024-demo-001?limit=20"
```

**Example response:**

```json theme={null}
{
  "ok": true,
  "events": [
    {
      "id": 1,
      "run_id": "run-2024-demo-001",
      "event_type": "run_created",
      "payload": {},
      "created_at": 1718000000000
    },
    {
      "id": 2,
      "run_id": "run-2024-demo-001",
      "event_type": "step_queued",
      "payload": { "step_id": "step-agent-alpha-001", "agent_id": "agent-alpha" },
      "created_at": 1718000001000
    }
  ]
}
```

***

## POST /api/run/cancel/:run\_id

Cancels an active run. Any steps in `QUEUED` or `CREATED` state are moved to `CANCELLED`. Steps currently leased are allowed to finish but their results are discarded.

```bash theme={null}
POST /api/run/cancel/:run_id
```

**Path parameters:**

<ParamField path="run_id" type="string" required>
  The run identifier.
</ParamField>

**Example request:**

```bash theme={null}
curl -X POST http://127.0.0.1:7788/api/run/cancel/run-2024-demo-001
```

**Example response:**

```json theme={null}
{
  "ok": true,
  "run_id": "run-2024-demo-001"
}
```

***

## POST /api/run/retry/:run\_id

Retries a failed run by re-queuing its failed steps from the beginning. Steps that already succeeded are not re-executed.

```bash theme={null}
POST /api/run/retry/:run_id
```

**Path parameters:**

<ParamField path="run_id" type="string" required>
  The run identifier.
</ParamField>

**Example request:**

```bash theme={null}
curl -X POST http://127.0.0.1:7788/api/run/retry/run-2024-demo-001
```

**Example response:**

```json theme={null}
{
  "ok": true,
  "run_id": "run-2024-demo-001"
}
```

***

## POST /api/knowledge/export

Exports a knowledge bundle from the kernel store. A knowledge bundle contains the decision records, evidence references, and reuse metrics accumulated for a given task type or specific task ID. Provide exactly one of `task_type` or `task_id`.

```bash theme={null}
POST /api/knowledge/export
```

<ParamField body="task_type" type="string">
  Export all knowledge records associated with this task type string (e.g. `"generic.qa.v1"`). Mutually exclusive with `task_id`.
</ParamField>

<ParamField body="task_id" type="string">
  Export knowledge records for a single specific task. Mutually exclusive with `task_type`.
</ParamField>

**Example request:**

```bash theme={null}
curl -X POST http://127.0.0.1:7788/api/knowledge/export \
  -H "Content-Type: application/json" \
  -d '{ "task_type": "generic.qa.v1" }'
```

**Example response:**

```json theme={null}
{
  "ok": true,
  "knowledge": {
    "task_type": "generic.qa.v1",
    "records": [
      {
        "task_id": "task-demo-001",
        "finalized_at": 1718000010000,
        "decision_value": "Paris",
        "confidence": 0.98,
        "evidence_count": 2,
        "reuse_attempts": 0,
        "reuse_successes": 0
      }
    ]
  }
}
```

<Note>
  Knowledge bundles are useful for fine-tuning prompts, auditing swarm consensus quality, and bootstrapping new nodes with historical decision context.
</Note>