---
title: "Unarchive Runs"
method: POST
path: "/api/v1/runs/unarchive"
tags: ["Runs"]
---

# Unarchive Runs

`POST /api/v1/runs/unarchive`

Restores up to 250 archived runs in one fail-soft, non-transactional request. Each run is processed independently and successful items emit the same per-run unarchive events as `POST /api/v1/runs/{id}/unarchive`. A valid batch returns `200` even when some items fail; inspect `results` and `summary` for per-run outcomes. Invalid request bodies are rejected before mutating any run.

## Request body

- BatchRunLifecycleRequest — Run IDs to archive or unarchive as one bounded fail-soft batch.
  - `run_ids` string[], required — Run IDs to process, in result order.

## Response `200`

Batch processed

- BatchRunLifecycleResponse — Per-run results for a fail-soft batch archive or unarchive request.
  - `results` BatchRunLifecycleResult[], required — Results ordered exactly like the request `run_ids`.
    - `run_id` string, required — Run ID from the request item.
    - `ok` boolean, required — Whether this item succeeded.
    - `outcome` 'archived' | 'already_archived' | 'unarchived' | 'not_archived' | 'not_found' | 'conflict' | 'error', required — Machine-readable item outcome.
    - `run` Run — Canonical public run shape.
      - `id` string, required
      - `parent_id` string, nullable — Current orchestration parent run ID, if linked.
      - `children_count` integer, required — Number of runs currently linked to this run as their orchestration parent.
      - `title` string, required
      - `goal` string, required
      - `workflow` WorkflowRef, required
        - `slug` string, nullable, required
        - `name` string, nullable, required
        - `graph_name` string, nullable, required
        - `node_count` integer, required — Number of nodes in the workflow graph.
        - `edge_count` integer, required — Number of edges in the workflow graph.
      - `automation` AutomationRef, required
        - `id` string, required
        - `name` string, nullable, required
        - `trigger_id` string, nullable
        - `workflow_source` ResolvedAutomationGitWorkflowSource — Workflow source coordinate and exact commit captured when an automation run was created. The requested selectors remain available for audit context while `resolved_sha` identifies the immutable source revision that supplied the workflow bytes.
          - `repo` string, required — GitHub repository slug in `owner/name` form.
          - `branch` string, required — Required branch fallback and audit context.
          - `tag` string — Optional tag requested by the automation.
          - `sha` string — Optional exact commit requested by the automation.
          - `resolved_sha` string, required — Exact lowercase Git commit that supplied the workflow bytes.
      - `repository` RepositoryRef, required — Durable repository metadata for a run.
        - `name` string, required
        - `origin_url` string, nullable, required
        - `provider` 'github' | 'git' | 'unknown', required
      - `created_by` 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
      - `origin` RunOrigin, required
        - `kind` 'api', required
      - `labels` object, required
      - `lifecycle` RunLifecycle, required
        - `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
        - `approval` RunApproval, required — Pre-execution approval state for runs that require one-time human approval.
          - `state` 'pending' | 'approved' | 'denied', required — State of a run's pre-execution approval request.
          - `requested_at` string, date-time, required
          - `decided_at` string, date-time, nullable, required
          - `denial_reason` string, nullable, required
        - `pending_control` 'cancel' | 'pause' | 'unpause', required — Run control action requested by the API.
        - `queue_position` integer, nullable, required
        - `error` RunError, required — Error information for a failed run.
          - `message` string, required — Error message.
        - `archived` boolean, required
        - `archived_at` string, date-time, nullable, required
      - `sandbox` RunSandbox, required — 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` string, required — Sandbox provider kind. `local`, `docker`, and `daytona` are bundled with the server; any other value names a sandbox-driver plugin configured under `server.sandbox.providers.<kind>`.
          - `image` string, nullable
          - `snapshot` string, nullable
        - `instance` RunSandboxInstance — Initialized sandbox provider and runtime metadata.
          - `provider` string, required — Sandbox provider kind. `local`, `docker`, and `daytona` are bundled with the server; any other value names a sandbox-driver plugin configured under `server.sandbox.providers.<kind>`.
          - `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
      - `models` RunModel[], required
        - `provider` string, nullable, required
        - `name` string, required
      - `source_directory` string, nullable, required
      - `timestamps` RunTimestamps, required
        - `created_at` string, date-time, required
        - `started_at` string, date-time, nullable, required
        - `last_event_at` string, date-time, nullable, required
        - `completed_at` string, date-time, nullable, required
      - `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`.
      - `usage` Usage, required — lithos `Usage`: token counts and, when known, what they cost. `cost` is absent when there is no cost data, never zero. A sum has a cost only when every part that used tokens was priced; its `source` is the parts' shared source, or `application` when they differ.
        - `tokens` TokenCounts, required — lithos `TokenCounts`: five disjoint token buckets. Every token is counted in exactly one, so their plain sum is the total. `input` excludes cache reads and writes, while `output` excludes reasoning tokens when the provider reports them separately. A bucket that is absent reads as zero.
          - `input` integer — Prompt tokens that were neither read from nor written to a cache.
          - `output` integer — Completion tokens that are not reasoning tokens.
          - `reasoning` integer — Completion tokens spent on reasoning, priced at the output rate.
          - `cache_read` integer — Prompt tokens served from a provider cache.
          - `cache_write` integer — Prompt tokens written into a provider cache.
        - `cost` Cost — lithos `Cost`: a USD amount in micros and where it came from.
          - `usd_micros` integer, required
          - `source` 'catalog' | 'provider' | 'application', required — Where a cost came from: `catalog` (estimated from catalog prices), `provider` (the provider's own reported cost), or `application` (a sum the caller assembled from differently sourced parts).
      - `size` 'XS' | 'S' | 'M' | 'L' | 'XL', required — Run size bucket derived from the run's current cost.
      - `ask_fabro` AskFabro, required — Readiness and defaults for starting an Ask Fabro session on this run.
        - `available` boolean, required
        - `unavailable_reason` 'no_sandbox' | 'sandbox_not_ready' | 'llm_unconfigured' | 'null', nullable, required
        - `default_model` string, nullable, required
      - `diff` DiffSummary, required — 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.
      - `pull_request` PullRequestLink, required — 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.
      - `current_question` RunQuestion, required — A pending human-in-the-loop question summary.
        - `text` string, required — Question text.
      - `superseded_by` string, nullable, required — Run ID that superseded this run via rewind, if any.
      - `retried_from` string, nullable, required — Source run ID when this run was created by manual retry.
      - `links` RunLinks, required
        - `web` string, uri, nullable, required
    - `error` ErrorResponseEntry — A single error entry in an error response.
      - `status` string, required — HTTP status code as a string.
      - `title` string, required — Short error classification.
      - `detail` string, required — Human-readable error description.
      - `code` string — Optional machine-readable error code for structured client handling.
      - `request_id` string, uuid — Server-generated request identifier; matches the x-request-id response header.
  - `summary` BatchRunLifecycleSummary, required — Aggregate counts for a batch archive or unarchive request.
    - `requested` integer, required — Number of requested run IDs.
    - `succeeded` integer, required — Number of item results with `ok=true`.
    - `failed` integer, required — Number of item results with `ok=false`.

## Other responses

- `400` — Invalid batch request
- `401` — Not authenticated
- `500` — Request-level server error

## Changes

- **2026-09-14** `57ca921cdd38` — 1 breaking, 1 info
  - removed the required property `results/items/run/billing` from the response with the `200` status
  - added the required property `results/items/run/usage` to the response with the `200` status
- **2026-09-10** `478e995209e9` — 8 info
  - removed the `daytona` enum value from the `results/items/run/sandbox/oneOf[#/components/schemas/RunSandbox]/instance/oneOf[#/components/schemas/RunSandboxInstance]/provider` response property for the response status `200`
  - removed the `daytona` enum value from the `results/items/run/sandbox/oneOf[#/components/schemas/RunSandbox]/plan/provider` response property for the response status `200`
  - removed the `docker` enum value from the `results/items/run/sandbox/oneOf[#/components/schemas/RunSandbox]/instance/oneOf[#/components/schemas/RunSandboxInstance]/provider` response property for the response status `200`
  - removed the `docker` enum value from the `results/items/run/sandbox/oneOf[#/components/schemas/RunSandbox]/plan/provider` response property for the response status `200`
  - …4 more
- …earlier changes not shown

[Full history](https://skmtc.dev/fabro-sh/apis/fabro-run-api/changes/api/v1/runs/unarchive/post.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.dev/fabro-sh/apis/fabro-run-api/revisions/1258a4cf33df?raw)