HTTP API

Sortie embeds an HTTP server that exposes a JSON API, a stream of change signals and agent events, a browser dashboard, health probes, and Prometheus metrics, all on a single port.

Server configuration

The HTTP server starts by default on 127.0.0.1:7678 with no flags required.

Override the port: pass --port <N> when launching Sortie:

sortie --port 9090 WORKFLOW.md

Override the bind address: pass --host <ADDR> for container deployments:

sortie --host 0.0.0.0 WORKFLOW.md

Workflow config: set server.port and server.host in the WORKFLOW.md front matter extensions:

---
server:
  port: 9090
  host: "0.0.0.0"
# ... rest of config
---

CLI flags take precedence over extension keys. Port 0 disables the server entirely (no TCP listener, no Prometheus metrics). --host must be a parseable IP address; DNS hostnames are not accepted.

When the default port (7678) is already occupied and no port was explicitly requested, Sortie logs a warning and starts without the HTTP server. When an explicit port is in use, Sortie exits with code 1.

The HTTP server is not started in --dry-run mode. Changing the port or host requires a restart: there is no hot-rebind.

For the full server extension schema, see WORKFLOW.md configuration reference. For Prometheus metric definitions, see Prometheus metrics reference.

GET /: Dashboard redirect

Redirects to the dashboard.

curl -i http://localhost:7678/

Returns 302 Found with Location: /ui/ and no body. The redirect is temporary, so browsers do not cache it.

GET /ui/: Dashboard

Serves the dashboard, a single-page application compiled into the Sortie binary. The dashboard reference describes what it shows.

curl -i http://localhost:7678/ui/

Every path under /ui/ that is not a script or stylesheet returns the same HTML document, so a screen address such as /ui/issues/MT-649 can be opened directly or bookmarked. The application reads its data from the JSON routes on this page and from the event stream.

Every response carries X-Content-Type-Options: nosniff and a Content-Security-Policy that allows only same-origin scripts, styles, and connections, and forbids framing.

The route accepts GET and HEAD. Sortie’s HTTP server has no authentication, so anyone who can reach the port can open the dashboard and use its actions. A deployment that others can reach must sit behind a reverse proxy with authentication or a VPN.

GET /api/v1/state: System state

Returns a full runtime snapshot: running sessions, retry queue, budget-exhausted and parked issues, pending pull request reactions, issues between stages, one entry per active issue in a stable order, the list of what needs a person, aggregate totals, rate limits, the workflow configuration in effect, the health of Sortie’s own checks, the Sortie version, and the time the process started.

curl http://localhost:7678/api/v1/state

Response

