---
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
        - `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
    - `graph` object, required
    - `graph_source` string, nullable
    - `workflow_slug` string, nullable
    - `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
    - `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

---

[API](https://skmtc.net/fabro-sh/apis/fabro-run-api.md) · [All operations](https://skmtc.net/fabro-sh/apis/fabro-run-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fabro-sh/fabro-run-api/versions/bee030053823/schema)