> Call the `diagnose` tool first. Full index: /llms.txt. Errors: /reference/problems.

# Runs and evidence

## `start_run`

Start a run and return at once with a run id, a cursor and a link to watch it.

Annotations: can change or delete data.

| Argument          | Type                                                                     | Required | What it is                     |
| ----------------- | ------------------------------------------------------------------------ | -------- | ------------------------------ |
| `app_id`          | `string`                                                                 | yes      |                                |
| `target`          | `WebRunTarget \| MobileRunTarget \| LiveMobileRunTarget`                 | yes      |                                |
| `selection`       | `ScenarioSelection \| SuiteSelection \| GoalSelection \| IssueSelection` | yes      |                                |
| `max_credits`     | `number \| string \| null`                                               | no       |                                |
| `request_id`      | `string`                                                                 | yes      |                                |
| `preview`         | `boolean`                                                                | no       |                                |
| `source_run_id`   | `string \| null`                                                         | no       |                                |
| `source_issue_id` | `string \| null`                                                         | no       |                                |
| `project_id`      | `string`                                                                 | yes      | The project the call is about. |

```json
{
  "$defs": {
    "BuildLabelSource": {
      "properties": {
        "kind": {
          "const": "build_label",
          "default": "build_label",
          "title": "Kind",
          "type": "string"
        },
        "label": {
          "maxLength": 128,
          "minLength": 1,
          "title": "Label",
          "type": "string"
        }
      },
      "required": [
        "label"
      ],
      "title": "BuildLabelSource",
      "type": "object"
    },
    "GoalSelection": {
      "description": "A goal in the developer's words. Navigation plans it for this run only; no managed scenario\nis created.",
      "properties": {
        "goal": {
          "minLength": 1,
          "title": "Goal",
          "type": "string"
        },
        "kind": {
          "const": "goal",
          "default": "goal",
          "title": "Kind",
          "type": "string"
        }
      },
      "required": [
        "goal"
      ],
      "title": "GoalSelection",
      "type": "object"
    },
    "IssueSelection": {
      "description": "Rerun the scenario an issue was raised on: the same frozen scenario version, from the\nstart, on the new target.",
      "properties": {
        "issue_id": {
          "minLength": 1,
          "title": "Issue Id",
          "type": "string"
        },
        "kind": {
          "const": "issue",
          "default": "issue",
          "title": "Kind",
          "type": "string"
        },
        "source_run_id": {
          "minLength": 1,
          "title": "Source Run Id",
          "type": "string"
        }
      },
      "required": [
        "source_run_id",
        "issue_id"
      ],
      "title": "IssueSelection",
      "type": "object"
    },
    "LiveMobileRunTarget": {
      "description": "The phone of a ``READY`` dev session the caller owns, as it is. The run borrows the\nsession's lease; the session is ``BUSY`` until the run ends.",
      "properties": {
        "code": {
          "anyOf": [
            {
              "$ref": "#/$defs/WorktreeCode"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "dev_session_id": {
          "minLength": 1,
          "title": "Dev Session Id",
          "type": "string"
        },
        "kind": {
          "const": "live_mobile",
          "default": "live_mobile",
          "title": "Kind",
          "type": "string"
        },
        "reset": {
          "$ref": "#/$defs/LiveRunReset",
          "default": "none"
        }
      },
      "required": [
        "dev_session_id"
      ],
      "title": "LiveMobileRunTarget",
      "type": "object"
    },
    "LiveRunReset": {
      "description": "What a live run resets on the borrowed phone before it starts.",
      "enum": [
        "none",
        "app_data"
      ],
      "title": "LiveRunReset",
      "type": "string"
    },
    "MobileRunTarget": {
      "description": "A mobile app build on a device profile.",
      "properties": {
        "build_id": {
          "anyOf": [
            {
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Build Id"
        },
        "device_profile": {
          "anyOf": [
            {
              "maxLength": 128,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Device Profile"
        },
        "kind": {
          "const": "mobile",
          "default": "mobile",
          "title": "Kind",
          "type": "string"
        }
      },
      "title": "MobileRunTarget",
      "type": "object"
    },
    "ScenarioExecutionPin": {
      "description": "Identity of the executable projection, distinct from an evaluation testcase revision.",
      "properties": {
        "revision": {
          "exclusiveMinimum": 0,
          "title": "Revision",
          "type": "integer"
        },
        "scenario_id": {
          "minLength": 1,
          "title": "Scenario Id",
          "type": "string"
        }
      },
      "required": [
        "scenario_id",
        "revision"
      ],
      "title": "ScenarioExecutionPin",
      "type": "object"
    },
    "ScenarioSelection": {
      "description": "These scenarios of the app.",
      "properties": {
        "kind": {
          "const": "scenarios",
          "default": "scenarios",
          "title": "Kind",
          "type": "string"
        },
        "reviewed": {
          "default": [],
          "items": {
            "$ref": "#/$defs/ScenarioExecutionPin"
          },
          "title": "Reviewed",
          "type": "array"
        },
        "scenario_ids": {
          "$ref": "#/$defs/UniqueTuple_Annotated_str__StringConstraints___MinLen_min_length_1_",
          "minLength": 1
        }
      },
      "required": [
        "scenario_ids"
      ],
      "title": "ScenarioSelection",
      "type": "object"
    },
    "SuiteSelection": {
      "description": "The app's scenarios in this Test Plan, as it stands at admission.",
      "properties": {
        "kind": {
          "const": "suite",
          "default": "suite",
          "title": "Kind",
          "type": "string"
        },
        "suite_id": {
          "minLength": 1,
          "title": "Suite Id",
          "type": "string"
        }
      },
      "required": [
        "suite_id"
      ],
      "title": "SuiteSelection",
      "type": "object"
    },
    "UniqueTuple_Annotated_str__StringConstraints___MinLen_min_length_1_": {
      "items": {
        "minLength": 1,
        "type": "string"
      },
      "type": "array"
    },
    "WebCodeProvenance": {
      "description": "What a web run's caller said it tested.",
      "properties": {
        "provenance": {
          "const": "caller_asserted",
          "default": "caller_asserted",
          "title": "Provenance",
          "type": "string"
        },
        "source": {
          "discriminator": {
            "mapping": {
              "build_label": "#/$defs/BuildLabelSource",
              "worktree": "#/$defs/WorktreeSource"
            },
            "propertyName": "kind"
          },
          "oneOf": [
            {
              "$ref": "#/$defs/WorktreeSource"
            },
            {
              "$ref": "#/$defs/BuildLabelSource"
            }
          ],
          "title": "Source"
        },
        "supplied_at": {
          "format": "date-time",
          "title": "Supplied At",
          "type": "string"
        }
      },
      "required": [
        "source",
        "supplied_at"
      ],
      "title": "WebCodeProvenance",
      "type": "object"
    },
    "WebRunTarget": {
      "description": "A web app, opened at ``start_url``: the developer's tunnel URL, for example.",
      "properties": {
        "code": {
          "anyOf": [
            {
              "$ref": "#/$defs/WebCodeProvenance"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "device_profile": {
          "anyOf": [
            {
              "maxLength": 128,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Device Profile"
        },
        "kind": {
          "const": "web",
          "default": "web",
          "title": "Kind",
          "type": "string"
        },
        "ports": {
          "default": [],
          "items": {
            "maximum": 65535,
            "minimum": 1,
            "type": "integer"
          },
          "title": "Ports",
          "type": "array"
        },
        "start_url": {
          "minLength": 1,
          "title": "Start Url",
          "type": "string"
        }
      },
      "required": [
        "start_url"
      ],
      "title": "WebRunTarget",
      "type": "object"
    },
    "WorktreeCode": {
      "description": "The code a working tree holds, as the CLI computes it on the developer's machine.",
      "properties": {
        "dirty_digest": {
          "title": "Dirty Digest",
          "type": "string"
        },
        "git_sha": {
          "title": "Git Sha",
          "type": "string"
        },
        "untracked_digest": {
          "title": "Untracked Digest",
          "type": "string"
        }
      },
      "required": [
        "git_sha",
        "dirty_digest",
        "untracked_digest"
      ],
      "title": "WorktreeCode",
      "type": "object"
    },
    "WorktreeSource": {
      "properties": {
        "code": {
          "$ref": "#/$defs/WorktreeCode"
        },
        "kind": {
          "const": "worktree",
          "default": "worktree",
          "title": "Kind",
          "type": "string"
        }
      },
      "required": [
        "code"
      ],
      "title": "WorktreeSource",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "description": "``start_run``: the Contracts request in its project, with a request id that is required.",
  "properties": {
    "app_id": {
      "minLength": 1,
      "title": "App Id",
      "type": "string"
    },
    "max_credits": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ],
          "gt": 0
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Max Credits"
    },
    "preview": {
      "default": false,
      "title": "Preview",
      "type": "boolean"
    },
    "project_id": {
      "description": "The project the call is about.",
      "minLength": 1,
      "title": "Project Id",
      "type": "string"
    },
    "request_id": {
      "maxLength": 128,
      "minLength": 1,
      "title": "Request Id",
      "type": "string"
    },
    "selection": {
      "discriminator": {
        "mapping": {
          "goal": "#/$defs/GoalSelection",
          "issue": "#/$defs/IssueSelection",
          "scenarios": "#/$defs/ScenarioSelection",
          "suite": "#/$defs/SuiteSelection"
        },
        "propertyName": "kind"
      },
      "oneOf": [
        {
          "$ref": "#/$defs/ScenarioSelection"
        },
        {
          "$ref": "#/$defs/SuiteSelection"
        },
        {
          "$ref": "#/$defs/GoalSelection"
        },
        {
          "$ref": "#/$defs/IssueSelection"
        }
      ],
      "title": "Selection"
    },
    "source_issue_id": {
      "anyOf": [
        {
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Source Issue Id"
    },
    "source_run_id": {
      "anyOf": [
        {
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Source Run Id"
    },
    "target": {
      "discriminator": {
        "mapping": {
          "live_mobile": "#/$defs/LiveMobileRunTarget",
          "mobile": "#/$defs/MobileRunTarget",
          "web": "#/$defs/WebRunTarget"
        },
        "propertyName": "kind"
      },
      "oneOf": [
        {
          "$ref": "#/$defs/WebRunTarget"
        },
        {
          "$ref": "#/$defs/MobileRunTarget"
        },
        {
          "$ref": "#/$defs/LiveMobileRunTarget"
        }
      ],
      "title": "Target"
    }
  },
  "required": [
    "app_id",
    "target",
    "selection",
    "request_id",
    "project_id"
  ],
  "title": "StartRunCall",
  "type": "object"
}
```