{
  "generated_at": "2026-03-26T14:30:00Z",
  "version": "1.19.0",
  "started_at": "2026-03-26T13:28:10Z",
  "counts": {
    "running": 1,
    "retrying": 1,
    "budget_exhausted": 1,
    "parked": 1,
    "pending_reactions": 2,
    "between_stages": 1,
    "attention": 4
  },
  "running": [
    {
      "issue_id": "abc123",
      "issue_identifier": "MT-649",
      "issue_title": "Fix the flaky login test",
      "issue_url": "https://tracker.example.com/browse/MT-649",
      "issue_labels": ["bug", "backend"],
      "issue_type": "Bug",
      "state": "In Progress",
      "session_id": "session-abc-001",
      "turn_count": 7,
      "self_review_active": false,
      "self_review_iteration": 0,
      "last_event": "turn_completed",
      "last_message": "",
      "started_at": "2026-03-26T14:10:12Z",
      "dispatched_at": "2026-03-26T13:41:08Z",
      "last_event_at": "2026-03-26T14:29:59Z",
      "workspace_path": "/tmp/sortie_workspaces/MT-649",
      "tokens": {
        "input_tokens": 12500,
        "output_tokens": 3200,
        "total_tokens": 15700,
        "cache_read_tokens": 8400,
        "cache_write_tokens": 1200
      },
      "model_name": "<model-id-reported-by-the-agent>",
      "rule_name": "bugfix",
      "stage_lineage": null,
      "stage_position": null,
      "configured_model": "claude-sonnet-4-5",
      "configured_effort": "medium",
      "workflow_file": "WORKFLOW.md",
      "agent_kind": "claude-code",
      "api_request_count": 12,
      "requests_by_model": {
        "<model-id-reported-by-the-agent>": 12
      },
      "tool_time_percent": 34.7,
      "api_time_percent": 51.2,
      "tokens_measured": true,
      "usage_arrival": "incremental",
      "usage_attribution": "per_model",
      "tokens_pending": false,
      "tokens_awaited": false,
      "api_requests_measured": true,
      "used_sessions": 2,
      "budget_sessions": 5,
      "issue_tokens_completed": 105000,
      "unmeasured_sessions": 0,
      "used_tokens": 120700,
      "used_tokens_complete": true,
      "budget_tokens": 500000,
      "estimated_cost_usd": 0.06372,
      "cost_status": "estimated",
      "issue_estimated_cost_usd": 0.49872,
      "issue_cost_status": "estimated",
      "status_text": "Turn 7",
      "status_text_full": "Running, turn 7.",
      "dispatch_id": "RLQFSIOFERWGDW2HZY45W55VXK",
      "quiet_at": "2026-03-26T14:32:29Z",
      "stall_at": "2026-03-26T14:34:59Z",
      "stall_text": null,
      "stall_text_full": null,
      "stall_off_text": null
    }
  ],
  "retrying": [
    {
      "issue_id": "def456",
      "issue_identifier": "MT-650",
      "issue_title": "Retry the export job",
      "issue_url": "https://tracker.example.com/browse/MT-650",
      "issue_type": "Task",
      "issue_labels": ["export"],
      "state": "In Progress",
      "dispatched_at": "2026-03-26T14:02:41Z",
      "attempt": 3,
      "due_at": "2026-03-26T14:35:00Z",
      "error": "no available orchestrator slots",
      "trigger": "timer",
      "rule_name": "implement",
      "agent_kind": "claude-code",
      "configured_model": "claude-sonnet-4-5",
      "stage_lineage": {
        "chain_id": "7q2m4x9b1k5d8f3h6j0n2p4rst",
        "previous": "specify",
        "previous_outcome": "succeeded"
      },
      "stage_position": {
        "chain": ["specify", "implement"],
        "current": "implement",
        "hop_count": 1,
        "hop_ceiling": 10
      },
      "paused": false,
      "status_text": "Retry 3 in 5m: no agent slot was free",
      "status_text_full": "The retry came due and was not dispatched: no agent slot was free. Retry 3 in 5m."
    }
  ],
  "budget_exhausted": [
    {
      "issue_id": "ghi789",
      "issue_identifier": "MT-651",
      "issue_title": "Migrate the billing tables",
      "issue_url": "https://tracker.example.com/browse/MT-651",
      "issue_type": "Task",
      "issue_labels": [],
      "state": "In Progress",
      "dispatched_at": "2026-03-26T13:31:07Z",
      "reason": "session_budget",
      "used_sessions": 3,
      "budget_sessions": 3,
      "used_tokens": null,
      "budget_tokens": null,
      "unmeasured_sessions": null,
      "stopped_in_flight": null,
      "exhausted_at": "2026-03-26T14:12:00Z",
      "stage_lineage": null,
      "stage_position": null,
      "agent_kind": "claude-code",
      "configured_model": "claude-sonnet-4-5",
      "status_text": "Held: session budget reached",
      "status_text_full": "Held at the session budget of 3. Sessions used: 3."
    }
  ],
  "parked": [
    {
      "issue_id": "jkl012",
      "issue_identifier": "MT-652",
      "issue_title": "Rotate the signing keys",
      "issue_url": "https://tracker.example.com/browse/MT-652",
      "issue_type": "Task",
      "issue_labels": ["security"],
      "state": "In Progress",
      "dispatched_at": "2026-03-26T13:41:20Z",
      "reason": "agent_blocked",
      "parked_state": "In Progress",
      "label": "needs-human",
      "label_applied": true,
      "parked_at": "2026-03-26T14:05:00Z",
      "rule_name": "bugfix",
      "stage_position": null,
      "agent_kind": "claude-code",
      "configured_model": "claude-sonnet-4-5",
      "status_text": "Parked: the agent needs a person",
      "status_text_full": "Parked: the agent stopped because it cannot go on without a person. Parking label: `needs-human`."
    }
  ],
  "pending_reactions": [
    {
      "issue_id": "mno345",
      "issue_identifier": "MT-653",
      "issue_title": "Add the export button",
      "issue_url": "https://tracker.example.com/browse/MT-653",
      "issue_type": "Story",
      "issue_labels": ["export"],
      "state": "In Review",
      "kind": "ci",
      "config_key": "ci_failure",
      "pull_request": {
        "number": 931,
        "repository": "acme/web",
        "url": "https://github.com/acme/web/pull/931",
        "branch": "sortie/MT-653",
        "head_sha": "4f1c2a9e8b7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b"
      },
      "created_at": "2026-03-26T14:09:30Z",
      "dispatched_at": "2026-03-26T13:58:03Z",
      "next_poll_at": "2026-03-26T14:31:40Z",
      "wait": "poll_interval",
      "used_attempts": 2,
      "max_attempts": 2,
      "escalated_at": "2026-03-26T14:26:40Z",
      "escalation_trigger": "budget_exhausted",
      "watch_ends_at": null,
      "last_check": {
        "observed_at": "2026-03-26T14:26:40Z",
        "head_sha": "9b7e3d1c0a2f4e6b8d0c1a3e5f7b9d2c4e6a8f0b",
        "status": "failing",
        "failing_checks": ["Test"],
        "failing": 1,
        "pending": 0,
        "passing": 4
      },
      "rule_name": "implement",
      "stage_position": {
        "chain": ["specify", "implement"],
        "current": "implement",
        "hop_count": 1,
        "hop_ceiling": 10
      },
      "agent_kind": "claude-code",
      "configured_model": "claude-sonnet-4-5",
      "status_text": "CI escalated on #931",
      "status_text_full": "Sortie escalated failing CI on PR #931; it keeps watching the pull request. CI fixes used: 2 of 2."
    },
    {
      "issue_id": "mno345",
      "issue_identifier": "MT-653",
      "issue_title": "Add the export button",
      "issue_url": "https://tracker.example.com/browse/MT-653",
      "issue_type": "Story",
      "issue_labels": ["export"],
      "state": "In Review",
      "kind": "review",
      "config_key": "review_comments",
      "pull_request": {
        "number": 931,
        "repository": "acme/web",
        "url": "https://github.com/acme/web/pull/931",
        "branch": "sortie/MT-653",
        "head_sha": "4f1c2a9e8b7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b"
      },
      "created_at": "2026-03-26T14:09:30Z",
      "dispatched_at": "2026-03-26T13:58:03Z",
      "next_poll_at": "2026-03-26T14:30:55Z",
      "wait": "debounce",
      "used_attempts": 1,
      "max_attempts": 3,
      "escalated_at": null,
      "watch_ends_at": "2026-03-26T14:39:30Z",
      "last_check": {
        "observed_at": "2026-03-26T14:29:58Z",
        "actionable_comments": 3,
        "new_comments": 1
      },
      "rule_name": "implement",
      "stage_position": {
        "chain": ["specify", "implement"],
        "current": "implement",
        "hop_count": 1,
        "hop_ceiling": 10
      },
      "agent_kind": "claude-code",
      "configured_model": "claude-sonnet-4-5",
      "status_text": "1 new review comment on #931; next check in 55s",
      "status_text_full": "Waiting for 1 new review comment on PR #931 (3 actionable) to settle; next check in 55s. Review fix runs used: 1 of 3."
    }
  ],
  "between_stages": [
    {
      "issue_id": "stu901",
      "issue_identifier": "MT-655",
      "issue_title": "Plan the export schema",
      "issue_url": "https://tracker.example.com/browse/MT-655",
      "issue_type": "Story",
      "issue_labels": ["export", "stage-implement"],
      "state": "In Progress",
      "source_rule": "specify",
      "target_rule": "implement",
      "target_label": "stage-implement",
      "hopped_at": "2026-03-26T14:28:15Z",
      "dispatched_at": "2026-03-26T14:03:41Z",
      "rule_name": "implement",
      "stage_position": {
        "chain": ["specify", "implement"],
        "current": "implement",
        "hop_count": 1,
        "hop_ceiling": 10
      },
      "agent_kind": "claude-code",
      "configured_model": "claude-sonnet-4-5",
      "status_text": "Between stages: specify to implement",
      "status_text_full": "Moved from stage specify to stage implement, and Sortie added `stage-implement`; implement starts when a poll tick reads that label on the issue."
    }
  ],
  "active": [
    {
      "issue_id": "ghi789",
      "issue_identifier": "MT-651",
      "issue_title": "Migrate the billing tables",
      "issue_url": "https://tracker.example.com/browse/MT-651",
      "status": "budget_exhausted",
      "stage_position": null,
      "agent_kind": "claude-code",
      "configured_model": "claude-sonnet-4-5",
      "dispatched_at": "2026-03-26T13:31:07Z",
      "status_text": "Held: session budget reached",
      "status_text_full": "Held at the session budget of 3. Sessions used: 3."
    },
    {
      "issue_id": "abc123",
      "issue_identifier": "MT-649",
      "issue_title": "Fix the flaky login test",
      "issue_url": "https://tracker.example.com/browse/MT-649",
      "status": "running",
      "rule_name": "bugfix",
      "stage_position": null,
      "agent_kind": "claude-code",
      "configured_model": "claude-sonnet-4-5",
      "dispatched_at": "2026-03-26T13:41:08Z",
      "status_text": "Turn 7",
      "status_text_full": "Running, turn 7."
    },
    {
      "issue_id": "jkl012",
      "issue_identifier": "MT-652",
      "issue_title": "Rotate the signing keys",
      "issue_url": "https://tracker.example.com/browse/MT-652",
      "status": "parked",
      "rule_name": "bugfix",
      "stage_position": null,
      "agent_kind": "claude-code",
      "configured_model": "claude-sonnet-4-5",
      "dispatched_at": "2026-03-26T13:41:20Z",
      "status_text": "Parked: the agent needs a person",
      "status_text_full": "Parked: the agent stopped because it cannot go on without a person. Parking label: `needs-human`."
    },
    {
      "issue_id": "mno345",
      "issue_identifier": "MT-653",
      "issue_title": "Add the export button",
      "issue_url": "https://tracker.example.com/browse/MT-653",
      "status": "pending_reactions",
      "rule_name": "implement",
      "stage_position": {
        "chain": ["specify", "implement"],
        "current": "implement",
        "hop_count": 1,
        "hop_ceiling": 10
      },
      "agent_kind": "claude-code",
      "configured_model": "claude-sonnet-4-5",
      "reaction_kind": "ci",
      "dispatched_at": "2026-03-26T13:58:03Z",
      "status_text": "CI escalated on #931",
      "status_text_full": "Sortie escalated failing CI on PR #931; it keeps watching the pull request. CI fixes used: 2 of 2."
    },
    {
      "issue_id": "def456",
      "issue_identifier": "MT-650",
      "issue_title": "Retry the export job",
      "issue_url": "https://tracker.example.com/browse/MT-650",
      "status": "retrying",
      "rule_name": "implement",
      "stage_position": {
        "chain": ["specify", "implement"],
        "current": "implement",
        "hop_count": 1,
        "hop_ceiling": 10
      },
      "agent_kind": "claude-code",
      "configured_model": "claude-sonnet-4-5",
      "dispatched_at": "2026-03-26T14:02:41Z",
      "status_text": "Retry 3 in 5m: no agent slot was free",
      "status_text_full": "The retry came due and was not dispatched: no agent slot was free. Retry 3 in 5m."
    },
    {
      "issue_id": "stu901",
      "issue_identifier": "MT-655",
      "issue_title": "Plan the export schema",
      "issue_url": "https://tracker.example.com/browse/MT-655",
      "status": "between_stages",
      "rule_name": "implement",
      "stage_position": {
        "chain": ["specify", "implement"],
        "current": "implement",
        "hop_count": 1,
        "hop_ceiling": 10
      },
      "agent_kind": "claude-code",
      "configured_model": "claude-sonnet-4-5",
      "dispatched_at": "2026-03-26T14:03:41Z",
      "status_text": "Between stages: specify to implement",
      "status_text_full": "Moved from stage specify to stage implement, and Sortie added `stage-implement`; implement starts when a poll tick reads that label on the issue."
    }
  ],
  "attention": [
    {
      "id": "436a04996ce8317d45cdb082d7ee656a",
      "kind": "workflow_reload_failed",
      "severity": "critical",
      "since": "2026-03-26T14:29:41Z",
      "acknowledged_at": null,
      "reason_text": "WORKFLOW.md failed to load",
      "why_text": "WORKFLOW.md failed to load (config: agent.turn_timeout_ms: must be greater than 0), so poll ticks dispatch nothing until it loads, and the configuration that last loaded stays in effect.",
      "clears_text": "Clears when WORKFLOW.md loads again, which Sortie tries each time the file is saved and on every poll tick.",
      "action": {"kind": "acknowledge"},
      "evidence": {
        "file": "WORKFLOW.md",
        "error": "config: agent.turn_timeout_ms: must be greater than 0"
      }
    },
    {
      "id": "9ee206201099385b431c9bb01911553f",
      "kind": "parked",
      "severity": "warning",
      "since": "2026-03-26T14:05:00Z",
      "acknowledged_at": null,
      "issue_id": "jkl012",
      "issue_identifier": "MT-652",
      "issue_title": "Rotate the signing keys",
      "issue_url": "https://tracker.example.com/browse/MT-652",
      "reason_text": "Parked: the agent needs a person",
      "why_text": "The agent stopped because it cannot go on without a person, so Sortie parked the issue under the label `needs-human`.",
      "clears_text": "Clears when a poll tick finds `needs-human` removed from the issue, or the issue moved out of In Progress.",
      "action": {"kind": "open_issue", "url": "https://tracker.example.com/browse/MT-652"},
      "evidence": {
        "reason": "agent_blocked",
        "label": "needs-human"
      }
    },
    {
      "id": "464f9ff8ea54c4c6cfb43af394234d57",
      "kind": "budget_held",
      "severity": "warning",
      "since": "2026-03-26T14:12:00Z",
      "acknowledged_at": null,
      "issue_id": "ghi789",
      "issue_identifier": "MT-651",
      "issue_title": "Migrate the billing tables",
      "issue_url": "https://tracker.example.com/browse/MT-651",
      "reason_text": "Session budget reached",
      "why_text": "The issue has used 3 sessions of its budget of 3.",
      "clears_text": "Clears on the next poll tick after `agent.max_sessions` is raised above 3 or is removed, or after the issue leaves the active tracker states.",
      "action": {"kind": "acknowledge"},
      "evidence": {
        "reason": "session_budget",
        "used_sessions": 3,
        "budget_sessions": 3
      }
    },
    {
      "id": "cf5210ceffa49562e16b5c7c7a9aeb36",
      "kind": "reaction_escalated",
      "severity": "warning",
      "since": "2026-03-26T14:26:40Z",
      "acknowledged_at": null,
      "issue_id": "mno345",
      "issue_identifier": "MT-653",
      "issue_title": "Add the export button",
      "issue_url": "https://tracker.example.com/browse/MT-653",
      "reason_text": "CI escalated on #931",
      "why_text": "Sortie escalated failing CI on PR #931 after 2 of 2 CI fixes; the latest check found Test failing.",
      "clears_text": "Clears when a check of PR #931 passes, a new commit lands on it, it merges or closes, `reactions.ci_failure.max_retries` rises above 2, or the issue reaches a terminal tracker state or leaves In Review.",
      "action": {"kind": "open_pull_request", "url": "https://github.com/acme/web/pull/931"},
      "evidence": {
        "reaction_kind": "ci",
        "config_key": "ci_failure",
        "pull_request": {
          "number": 931,
          "repository": "acme/web",
          "url": "https://github.com/acme/web/pull/931",
          "branch": "sortie/MT-653",
          "head_sha": "4f1c2a9e8b7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b"
        },
        "escalation_trigger": "budget_exhausted",
        "used_attempts": 2,
        "max_attempts": 2,
        "last_check": {
          "observed_at": "2026-03-26T14:26:40Z",
          "head_sha": "9b7e3d1c0a2f4e6b8d0c1a3e5f7b9d2c4e6a8f0b",
          "status": "failing",
          "failing_checks": ["Test"],
          "failing": 1,
          "pending": 0,
          "passing": 4
        }
      }
    }
  ],
  "agent_totals": {
    "input_tokens": 45000,
    "output_tokens": 18200,
    "total_tokens": 63200,
    "cache_read_tokens": 31500,
    "cache_write_tokens": 4800,
    "seconds_running": 2847.3,
    "unmeasured_sessions": 3,
    "running_unreported": 0,
    "running_non_reporting": 0
  },
  "rate_limits": {},
  "active_estimated_cost_usd": 0.06372,
  "cost_unpriced_running": 0,
  "config": {
    "tracker": {
      "kind": "jira",
      "active_states": ["To Do", "In Progress"],
      "in_progress_state": "In Progress",
      "handoff_state": "In Review",
      "terminal_states": ["Done"]
    },
    "polling": {
      "interval_ms": 30000
    },
    "agent": {
      "kind": "claude-code",
      "usage_arrival": "incremental",
      "max_turns": 20,
      "stall_timeout_ms": 300000,
      "max_retry_backoff_ms": 300000,
      "max_sessions": 5,
      "max_tokens": 500000,
      "max_concurrent_agents": 4,
      "max_concurrent_agents_by_state": {}
    },
    "worker": {
      "ssh_hosts": [],
      "max_concurrent_agents_per_host": null
    },
    "dispatch": {
      "rules": [
        {
          "name": "specify",
          "selected_by": "match",
          "match": {"issue_type": ["Story"]},
          "next": "implement",
          "agent_kind": "claude-code",
          "usage_arrival": "incremental"
        },
        {
          "name": "implement",
          "selected_by": "stage",
          "stage": "stage-implement",
          "agent_kind": "claude-code",
          "usage_arrival": "incremental"
        },
        {
          "name": "bugfix",
          "selected_by": "match",
          "match": {"labels": ["bug"], "priority": {"op": "lte", "value": 2}},
          "agent_kind": "claude-code",
          "usage_arrival": "incremental"
        }
      ],
      "default": null,
      "chains": [["specify", "implement"]],
      "max_consecutive_hops": null,
      "hop_ceiling": 10
    },
    "reactions": {
      "ci_failure": {
        "max_retries": 2,
        "triage": false,
        "escalation": "label",
        "escalation_label": "needs-human"
      },
      "review_comments": {
        "max_continuation_turns": 3,
        "debounce_ms": 60000,
        "poll_interval_ms": 120000,
        "triage": false,
        "escalation": "label",
        "escalation_label": "needs-human"
      },
      "bot_review": {
        "max_continuation_turns": 5,
        "poll_interval_ms": 60000,
        "bot_usernames": ["review-bot"],
        "triage": false,
        "escalation": "none"
      },
      "merge_conflicts": {
        "max_retries": 1,
        "poll_interval_ms": 60000,
        "triage": false,
        "escalation": "label",
        "escalation_label": "needs-human"
      },
      "auto_merge": {
        "strategy": "squash",
        "require_ci": true,
        "delete_branch": true,
        "poll_interval_ms": 60000,
        "max_retries": null,
        "escalation": "label",
        "escalation_label": "needs-human"
      }
    },
    "token_rates": {
      "claude-code": {
        "input_per_mtok": 3,
        "output_per_mtok": 15,
        "cache_read_per_mtok": 0.3,
        "cache_write_per_mtok": null,
        "complete": true
      },
      "codex": {
        "input_per_mtok": 2.5,
        "output_per_mtok": null,
        "cache_read_per_mtok": null,
        "cache_write_per_mtok": null,
        "complete": false
      }
    }
  },
  "health": {
    "database": {"status": "pass", "checked_at": "2026-03-26T14:29:58Z", "last_success_at": "2026-03-26T14:29:58Z", "consecutive_failures": 0, "failing_since": null},
    "preflight": {"status": "fail", "checked_at": "2026-03-26T14:29:58Z", "last_success_at": "2026-03-26T14:29:28Z", "consecutive_failures": 1, "failing_since": "2026-03-26T14:29:58Z", "error": "dispatch preflight failed: workflow file cannot be loaded: config: agent.turn_timeout_ms: must be greater than 0"},
    "workflow": {"file": "WORKFLOW.md", "status": "fail", "checked_at": "2026-03-26T14:29:58Z", "last_success_at": "2026-03-26T14:29:28Z", "consecutive_failures": 2, "failing_since": "2026-03-26T14:29:41Z", "error": "config: agent.turn_timeout_ms: must be greater than 0"},
    "poll": {"status": "fail", "checked_at": "2026-03-26T14:29:58Z", "last_success_at": "2026-03-26T14:29:28Z", "consecutive_failures": 1, "failing_since": "2026-03-26T14:29:58Z", "outcome": "preflight_failed", "next_poll_at": "2026-03-26T14:30:28Z", "summary_text": "The latest poll stopped at the dispatch preflight before reading the tracker; the last successful poll was 32s ago."},
    "scm": {"provider": "github", "status": "pass", "checked_at": "2026-03-26T14:29:58Z", "last_success_at": "2026-03-26T14:29:58Z", "consecutive_failures": 0, "failing_since": null}
  }
}

