--- title: "Archive Runs" method: POST path: "/api/v1/runs/archive" tags: ["Runs"] --- # Archive Runs `POST /api/v1/runs/archive` Marks up to 250 terminal runs as archived in one fail-soft, non-transactional request. Each run is processed independently and successful items emit the same per-run archive events as `POST /api/v1/runs/{id}/archive`. 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 - `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` '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 - `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`. - `billing` RunBillingSummary, required - `total_usd_micros` integer, nullable, required - `size` 'XS' | 'S' | 'M' | 'L' | 'XL', required — Run size bucket derived from current best-effort billed usage. - `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 --- [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/revisions/bee030053823/schema)