## `watch_run`

Follow a run by cursor; wait_seconds holds the call open for news.

Annotations: changes data, never deletes.

| Argument       | Type             | Required | What it is                     |
| -------------- | ---------------- | -------- | ------------------------------ |
| `run_id`       | `string`         | yes      |                                |
| `cursor`       | `string \| null` | no       |                                |
| `limit`        | `integer`        | no       |                                |
| `wait_seconds` | `integer`        | no       |                                |
| `project_id`   | `string`         | yes      | The project the call is about. |

```json
{
  "additionalProperties": false,
  "properties": {
    "cursor": {
      "anyOf": [
        {
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cursor"
    },
    "limit": {
      "default": 20,
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "project_id": {
      "description": "The project the call is about.",
      "minLength": 1,
      "title": "Project Id",
      "type": "string"
    },
    "run_id": {
      "minLength": 1,
      "title": "Run Id",
      "type": "string"
    },
    "wait_seconds": {
      "default": 0,
      "maximum": 25,
      "minimum": 0,
      "title": "Wait Seconds",
      "type": "integer"
    }
  },
  "required": [
    "run_id",
    "project_id"
  ],
  "title": "WatchRunCall",
  "type": "object"
}
```

## `cancel_run`

Cancel a run.

Annotations: can change or delete data.