Field notes

running[] entries:

The issue-level keys are always present on a running row. A limit key (budget_tokens, budget_sessions) set to null means no limit is configured. A usage key (used_sessions, unmeasured_sessions, issue_tokens_completed, used_tokens) set to null means unknown. The cost_budget tool reports figures under some of the same names to the agent; there a limit that is not configured reads 0.

The same row on a session that has measured nothing, showing only the fields that differ:

{
  "tokens": {
    "input_tokens": null,
    "output_tokens": null,
    "total_tokens": null,
    "cache_read_tokens": null,
    "cache_write_tokens": null
  },
  "api_request_count": null,
  "tokens_measured": false,
  "api_requests_measured": false,
  "used_tokens_complete": false,
  "estimated_cost_usd": null,
  "cost_status": "unmeasured"
}

model_name and requests_by_model are absent from that row rather than empty. A null figure is the absence of a measurement, not a measurement of zero: a consumer aggregating figures across rows must skip a null rather than add it as 0.

A session that continues a CI fix adds these keys, and a session that continues no reaction has none of them:

{
  "reaction_kind": "ci",
  "reaction_config_key": "ci_failure",
  "reaction_attempt": 1,
  "pull_request": {"number": 936, "repository": "acme/web"}
}

Configured and reported model

A running row carries two answers to “which model is this?”. configured_model and configured_effort are what the attempt was asked to run. Sortie resolves them when the attempt starts: the agent kind’s top-level block with the matching dispatch rule’s block laid over it.

