---
title: "Get Run State"
method: GET
path: "/api/v1/runs/{id}/state"
tags: ["Run Internals"]
---

# Get Run State

`GET /api/v1/runs/{id}/state`

Returns the internal event-sourced run projection. This is not a stable public contract.

## Path parameters

- `id` string, required

## Response `200`

Current run projection

- RunProjection — Raw internal run projection derived from the event log.
  - `title` string — Resolved run title from the event log.
  - `parent_id` string, nullable — Current orchestration parent run ID, if linked.
  - `spec` RunSpec, required — Durable workflow run specification reconstructed from run.created events.
    - `run_id` string, required
    - `settings` WorkflowSettings, required — The persisted dense `WorkflowSettings` snapshot used for a specific run. This matches the resolved run settings recorded at launch time.
      - `project` ProjectNamespace, required
        - `name` string, nullable, required
        - `description` string, nullable, required
        - `metadata` StringMap, required
      - `workflow` WorkflowNamespace, required
        - `name` string, nullable, required
        - `description` string, nullable, required
        - `graph` string, required
        - `metadata` StringMap, required
      - `environments` object, required
      - `run` RunNamespace, required
        - `goal` union, required
          - RunGoalInline
            - `type` 'inline', required
            - `value` string, required — Config string that can contain typed interpolation tokens.
          - RunGoalFile
            - `type` 'file', required
            - `value` string, required — Config string that can contain typed interpolation tokens.
        - `working_dir` string, required — Config string that can contain typed interpolation tokens.
        - `metadata` StringMap, required
        - `inputs` object, required
        - `model` RunModelSettings, required
          - `provider` string, nullable, required
          - `name` string, nullable, required
          - `fallbacks` object, required — Ordered fallback targets keyed by the originally requested model. Each chain is independent; selecting a fallback target does not activate that target model's own chain.
          - `controls` RunModelControls — Run-level default values for typed model controls. Node and style attributes still win over these defaults.
            - `reasoning_effort` string, nullable, required
            - `speed` string, nullable, required
        - `git` RunGitSettings, required
          - `author` GitAuthorSettings, required
            - `name` string, nullable, required
            - `email` string, nullable, required
        - `prepare` RunPrepareSettings, required
          - `steps` PreparedStep[], required
            - union — A single resolved prepare step. The runnable part preserves the script-vs-argv distinction via the `type` discriminator: a `script` is a raw shell snippet kept verbatim, while a `command` is an argv whose elements are shell-quoted and joined at the run boundary (after `{{ secrets.* }}` resolution) so an interpolated value cannot inject shell syntax. Optional per-step `env` is shared by both shapes.
              - …
          - `timeout_ms` integer, required
        - `execution` RunExecutionSettings, required
          - `mode` 'normal' | 'dry_run', required
          - `approval` 'prompt' | 'auto', required
        - `checkpoint` RunCheckpointSettings, required
          - `exclude_globs` string[], required
          - `skip_git_hooks` boolean, required — When true, Fabro-managed run-branch checkpoint commits bypass local Git commit hooks. Does not affect Fabro `[[run.hooks]]` or metadata-branch snapshots. Defaults to false.
        - `clone` RunCloneSettings, required
          - `enabled` boolean, required
          - `depth` integer — Git history depth. Set to 0 to clone full history.
        - `run_branch` RunBranchSettings, required
          - `enabled` boolean, required
          - `push` boolean, required
        - `meta_branch` RunMetaBranchSettings, required
          - `enabled` boolean, required
          - `push` boolean, required
        - `environment` RunEnvironmentSettings, required
          - `id` string, required
          - `provider` 'local' | 'docker' | 'daytona', required — Desired environment provider.
          - `cwd` string, nullable — Local-provider command working directory for this environment. Docker and Daytona ignore this value.
          - `image` EnvironmentImageSettings, required
            - `docker` string, nullable, required
            - `dockerfile` union, required
              - …
          - `resources` EnvironmentResourcesSettings, required
            - `cpu` integer, nullable, required
            - `memory` string, nullable, required
            - `disk` string, nullable, required
          - `network` EnvironmentNetworkSettings, required
            - `mode` 'allow_all' | 'block' | 'cidr_allow_list', required
            - `allow` string[], required
          - `lifecycle` EnvironmentLifecycleSettings, required
            - `preserve` boolean, required
            - `stop_on_terminal` boolean, required
            - `auto_stop` string, nullable, required
          - `labels` StringMap, required
          - `env` object, required
        - `notifications` object, required
        - `interviews` RunInterviewsSettings, required
          - `provider` string, nullable, required
          - `slack` InterviewProviderSettings, required
            - `channel` string, nullable, required
        - `agent` RunAgentSettings, required
          - `fabro_tools` boolean, required
          - `mcps` object, required
        - `hooks` HookDefinition[], required
          - `name` string, nullable, required
          - `event` 'run_start' | 'run_complete' | 'run_failed' | 'stage_start' | 'stage_complete' | 'stage_failed' | 'stage_retrying' | 'edge_selected' | 'parallel_start' | 'parallel_complete' | 'sandbox_ready' | 'sandbox_cleanup' | 'checkpoint_saved' | 'pre_tool_use' | 'post_tool_use' | 'post_tool_use_failure', required
          - `command` string, nullable, required
          - `type` 'command' | 'http' | 'prompt' | 'agent' | 'null', nullable
          - `url` string, nullable
          - `headers` StringMap
          - `tls` 'verify' | 'no_verify' | 'off'
          - `prompt` string, nullable
          - `model` string, nullable
          - `max_tool_rounds` integer, nullable
          - `matcher` string, nullable, required
          - `blocking` boolean, nullable, required
          - `timeout_ms` integer, nullable, required
          - `sandbox` boolean, nullable, required
        - `scm` RunScmSettings, required
          - `provider` string, nullable, required
          - `owner` string, nullable, required
          - `repository` string, nullable, required
          - `github` ScmGitHubSettings, required
        - `pull_request` PullRequestSettings, required
          - `enabled` boolean, required
          - `draft` boolean, required
          - `auto_merge` boolean, required
          - `merge_strategy` 'merge' | 'squash' | 'rebase', required — GitHub merge method for a pull request.
        - `artifacts` ArtifactsSettings, required
          - `include` string[], required
        - `integrations` RunIntegrationsSettings, required
          - `github` RunIntegrationsGithubSettings, required
            - `permissions` object, required
            - `additional_repositories` string[] — Additional GitHub repositories, beyond the implicit run origin, that the minted GITHUB_TOKEN must cover. Each entry is a full `owner/repository` slug; every repository must share one owner with the run origin. Omitted when empty; settings persisted before this field existed deserialize to an empty set.
    - `graph` object, required
    - `graph_source` string, nullable
    - `workflow_slug` string, nullable
    - `workflow_version_id` string — SHA-256 identity of validated canonical workflow-version bytes. Hex input is case-insensitive; Fabro emits the canonical lowercase form.
    - `target` union — Workspace content and location requested for a run.
      - GitRunTarget — Public github.com repository target. The branch names the attached working branch. An optional tag selects a release at worker start, and an optional exact SHA is authoritative when both are present.
        - `kind` 'git', required
        - `repo` string, required — GitHub repository slug in `owner/name` form.
        - `branch` string, required — Required attached working branch name, preserved exactly.
        - `tag` string — Optional bare tag name. Prefixes such as `refs/tags/` and `tags/` are rejected. Without `sha`, the worker resolves this tag when the sandbox starts and fails if it is unavailable.
        - `sha` string — Optional exact commit. The server lowercase-normalizes its syntax but does not resolve it, prove branch ancestry, or prove that it matches an accompanying tag. When present, this exact commit wins.
      - NoneRunTarget — Empty workspace with no repository. Docker and Daytona accept this target and suppress cloning even when workflow settings enable it. Local environments reject it; Local scratch allocation is a separate future capability.
        - `kind` 'none', required
      - FolderRunTarget — Existing directory on the Fabro server, executed in place by a Local environment. The submitted path must be absolute and name an existing directory; Fabro resolves symlinks and persists its canonical UTF-8 path. This target is intended for trusted single-tenant deployments. Docker and Daytona environments always reject it. This target does not add Local Git cloning or Local scratch workspaces. Folder runs execute in place without Fabro Git checkpoints, so fork and rewind are unavailable.
        - `kind` 'folder', required
        - `path` string, required — Absolute path on the Fabro server, not on the API caller's machine.
    - `automation` AutomationRef
      - `id` string, required
      - `name` string, nullable, required
      - `trigger_id` string, nullable
    - `source_directory` string, nullable
    - `labels` object
    - `provenance` RunProvenance, required
      - `server` RunServerProvenance
        - `version` string, required
      - `client` RunClientProvenance
        - `user_agent` string
        - `name` string
        - `version` string
      - `subject` union, required
        - PrincipalUser
          - `kind` 'user', required
          - `identity` IdpIdentity, required
            - `issuer` string, required
            - `subject` string, required
          - `login` string, required
          - `auth_method` 'github' | 'dev_token', required — Runtime user authentication method.
          - `avatar_url` string, nullable
        - PrincipalWorker
          - `kind` 'worker', required
          - `run_id` string, required
        - PrincipalWebhook
          - `kind` 'webhook', required
          - `delivery_id` string, required
        - PrincipalSlack
          - `kind` 'slack', required
          - `team_id` string, required
          - `user_id` string, required
          - `user_name` string, nullable
        - PrincipalAgent
          - `kind` 'agent', required
          - `session_id` string, nullable
          - `parent_session_id` string, nullable
          - `model` string, nullable
        - PrincipalSystem
          - `kind` 'system', required
          - `system_kind` 'engine' | 'watchdog' | 'timeout', required
    - `manifest_blob` string, nullable
    - `definition_blob` string, nullable
    - `spec_blob` string, nullable
    - `git` GitContext — Observable git state captured before the run starts.
      - `origin_url` string, required — Remote origin URL with any embedded credentials removed.
      - `branch` string, required — Current branch name.
      - `sha` string, nullable — Current commit SHA, when known.
      - `dirty` 'clean' | 'dirty' | 'unknown', required
    - `fork_source_ref` ForkSourceRef — Source checkpoint used to initialize a forked or rewound run.
      - `source_run_id` string, required
      - `checkpoint_sha` string, required
  - `web_url` string, nullable — Absolute web UI URL for this run when server web settings are configured.
  - `start` StartRecord — Metadata captured when execution starts.
    - `start_time` string, date-time, required
    - `run_branch` string, nullable
    - `base_sha` string, nullable
  - `status` union, required — Execution status of a run. Archive state is represented separately on `RunLifecycle.archived` so terminal status payloads remain intact.
    - RunStatusSubmitted
      - `kind` 'submitted', required
    - RunStatusPending
      - `kind` 'pending', required
      - `reason` 'approval_required', required — Reason a pre-execution run is pending instead of runnable.
    - RunStatusRunnable
      - `kind` 'runnable', required
    - RunStatusStarting
      - `kind` 'starting', required
    - RunStatusRunning
      - `kind` 'running', required
    - RunStatusBlocked
      - `kind` 'blocked', required
      - `blocked_reason` 'human_input_required', required — Specific reason a run is blocked on external intervention.
    - RunStatusPaused
      - `kind` 'paused', required
      - `prior_block` 'human_input_required', required — Specific reason a run is blocked on external intervention.
    - RunStatusRemoving
      - `kind` 'removing', required
    - RunStatusSucceeded
      - `kind` 'succeeded', required
      - `reason` 'completed' | 'partial_success', required — Reason attached to a successful terminal run status.
    - RunStatusFailed
      - `kind` 'failed', required
      - `reason` 'workflow_error' | 'publish_failed' | 'cancelled' | 'approval_denied' | 'terminated' | 'transient_infra' | 'budget_exhausted' | 'launch_failed' | 'bootstrap_failed' | 'sandbox_init_failed', required — Reason attached to a failed terminal run status.
    - RunStatusDead
      - `kind` 'dead', required
  - `archived_at` string, date-time, nullable
  - `status_updated_at` string, date-time, required
  - `last_event_at` string, date-time, required
  - `pending_control` 'cancel' | 'pause' | 'unpause' — Run control action requested by the API.
  - `checkpoints` CheckpointRecord[], required — Sequence-tagged checkpoint history entries.
    - `seq` integer, required
    - `checkpoint` RunCheckpoint, required — Serializable snapshot of execution state for crash recovery and resume.
      - `timestamp` string, date-time, required — ISO 8601 timestamp when the checkpoint was created.
      - `current_node` string, required — Identifier of the node being executed at checkpoint time.
      - `completed_nodes` string[], required — Identifiers of nodes that have completed execution.
      - `node_retries` object, required — Map of node identifier to retry count.
      - `context_values` object, required — Key-value context map accumulated during execution.
      - `node_outcomes` object — Map of node identifier to outcome data for goal gate checks after resume.
      - `next_node_id` string — The node to resume execution at after this checkpoint.
      - `git_commit_sha` string — SHA of the git commit created at this checkpoint.
      - `loop_failure_signatures` object — Failure signature counts within the main loop.
      - `restart_failure_signatures` object — Failure signature counts across loop_restart edges.
    - `diff` RunDiff, required — Patch text and aggregate counts captured for a run-level diff.
      - `patch` string, nullable
      - `summary` DiffSummary — Cheap aggregate file and line counts for a run diff.
        - `files_changed` integer, required — Total number of changed files, including binary files.
        - `additions` integer, required — Total lines added across text files.
        - `deletions` integer, required — Total lines deleted across text files.
  - `conclusion` Conclusion — Terminal run conclusion derived from final workflow execution.
    - `timestamp` string, date-time, required
    - `status` 'succeeded' | 'partially_succeeded' | 'failed' | 'skipped', required — Terminal execution outcome of a workflow stage.
    - `timing` RunTiming, required — Timing rollup for an entire run. Active fields sum work across stage visits, so `active_time_ms` can exceed `wall_time_ms` when parallel branches run concurrently. For a running run, stages still in flight contribute a live estimate rather than nothing, so wall and active both advance continuously. Unlike `StageTiming`, active is not clamped to wall here — concurrent branches can legitimately sum past run wall time.
      - `wall_time_ms` integer, required
      - `inference_time_ms` integer, required
      - `tool_time_ms` integer, required
      - `active_time_ms` integer, required — Equals `inference_time_ms + tool_time_ms`.
    - `failure` RunFailure — Terminal run failure reason and rich diagnostics.
      - `reason` 'workflow_error' | 'publish_failed' | 'cancelled' | 'approval_denied' | 'terminated' | 'transient_infra' | 'budget_exhausted' | 'launch_failed' | 'bootstrap_failed' | 'sandbox_init_failed', required — Reason attached to a failed terminal run status.
      - `detail` FailureDetail, required — Rich diagnostic detail for a failed stage or terminal run.
        - `message` string, required
        - `causes` string[]
        - `category` 'transient_infra' | 'deterministic' | 'budget_exhausted' | 'compilation_loop' | 'canceled' | 'structural', required — Product-level classification for grouping and retry policy.
        - `system_actor` 'engine' | 'watchdog' | 'timeout'
        - `signature` string — Stable normalized signature for grouping related failures.
        - `exec_output_tail` ExecOutputTail — Redacted tail of command stdout/stderr captured for diagnostics.
          - `stdout` string, nullable
          - `stderr` string, nullable
          - `stdout_truncated` boolean
          - `stderr_truncated` boolean
    - `final_git_commit_sha` string, nullable
    - `stages` StageSummary[], required
      - `stage_id` string, required
      - `stage_label` string, required
      - `timing` StageTiming, required — Timing breakdown for one stage visit. Fields are all milliseconds. `wall_time_ms` is elapsed clock time; `inference_time_ms` is Fabro- observed LLM request/stream elapsed time; `tool_time_ms` is tool or command execution elapsed time; `active_time_ms` equals `inference_time_ms + tool_time_ms`. For a terminal stage these come from the worker's own stopwatch and are authoritative. For a stage still in flight they are a live estimate reconstructed from the event log, and `active_time_ms` is clamped to `wall_time_ms`. The estimate is replaced by the authoritative breakdown when the stage reaches a terminal event.
        - `wall_time_ms` integer, required
        - `inference_time_ms` integer, required
        - `tool_time_ms` integer, required
        - `active_time_ms` integer, required — Equals `inference_time_ms + tool_time_ms`.
      - `billing_usd_micros` integer, nullable
      - `retries` integer, required
    - `billing` BilledTokenCounts — Token counts with optional billed USD micros totals.
      - `input_tokens` integer, required — Number of input tokens consumed.
      - `output_tokens` integer, required — Number of output tokens generated.
      - `total_tokens` integer, required — Total billable tokens aggregated across categories.
      - `reasoning_tokens` integer, required — Number of reasoning tokens.
      - `cache_read_tokens` integer, required — Number of cache read tokens.
      - `cache_write_tokens` integer, required — Number of cache write tokens.
      - `total_usd_micros` integer, nullable — Billed USD amount in micros.
    - `total_retries` integer, required
    - `diff` RunDiff, required — Patch text and aggregate counts captured for a run-level diff.
      - `patch` string, nullable
      - `summary` DiffSummary — Cheap aggregate file and line counts for a run diff.
        - `files_changed` integer, required — Total number of changed files, including binary files.
        - `additions` integer, required — Total lines added across text files.
        - `deletions` integer, required — Total lines deleted across text files.
  - `sandbox` RunSandbox — Sandbox lifecycle record for a run. A run can have a requested sandbox plan before it has an initialized sandbox instance.
    - `kind` 'planned' | 'initializing' | 'ready' | 'failed', required — Lifecycle state for a run sandbox request.
    - `plan` RunSandboxPlan, required — Requested sandbox provider and base image/snapshot from run settings.
      - `provider` 'local' | 'docker' | 'daytona', required — Sandbox provider discriminator.
      - `image` string, nullable
      - `snapshot` string, nullable
    - `instance` RunSandboxInstance — Initialized sandbox provider and runtime metadata.
      - `provider` 'local' | 'docker' | 'daytona', required — Sandbox provider discriminator.
      - `image` string, nullable
      - `snapshot` string, nullable
      - `runtime` RunSandboxRuntime, required
        - `id` string, required
        - `working_directory` string, required
        - `repo_cloned` boolean, nullable, required
        - `clone_origin_url` string, nullable, required
        - `clone_branch` string, nullable, required
        - `workspace_root` string, nullable
        - `repos_root` string, nullable
        - `primary_repo_path` string, nullable
        - `primary_repo_link` string, nullable
    - `failure` RunSandboxFailure — Sandbox initialization failure details.
      - `provider` string, required — Provider reported by the sandbox initialization event.
      - `error` string, required
      - `causes` string[], required
      - `duration_ms` integer, required
  - `pull_request` PullRequestLink — Minimal GitHub pull request link associated with a run.
    - `owner` string, required
    - `repo` string, required
    - `number` integer, required
    - `html_url` string, uri, required — Computed GitHub web URL for the pull request.
  - `pull_request_creation` PullRequestCreation — Durable status for the latest explicit pull request creation requested for a run.
    - `id` string, required — Stable identifier for one explicit pull request creation request.
    - `status` 'pending' | 'succeeded' | 'failed', required — Durable state of a pull request creation request.
    - `model` string, required — Resolved model identifier used to generate the pull request content.
    - `force` boolean, required — Whether creation was allowed for a run without a successful conclusion.
    - `requested_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `pull_request` PullRequestLink — Minimal GitHub pull request link associated with a run.
      - `owner` string, required
      - `repo` string, required
      - `number` integer, required
      - `html_url` string, uri, required — Computed GitHub web URL for the pull request.
    - `error` string, nullable
  - `superseded_by` string, nullable
  - `retried_from` string, nullable — Source run ID when this run was created by manual retry.
  - `pending_interviews` object, required
  - `stages` object, required — Map from StageId (`node_id@visit`) to stage projection data.

## Other responses

- `404` — Run not found

## Changes

- **2026-08-26** `13262755c97f` — 1 info
  - added the optional property `spec/target/oneOf[#/components/schemas/RunTarget]/oneOf[#/components/schemas/GitRunTarget]/tag` to the response with the `200` status
- **2026-08-26** `e7fd6d853204` — 1 breaking, 1 info
  - added `#/components/schemas/FolderRunTarget` to the `spec/target/oneOf[#/components/schemas/RunTarget]/` response property `oneOf` list for the response status `200`
  - added `folder` discriminator mapping keys to the `spec/target/oneOf[#/components/schemas/RunTarget]/` response property for the response status `200`
- **2026-08-25** `9abd94e6cfbe` — 1 breaking, 1 info
  - added `#/components/schemas/NoneRunTarget` to the `spec/target/oneOf[#/components/schemas/RunTarget]/` response property `oneOf` list for the response status `200`
  - added `none` discriminator mapping keys to the `spec/target/oneOf[#/components/schemas/RunTarget]/` response property for the response status `200`
- **2026-08-24** `5290add6d36f` — 2 info
  - removed `none` discriminator mapping keys from the `spec/target/oneOf[#/components/schemas/RunTarget]/` response property for the response status `200`
  - removed `#/components/schemas/NoneRunTarget` from the `spec/target/oneOf[#/components/schemas/RunTarget]/` response property `oneOf` list for the response status `200`
- …earlier changes not shown

[Full history](https://skmtc.dev/fabro-sh/apis/fabro-run-api/changes/api/v1/runs/:id/state/get.md)

---

[API](https://skmtc.dev/fabro-sh/apis/fabro-run-api.md) · [All operations](https://skmtc.dev/fabro-sh/apis/fabro-run-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fabro-sh/fabro-run-api/revisions/7bdeefd151cd/schema)