| Argument     | Type     | Required | What it is                     |
| ------------ | -------- | -------- | ------------------------------ |
| `run_id`     | `string` | yes      |                                |
| `project_id` | `string` | yes      | The project the call is about. |

```json
{
  "additionalProperties": false,
  "properties": {
    "project_id": {
      "description": "The project the call is about.",
      "minLength": 1,
      "title": "Project Id",
      "type": "string"
    },
    "run_id": {
      "minLength": 1,
      "title": "Run Id",
      "type": "string"
    }
  },
  "required": [
    "run_id",
    "project_id"
  ],
  "title": "CancelRunCall",
  "type": "object"
}
```

## `read_evidence`

Read one page of a run's steps, requests, console lines or snapshots.

Annotations: reads only.

| Argument     | Type             | Required | What it is                     |
| ------------ | ---------------- | -------- | ------------------------------ |
| `run_id`     | `string`         | yes      |                                |
| `ref`        | `string \| null` | no       |                                |
| `filter`     | `EvidenceFilter` | no       |                                |
| `cursor`     | `string \| null` | no       |                                |
| `limit`      | `integer`        | no       |                                |
| `project_id` | `string`         | yes      | The project the call is about. |

```json
{
  "$defs": {
    "EvidenceFilter": {
      "description": "Narrows what ``read_evidence`` lists. Every field narrows; an empty filter lists all.",
      "properties": {
        "failed_only": {
          "default": false,
          "title": "Failed Only",
          "type": "boolean"
        },
        "kind": {
          "anyOf": [
            {
              "$ref": "#/$defs/EvidenceItemKind"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "step": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Step"
        }
      },
      "title": "EvidenceFilter",
      "type": "object"
    },
    "EvidenceItemKind": {
      "description": "What one evidence item is.",
      "enum": [
        "step",
        "issue",
        "network",
        "console",
        "snapshot",
        "file",
        "content",
        "link"
      ],
      "title": "EvidenceItemKind",
      "type": "string"
    }
  },
  "additionalProperties": false,
  "properties": {
    "cursor": {
      "anyOf": [
        {
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cursor"
    },
    "filter": {
      "$ref": "#/$defs/EvidenceFilter"
    },
    "limit": {
      "default": 20,
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "project_id": {
      "description": "The project the call is about.",
      "minLength": 1,
      "title": "Project Id",
      "type": "string"
    },
    "ref": {
      "anyOf": [
        {
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ref"
    },
    "run_id": {
      "minLength": 1,
      "title": "Run Id",
      "type": "string"
    }
  },
  "required": [
    "run_id",
    "project_id"
  ],
  "title": "ReadEvidenceCall",
  "type": "object"
}
```

## `compare_runs`

Show what a rerun changed against an earlier run.

Annotations: reads only.

| Argument           | Type             | Required | What it is                     |
| ------------------ | ---------------- | -------- | ------------------------------ |
| `baseline_run_id`  | `string`         | yes      |                                |
| `candidate_run_id` | `string`         | yes      |                                |
| `cursor`           | `string \| null` | no       |                                |
| `project_id`       | `string`         | yes      | The project the call is about. |

```json
{
  "additionalProperties": false,
  "properties": {
    "baseline_run_id": {
      "minLength": 1,
      "title": "Baseline Run Id",
      "type": "string"
    },
    "candidate_run_id": {
      "minLength": 1,
      "title": "Candidate Run Id",
      "type": "string"
    },
    "cursor": {
      "anyOf": [
        {
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cursor"
    },
    "project_id": {
      "description": "The project the call is about.",
      "minLength": 1,
      "title": "Project Id",
      "type": "string"
    }
  },
  "required": [
    "baseline_run_id",
    "candidate_run_id",
    "project_id"
  ],
  "title": "CompareRunsCall",
  "type": "object"
}
```