They stay fixed for the session, and the next attempt of the same issue resolves them again from the workflow in force at that moment, so a retry after an edit to WORKFLOW.md can show different values. model_name is what the runtime reported running, taken from its token usage events.

Nothing compares the two, and a reported model never replaces a configured one. They differ legitimately: a routing alias in configured_model resolves to a dated model name in model_name, and a runtime can fall back to another model when the configured one is unavailable. A mismatch is therefore not a fault by itself. Read model_name as what ran and configured_model as what the workflow asked for. The cost and quality of the work belong to the model that ran.

The dashboard shows both values. Completed runs keep all three; see model and effort of a completed run.

issue_title, issue_url, issue_labels, issue_type, and state pass through the same masking as the logs: a value Sortie knows to be a secret reads [redacted]. A Jira link carries no user name or password written into tracker.endpoint.

retrying[] entries:

When a retry comes due and cannot start, Sortie puts it back with trigger set to timer and error set to the reason from the table below. The error of the run before it is not kept on the row; it stays in the logs and in that run’s run history. A retry that has not yet come due still carries the error of the run that scheduled it. That error, and last_error on the per-issue response, read as the plain sentence a run row’s error carries for the same failure, not the text Sortie stored. The reschedule reasons below are served as written.

A retry that is rescheduled this way and advances its attempt waits the backoff delay of the new attempt number, per the backoff formula. A reaction retry that stays paused is eventually dropped; see the retry timer row of the transition triggers.

