---
title: "List Run Files Changed"
method: GET
path: "/api/v1/runs/{id}/files"
tags: ["Run Outputs"]
---

# List Run Files Changed

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

Returns the set of file changes produced by a run as a list of before/after diffs.

While the run's sandbox is reachable, diffs are resolved live against the sandbox working tree at the current HEAD. Degraded responses keep the same `data: FileDiff[]` shape. File contents are null on every entry; non-sensitive non-flagged entries include `unified_patch`, while sensitive / binary / symlink / submodule / truncated entries render through the same placeholder flags used by the live path.

Responses are bounded by per-file (256 KiB / 20k lines), per-run aggregate (5 MiB), and per-request (200 files) caps. Files exceeding a cap are returned with `truncated: true` and empty `contents`. Sensitive paths (credentials, keys) are elided with `sensitive: true` and empty `contents`.

## Path parameters

- `id` string, required

## Query parameters

- `page[limit]` integer
- `page[offset]` integer
- `scope` 'committed' | 'uncommitted' | 'all'
- `from_sha` string
- `to_sha` string

## Response `200`

File diffs for the run

- PaginatedRunFileList — List of file diffs produced by a run, with metadata describing truncation and degraded-response state. Naturally bounded: at most 200 files per response. Consumers should inspect `meta.truncated` rather than assuming `data.length` equals the run's total change count.
  - `data` FileDiff[], required
    - `old_file` DiffFile, required — A file's contents at one side of a diff.
      - `name` string, required — File path relative to the repository root.
      - `contents` string, nullable, required — Full contents at this side. Live path: empty string for added/deleted/binary/sensitive/symlink/submodule/truncated entries (the placeholder flags drive rendering). Degraded path: null for every entry (including placeholder-flagged ones), because the server only holds a checkpoint patch and cannot reconstruct full file bytes — distinguish degraded from live by `meta.degraded`.
    - `new_file` DiffFile, required — A file's contents at one side of a diff.
      - `name` string, required — File path relative to the repository root.
      - `contents` string, nullable, required — Full contents at this side. Live path: empty string for added/deleted/binary/sensitive/symlink/submodule/truncated entries (the placeholder flags drive rendering). Degraded path: null for every entry (including placeholder-flagged ones), because the server only holds a checkpoint patch and cannot reconstruct full file bytes — distinguish degraded from live by `meta.degraded`.
    - `change_kind` 'added' | 'modified' | 'deleted' | 'renamed' | 'symlink' | 'submodule' — Optional classification of the change. Clients that don't recognize a value should fall back to inspecting the old/new contents.
    - `truncated` boolean — When `true`, `new_file.contents` and `old_file.contents` are empty strings because the file exceeded a cap (see `truncation_reason`).
    - `truncation_reason` 'file_too_large' | 'budget_exhausted' — Reason this file's contents were omitted. Absent when `truncated` is `false` or omitted.
    - `binary` boolean — When `true`, the file is non-textual; `contents` on both sides are empty strings.
    - `sensitive` boolean — When `true`, the file path matched the server's sensitive-path denylist; `contents` on both sides are empty strings regardless of truncation or binary flags.
    - `unified_patch` string, nullable — Per-file unified-patch text (the `diff --git` section verbatim). Populated only for regular non-flagged text-diff entries in degraded mode. Absent for sensitive, binary, symlink, submodule, truncated, and live-path entries.
  - `meta` RunFilesMeta, required — Metadata for a `PaginatedRunFileList` response. Replaces `PaginationMeta` on the files endpoint — the naturally-bounded list does not use cursor pagination but exposes caps and a degraded-response path instead.
    - `source` 'sandbox' | 'final_patch', required — Source used to materialize this response. `sandbox` honors the requested scope from the run-owned sandbox; `final_patch` is fallback committed/final diff data from stored run state.
    - `scope` 'committed' | 'uncommitted' | 'all' | 'range', required — Diff scope materialized for this response.
    - `stats` DiffStats, required — Aggregate `+/-` line counts across all files in a diff. Binary, sensitive, symlink, and submodule files contribute 0/0 since they have no line-level diff. Both fields are 0 for empty / pre-start envelopes.
      - `additions` integer, required — Total lines added.
      - `deletions` integer, required — Total lines deleted.
    - `truncated` boolean, required — True when any cap (file count, per-file size, or aggregate size) was hit for this response.
    - `files_omitted_by_budget` integer — Number of files dropped because the aggregate 5 MiB budget was exhausted. Zero or absent when no files were dropped for budget reasons.
    - `total_changed` integer, required — Total files changed in the run (before caps were applied). May exceed `data.length` when truncation occurred.
    - `to_sha` string — Head SHA the diff (or patch) was resolved against.
    - `to_sha_committed_at` string, date-time — Commit time of `to_sha`, used by the UI for the "Checkpoint Xm ago" freshness label on Running runs.
    - `degraded` boolean — When `true`, every entry in `data` has null `contents` on both sides; non-sensitive non-flagged entries also include `unified_patch`. Entries flagged `sensitive` / `binary` / `symlink` / `submodule` / `truncated` render via the same placeholders used in the live path (the flags drive rendering; contents are null in degraded mode regardless). The data shape is otherwise identical to the live path.
    - `degraded_reason` 'sandbox_unreachable' | 'sandbox_gone' | 'provider_unsupported' — Why the response degraded. Absent when `degraded` is `false` or omitted.

## Other responses

- `400` — Malformed query parameter (invalid SHA format, one-sided SHA range, or `scope` combined with an explicit SHA range).
- `404` — Run not found (or caller lacks access; returned as 404 to prevent enumeration).
- `503` — Transient sandbox subprocess failure (timeout, process kill). Safe to retry.

---

[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)