A retry keeps the title, link, type, labels, and state it was scheduled with. Sortie stores them with the retry and restores them at startup, so a restart serves what was served before it. A retry stored by an earlier release has none of them until the next poll whose candidates include its issue, or until the retry next fires. A read never replaces a title or link the retry already holds. The retry stores configured_model and dispatched_at the same way.

budget_exhausted[] entries: Issues held out of dispatch by a per-issue budget ceiling (agent.max_sessions or agent.max_tokens).

A hold found on a retry carries the retry’s dispatch context, and a later poll keeps it. A hold the poll finds first takes its context from the target rule of a stage hop still waiting for its next dispatch, resolved from the configuration in force, and otherwise from the issue’s latest agent run in run history, never from the tracker.

A hold without a context is one for an issue with no agent run, or one whose run history read failed; it reads null for dispatched_at, stage_lineage, and stage_position and omits the other three keys until a later poll reads again.

parked[] entries: Issues held out of dispatch until a person acts on them. The list is always present, [] when no issue is parked, and sorted by issue_identifier, then issue_id. counts.parked equals its length. An issue appears in every list that holds it, so a parked issue that also has a reaction continuation queued is in parked and retrying both. For how a park is recorded and lifted, see agent communication.

The run a park follows is the run whose exit or retry led to the park. When a poll tick parks an issue for reaching the handoff-absence ceiling, it is the issue’s newest agent run. If Sortie cannot read that run, the issue is parked anyway and serves no run: dispatched_at and stage_position are null, and rule_name, agent_kind, and configured_model are omitted until the park is released.

Sortie stores the run, the issue type, and the labels with the park and restores them at startup, so a restart serves what was served before it.

A park stored by an earlier release takes its run from the issue’s newest agent run that started at or before the park, when Sortie upgrades its database, and has no type or labels until a poll whose candidates include its issue supplies them. That poll makes no extra tracker call. For a park that already holds a title or link, it adds the type and labels and changes nothing else.

pending_reactions[] entries: Pull request reactions that Sortie keeps watching after a run hands off, one row per issue and reaction kind. The list is always present, [] when no reaction is pending, and sorted by issue_identifier, then issue_id, then kind. counts.pending_reactions equals its length. An issue appears in every list that holds it, so an issue with a CI fix queued and a review check pending is in retrying and pending_reactions both. active lists each such issue once.

Pending reactions live in memory, except for a standing escalation, which Sortie stores. After a restart Sortie rebuilds the rows from run history and from the stored escalations, and a rebuilt row has no wait or last_check, no pull request url until a check reads one, and a created_at of the restart. A row with a standing escalation keeps its escalated_at, escalation_trigger, and used_attempts. It also holds the title and link only, with no issue_type, issue_labels, or state, because run history records none of them. Its dispatched_at, rule_name, agent_kind, and configured_model come from the run history row.

pull_request keys:

last_check keys. The object is flat, and its members follow the kind:

wait values, set by the pass that last returned the reaction to the pending set:

used_attempts and max_attempts by kind:

between_stages[] entries: Issues that a stage hop moved to their next stage and that no run has picked up yet. The list is always present, [] when no issue is between stages, and sorted by issue_identifier, then issue_id. counts.between_stages equals its length.

An issue joins the list when its hop is made. It leaves when a run of the issue is dispatched, whichever way, or when a reset of the issue’s hop count drops the hop.

An issue with a running session or a queued retry is never listed, so no issue is in between_stages and in running or retrying at once; an issue is in every other list that holds it.

The hop is stored in the database with its type, labels, and state, so a restart serves the rows it served before. A hop stored by an earlier release serves none of the three until its next stage is dispatched.

active[] entries: Every issue that running, retrying, budget_exhausted, parked, pending_reactions, or between_stages holds, once per issue. A client that shows one line per issue reads this list and merges, chooses, and orders nothing itself. The list is always present, [] when no issue is active. The six lists above and counts are unchanged, and counts has no active member: the length of active is the number of active issues.

An entry takes its values from the one row that decides the issue’s status, as that row serves them, so a masked string stays masked. status is the name of that list and follows the precedence of GET /api/v1/{identifier}: running, else retrying, else budget_exhausted, else parked, else pending_reactions, else between_stages. An entry never reads history. For an issue in pending_reactions the deciding row is the first row whose escalated_at is not null, and the first row when none is. A client that needs the rest of the issue’s data finds the deciding row by issue_id in the list status names, and in pending_reactions also by kind equal to reaction_kind.

The entries are ordered by the issue’s place, then issue_identifier, then issue_id, each compared byte by byte. An issue’s place is the earliest dispatched_at its rows carry when the issue enters the lists. An issue none of whose rows is dated is placed before every dated issue. The place does not change when the issue moves from one list to another, when a new pass begins while the issue is listed, or when a dispatched_at of null becomes a time. An issue that no list held and that then returns takes a new place. The order can therefore differ from the order of the entries’ dispatched_at values.

Sortie keeps the places in memory and serves them nowhere. A restart discards them, and each issue then takes its place from the earliest dispatched_at of its restored rows. A client that filters the list keeps the served order.

attention[] entries: Things that need a person. Sortie derives the list on each request from the rows above and the health block and stores it nowhere, so an item exists exactly while its cause holds and disappears on the first request after the cause clears. The list is always present, [] when nothing needs a person, and counts.attention is the number of items whose acknowledged_at is null. A person can acknowledge an item to record that it was seen. The item stays in the list, with acknowledged_at set, until its cause clears, and no longer counts. A client that shows the list needs no ordering, wording, or counting rules of its own: the order, the sentences, and the action come with each item.

kind values, with the cause that raises each:

A preflight that fails because the workflow file did not load yields no preflight_failed item, because the workflow_reload_failed item already names the cause. A preflight_failed item’s since is when the preflight began failing, which can be earlier than the item’s first appearance when the failing streak began on a workflow load. Both process-wide items are absent from a response that carries no health block.

A reaction_escalated item for a row rebuilt after a restart carries open_issue until a check reads the pull request’s link, and then open_pull_request.

evidence members. A member is present exactly on the kinds named and absent on every other:

reason_text, why_text, and clears_text are English sentences that Sortie takes from the same table of wording as the status sentences, one template per park reason, per budget reason, per check, and per kind of escalating reaction. They follow the same rules: each states only a fact Sortie records, is masked like issue_title, and carries no cost, clock time, or date. A part that cannot be rendered reads Status not available, and the item stays, so the list and its count never drop a cause. The reason_text of each kind:

What clears each cause is the source’s own rule, and clears_text words it. A park lifts when a person removes its label after Sortie has seen it there, or moves the issue to another tracker state. A hold leaves the set when a poll tick finds the issue no longer at a ceiling or among the candidates, for example after the ceiling is raised or removed. A reaction escalation ends on the facts under standing escalations. A reload failure ends with the next load that succeeds, and a preflight failure with the next preflight that passes.

Items are ordered by severity (critical before warning), then by since (null first, then ascending), then by id ascending. The order is total, so the same state serves the same list. The attention array of the example above holds the failed reload first, because it is critical, then the park, the hold, and the CI escalation in the order of their since. It holds no preflight_failed item, because the preflight error is the load error.

Attention item IDs

id is the lowercase hexadecimal form of the first 16 bytes of the SHA-256 hash of the JSON array [kind, part, ...], written without whitespace. The parts depend on the kind, with times in UTC:

A park keeps its id and since across a restart, because Sortie stores the park at whole-second precision. A hold keeps its id across a restart, but its since becomes the first poll tick after the restart, because Sortie keeps the moment a hold began in memory only. A reaction escalation keeps its id and since across a restart, because the restored escalation carries its stored time. A reload or preflight failure cannot span a restart, because startup exits when the first load or the startup preflight fails.

A recurrence changes a part, so an acknowledgement, which Sortie keeps under id, never hides a new cause: a new park has a new time, a hold reached again after a raise or under an edited ceiling has a new ceiling, a different budget reason is a new reason, an escalation that ended and began again has a new time, and a failure after a pass has a new failing_since.

Sortie stores an acknowledgement, so it survives a restart for as long as the item exists. A poll tick that has read the candidate issues from the tracker deletes the acknowledgement of every item that no longer exists. A tick whose candidate read fails deletes none.

Status sentences

Every row of running, retrying, budget_exhausted, parked, pending_reactions, and between_stages carries a pair of sentences that say in plain English what the issue is doing, what it waits on, or how it ended. Every entry of active carries the pair of its deciding row. The poll check of health carries one further sentence, summary_text, that follows the rules below. The per-issue response of GET /api/v1/{identifier} carries the same pair on its rows and once for the issue, and every issue_outcome carries a pair too.

• Both keys are always present and never empty. A sentence that cannot be rendered reads Status not available, and Sortie logs the failure.
• Sentences are English and are not translated.
• A sentence does not repeat what the response around it already shows. status_text_full, a next outcome, and an attention item’s why_text and clears_text never name the issue key: they say “the issue” or leave it implied. Only an operator action’s outcome_text, which a client shows on its own, names the issue.
• Sortie renders a sentence on each request from the snapshot, the config this response serves, and run history. It stores none.
• A relative time such as in 55s is measured from the time the snapshot was generated, which generated_at serves on GET /api/v1/state. A sentence carries no clock time or date, and no cost.
• A figure Sortie does not have reads as not measured, never as 0, and a token figure that is only a lower bound reads as at least.
• A running row names its stage only when its stage_position is not null.
• A sentence is masked like issue_title, so a value Sortie knows to be a secret reads [redacted].
• A retry sentence that quotes the error of the run before it quotes the plain sentence the retry’s error serves, not the stored text.
• The sentences are for display. Every field a sentence is built from stays in the response, so a client that needs data reads those fields and does not parse the text.

The examples on this page show the sentences for the values they hold, with a snapshot generated at 2026-03-26T14:30:00Z.

Dispatch time and stage position

dispatched_at is on every kind of entry, and always present. It is when Sortie dispatched the first run of the issue’s current pass.

A pass is the runs of one issue that share a stage chain identifier: a dispatch that no stage hop reached starts one, and a retry, a reaction continuation, the next stage of a hop, and a restart continue it. The value therefore stays fixed across those events, where a running row’s started_at is the start of the session in flight.

It is null where Sortie cannot date the pass: a retry or hop stored without a stage chain identifier, a pass with no agent run in run history, a park that follows no run, and a budget-exhausted entry with no dispatch context. Rows dispatched in one poll tick can share a value, so issue_identifier, then issue_id, order them further. The active list is ordered by the issue’s place, not by this value alone; see active[] entries.

stage_position is on every kind of entry, and always present. It is null exactly when the entry’s rule is on no stage chain, or the entry has no rule, as a park that follows no run has none. Every entry of a workflow without stage chains serves null. Otherwise it is an object:

chain and hop_ceiling follow the configuration as of the latest poll tick, as a running row’s budget_tokens does, while rule_name and stage_lineage stay as they were when the dispatch was selected. After a reload removes the rule from every chain, the entry serves null and keeps its rule_name.

agent_totals: Cumulative across all sessions since Sortie’s database was created, carried over when Sortie restarts; a session whose coding agent has reported no token usage, running or completed, adds nothing to its five token counts. seconds_running includes elapsed time from currently active sessions, not only completed ones. Three further fields disclose, by reason, how many sessions those counts leave out:

active_estimated_cost_usd: Estimated total cost across currently running sessions, computed from configured token rates and each running session’s agent adapter kind. Sessions whose tokens_measured is false are excluded. Omitted when no running, measured session matches an entry containing both input and output rates. It equals the sum of estimated_cost_usd over the running[] entries whose cost_status is "estimated". This is a presentation-layer estimate, not provider billing data.

cost_unpriced_running: Count of running, measured sessions that active_estimated_cost_usd leaves out because their agent kind has no token_rates entry or its entry lacks input_per_mtok or output_per_mtok. Present, zero included, whenever token_rates holds any agent-kind entry, complete or not; omitted when token_rates is absent or empty. When present, it equals the number of running[] entries whose cost_status is "unpriced". Without token_rates, every measured running[] entry reads "unpriced" while this key is absent.

rate_limits: Reserved for future use. Currently an empty object.

config: The workflow configuration in effect, so a client can tell which stages, dispatch rules, and pull request reactions the workflow has without reading WORKFLOW.md. Present on this endpoint only; GET /api/v1/{identifier} carries no config. It holds no credential: no tracker endpoint, API key, or query filter, no agent command, hook, workspace path, or database path, no notification destination, and no agent settings block. The strings it does carry (state names, labels, SSH host names, bot usernames) are served as written.

A member reports the WORKFLOW.md key of the same name. The derived members are selected_by, agent_kind, usage_arrival, chains, hop_ceiling, and complete. A setting that imposes no ceiling reads null, never 0. An optional string is omitted when unset, and a list is [] when empty.

Most members follow the last successful load of WORKFLOW.md; a reload that fails validation leaves the previous values in place. Two groups report what the running process applies instead, because Sortie captures them at startup: every reaction except ci_failure, and token_rates. Until the next restart, config omits a reaction a reload added, keeps listing one a reload removed, and keeps the rates the process started with. See reactions and the token_rates reload behavior.

version and started_at: version is the Sortie version, the same value /readyz serves. started_at is when the process started, in UTC, so it and the uptime_seconds of /readyz count from one instant.

health: The health of Sortie’s own checks, so a client sees a failed reload, a failed preflight, or a failing tracker without reading the log. It holds a member per check: database, preflight, workflow, poll, and scm. Every check carries the members of the first table, and workflow, poll, and scm add members of their own. A time Sortie does not have is null.

A reload that fails to load changes nothing else: the previous configuration stays in effect and config keeps serving it. The tick’s preflight fails with the load error after workflow file cannot be loaded:, and its poll ends as preflight_failed, so the tick dispatches nothing. /readyz keeps reporting workflow: pass beside a failing health.workflow.

A running, retry, or budget-exhausted row records its rule_name and its stage_lineage.previous, and a running or retry row its reaction_config_key, when the run was dispatched or the row was stored, while config follows the rules above. A row can therefore name a rule or reaction that config no longer holds: after a reload that renames or removes a rule, after a restart on an edited file for a restored retry, or, for a row whose rule_name is default, once dispatch.default reads null. Read such a row from its own fields.

Status codes

GET /api/v1/runs: Run history

Returns finished runs from run history, newest first, one page at a time. Each filter narrows the result before the page is cut.

curl 'http://localhost:7678/api/v1/runs?issue=MT-649&limit=20'

Query parameters

Every parameter is optional. An empty value is the same as an absent one. Filters combine with AND and match exactly, case included.

An issue with no issue_outcome matches neither ending bound, so a request that carries ended_since or ended_until returns no run of such an issue. The ending bounds select by the issue’s ending, not by the run’s completion: every run of a matching issue is returned, and the bounds combine with since and until by AND.

Sortie checks every parameter before it reads anything. A parameter outside this table, a parameter given more than once, and a value outside the ranges above answer 400, so a misspelled filter never returns unfiltered rows.

Response

{
  "runs": [
    {
      "run_id": 42,
      "issue_id": "abc123",
      "issue_identifier": "MT-649",
      "issue_title": "Fix the flaky login test",
      "issue_url": "https://tracker.example.com/browse/MT-649",
      "attempt": 2,
      "status": "succeeded",
      "error": null,
      "rule_name": "implement",
      "agent_kind": "claude-code",
      "configured_model": "claude-sonnet-4-20250514",
      "configured_effort": "high",
      "model_name": "claude-sonnet-4-20250514",
      "workflow_file": "WORKFLOW.md",
      "started_at": "2026-03-26T14:10:12Z",
      "completed_at": "2026-03-26T14:31:47Z",
      "dispatched_at": "2026-03-26T13:48:20Z",
      "turns_completed": 9,
      "tokens": {
        "input_tokens": 52000,
        "output_tokens": 9100,
        "total_tokens": 61100,
        "cache_read_tokens": 30000,
        "cache_write_tokens": 4000
      },
      "tokens_measured": true,
      "unaccounted_turns": 0,
      "estimated_cost_usd": 0.1923,
      "cost_status": "estimated",
      "chain_id": "3c8v5n2w7r1t4y6u9i0o8p2asd",
      "stage_previous": "specify",
      "stage_previous_outcome": "succeeded",
      "stage_target": "review",
      "stage_result": "advanced",
      "self_review": {
        "final_verdict": "pass",
        "total_iterations": 2,
        "cap_reached": false
      },
      "origin_recorded": true,
      "trigger": "ci_fix",
      "reaction_kind": "ci",
      "reaction_config_key": "ci_failure",
      "session_id": "session-abc-002",
      "ssh_host": "",
      "dispatch_id": "K2VD7QXN4MZB5TLH6RYC3PWJ2F",
      "issue_outcome": {
        "kind": "merged",
        "observed_at": "2026-03-26T15:02:09Z",
        "merge_path": "auto_merge",
        "pull_request": {"number": 311, "repository": "acme/shop"},
        "status_text": "Merged #311",
        "status_text_full": "Ended merged: auto-merge merged PR #311."
      }
    }
  ],
  "next_cursor": "42"
}

runs is [] when no run matches.

Field notes

Runs are ordered by descending run_id, which is the order Sortie recorded them. Sortie records a run when it completes, so this is completion order. next_cursor is null on the last page. Otherwise it is the run_id of the page’s last run, as a string; pass it back as cursor together with the same filters to read the next page. A run recorded between two requests never moves a served run to another page.

Run fields:

A status of "ci_failed" marks a recorded CI result rather than an agent session: it has no agent_kind, and each origin member and dispatch_id is "".

Model and effort of a completed run

Each completed run also stores the settings it ran with, in three text columns of run_history: configured_model and configured_effort (what the attempt was asked to run) and reported_model (what the runtime reported running). Configured and reported model explains how to read the pair. This route serves them as configured_model, configured_effort, and model_name, each omitted when empty:

curl -s 'http://localhost:7678/api/v1/runs?limit=5' | jq '.runs[] | {issue_identifier, configured_model, configured_effort, model_name}'

The columns can also be read from the database directly:

sqlite3 .sortie.db "SELECT identifier, configured_model, configured_effort, reported_model FROM run_history ORDER BY started_at DESC LIMIT 5"

An unset value is an empty string, not NULL. All three columns are empty on runs recorded before Sortie stored them and on ci_failed rows. sortie stats aggregates the configured model; it does not read reported_model or configured_effort.

Issue outcome

issue_outcome records how the issue’s latest work ended, with the time Sortie observed the ending. It belongs to the issue, not to a run. It is null while Sortie has not seen the issue end.

Sortie records the outcome when it observes the ending:

• A handoff transition succeeds. The kind is "terminal" when the target state is itself terminal.
• Reconciliation, a retry timer, a handoff verification read, a stage hop check, or the release of a parked issue reads the issue in a terminal state. If the issue holds a pending auto_merge or merge_completion reaction, Sortie first reads that pull request once and records "merged" when the read reports it merged, so a forge that closes the issue on merge does not hide the pull request. A failed read records "terminal".
• auto_merge merges the pull request, is told it is already merged, or finds it merged on a read. merge_completion reads it merged.

One outcome is kept per issue. A new observation replaces the stored outcome only as follows; otherwise the stored outcome and its observed_at stay.

A poll tick that dispatches the issue again clears the outcome, so issue_outcome describes the latest ending only. A failed write is logged and does not affect the issue.

Status codes

GET /api/v1/runs/issues: Run history by issue

Returns run history grouped by issue, one page of issues at a time. The issue with the newest matching run comes first, and each issue carries its newest runs, its totals, and the sentence that says what it is doing now or how it ended. GET /api/v1/runs lists runs, so one busy issue can fill a page; this route lists issues.

curl 'http://localhost:7678/api/v1/runs/issues?status=failed&limit=10'

Query parameters

Every parameter is optional. An empty value is the same as an absent one. Filters combine with AND and match exactly, case included. An issue is selected when at least one of its runs matches every filter.

The parameters of GET /api/v1/runs that select by run id, completion time, or issue ending (issue_id, since, until, ended_since, ended_until) are not accepted here.

Sortie checks every parameter before it reads anything. A parameter outside this table, a parameter given more than once, and a value outside the ranges above answer 400, so a misspelled filter never returns unfiltered issues.

Response

{
  "groups": [
    {
      "issue_id": "abc123",
      "issue_identifier": "MT-649",
      "issue_title": "Fix the flaky login test",
      "issue_url": "https://tracker.example.com/browse/MT-649",
      "status": "history",
      "status_text": "Merged #311",
      "status_text_full": "Ended merged: auto-merge merged PR #311.",
      "issue_outcome": {
        "kind": "merged",
        "observed_at": "2026-03-26T15:02:09Z",
        "merge_path": "auto_merge",
        "pull_request": {"number": 311, "repository": "acme/shop"},
        "status_text": "Merged #311",
        "status_text_full": "Ended merged: auto-merge merged PR #311."
      },
      "runs": [
        {
          "run_id": 42,
          "issue_id": "abc123",
          "issue_identifier": "MT-649",
          "status": "succeeded",
          "completed_at": "2026-03-26T14:31:47Z"
        }
      ],
      "next_cursor": null,
      "totals": {
        "run_count": 1,
        "unmeasured_runs": 0,
        "tokens": {
          "input_tokens": 52000,
          "output_tokens": 9100,
          "total_tokens": 61100,
          "cache_read_tokens": 30000,
          "cache_write_tokens": 4000
        },
        "tokens_complete": true,
        "estimated_cost_usd": 0.1923,
        "cost_status": "estimated"
      }
    }
  ],
  "next_cursor": "42"
}

The example trims each run to four of its fields. groups is [] when no issue matches.

Field notes

Groups are ordered by the run_id of each issue’s newest matching run, descending. next_cursor is null on the last page. Otherwise it is that run_id for the page’s last group, as a string; pass it back as cursor together with the same filters to read the next page. Every issue appears once in a traversal, and a run recorded between two requests never moves a served issue to another page.

Group fields:

The filters narrow runs to the matching runs, but issue_identifier, the title, the link, and totals describe the issue as a whole.

Status codes

GET /api/v1/runs/{dispatch_id}/events: Run events

Returns the agent events Sortie kept for one run, oldest first, each with a plain English sentence. {dispatch_id} is the dispatch_id of a running row or of a run, as one path segment. The route takes no parameters and ignores the query string. To receive the same events as they arrive, name the run in the run parameter of GET /api/v1/events.

curl http://localhost:7678/api/v1/runs/RLQFSIOFERWGDW2HZY45W55VXK/events

Response

{
  "dispatch_id": "RLQFSIOFERWGDW2HZY45W55VXK",
  "first_seq": 1,
  "events": [
    {
      "seq": 1,
      "at": "2026-03-26T14:10:14Z",
      "event": "session_started",
      "message": "",
      "session_id": "session-abc-001",
      "text": "Session started."
    },
    {
      "seq": 41,
      "at": "2026-03-26T14:29:31Z",
      "event": "tool_result",
      "message": "",
      "tool_name": "Bash",
      "duration_ms": 2400,
      "tool_error": false,
      "text": "Ran Bash in 2.4s."
    },
    {
      "seq": 42,
      "at": "2026-03-26T14:29:59Z",
      "event": "turn_completed",
      "message": "Working on tests",
      "usage": {
        "input_tokens": 12500,
        "output_tokens": 3200,
        "total_tokens": 15700,
        "cache_read_tokens": 8400,
        "cache_write_tokens": 1200
      },
      "text": "Turn completed: Working on tests."
    }
  ]
}