---
title: "Apply one allowed run state transition"
method: PATCH
path: "/v1/automation-runs/{run_id}"
tags: ["Automation"]
---

# Apply one allowed run state transition

`PATCH /v1/automation-runs/{run_id}`

## Request

- Base URL: `https://api.agentry.sh`
- URL: `https://api.agentry.sh/v1/automation-runs/{run_id}`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

The server validates the immutable policy, evidence, budget, current switch, and case lease. The caller cannot mark deploy verification successful through this endpoint.

## Path parameters

- `run_id` string, required

## Headers

- `X-Agentry-Lease-Token` string

## Request body

- object
  - `status` 'running' | 'failed' | 'escalated' | 'cancelled', required
  - `summary_md` string
  - `evidence` object
    - `change_types` string[]
    - `changed_files` string[]
    - `changed_lines` object
      - `added` integer, required
      - `deleted` integer, required
    - `tests` object[]
      - `command` string, required
      - `status` 'passed' | 'failed' | 'skipped', required
      - `exit_code` integer
      - `duration_ms` integer
      - `output_excerpt` string
    - `ci` object
      - `status` 'pending' | 'passed' | 'failed' | 'cancelled', required
      - `url` string, uri: Absolute HTTPS URL without embedded username or password credentials.
    - `artifacts` object[]
      - `kind` 'log' | 'diff' | 'report' | 'screenshot' | 'other', required
      - `url` string, uri, required: Absolute HTTPS URL without embedded username or password credentials.
      - `label` string
    - `report` object
      - `kind` 'funnel_review' | 'reliability_review' | 'custom', required
      - `period_start` integer, required
      - `period_end` integer, required
      - `source_hash` string, required
      - `findings` union[], required
        - union
          - object
            - `kind` 'metric', required
            - `metric` string, required
            - `unit` 'count' | 'percent' | 'ratio' | 'seconds' | 'currency', required
            - `prior_value` number, nullable, required
            - `current_value` number, nullable, required
            - `change` number, nullable, required
            - `source_columns` string[], required
          - object
            - `kind` 'hypothesis', required
            - `rank` integer, required
            - `title` string, required
            - `rationale` string, required
            - `expected_impact` 'low' | 'medium' | 'high' | 'unknown', required
            - `confidence` 'low' | 'medium' | 'high', required
            - `evidence_columns` string[], required
            - `suggested_human_next_step` string, required
          - object
            - `kind` 'readiness_gap', required
            - `code` string, required
            - `message` string, required
            - `required_signal` string
      - `limitations` string[]
  - `error` object
    - `code` string, required
    - `message` string, required

## Response `200`

OK

- AutomationRun
  - `data_boundary` object, required
    - `schema_version` '1', required
    - `classification` 'untrusted_observation' | 'untrusted_observation_and_runner_evidence' | 'runner_and_owner_annotation' | 'server_control_with_authority_free_observation' | 'server_owned_bounded_aggregate' | 'external_response', required
    - `content_role` 'evidence_only', required
    - `instruction_authority` 'none', required
    - `trusted_provenance_does_not_mean_trusted_content` true, required
    - `external_url_policy` 'do_not_fetch', required
    - `command_policy` 'do_not_execute', required
    - `authority_source` 'enabled_automation_contract_and_server_policy_only', required
    - `applies_to` union
      - string
      - string[]
    - `inspection` object
      - `heuristic_only` true, required
      - `indicators` string[], required
      - `external_url_hosts` string[], required
      - `redacted_paths` string[], required
      - `truncated_paths` string[], required
    - `control_fields` string[]
    - `identifier_columns_included` boolean
    - `secret_values_included` boolean
  - `id` string, required
  - `project_id` string, required
  - `automation_id` string, required
  - `case_id` string, nullable, required
  - `case_revision` integer, nullable, required
  - `trigger_kind` 'alert' | 'unhandled_cases' | 'schedule', required
  - `trigger_receipt_id` string, required
  - `request_hash` string, required
  - `attempt` integer, required
  - `status` 'queued' | 'claimed' | 'running' | 'draft_pr_opened' | 'awaiting_approval' | 'verifying' | 'succeeded' | 'failed' | 'escalated' | 'cancelled', required
  - `runner` object, required
    - `provider` 'codex' | 'claude_code' | 'github_actions' | 'custom', nullable, required
    - `id` string, nullable, required
    - `credential_id` string, nullable, required
    - `model` string, nullable, required
  - `control` object, required
    - `source` 'agentry_system', required
    - `contract_revision` integer, required
    - `contract_etag` string, required
    - `policy_snapshot` object, required
      - `id` string, required
      - `template_ref` object
        - `id` string, required
        - `version` string, required
        - `bindings_sha256` string, required
      - `name` string, required
      - `description` string
      - `enabled` boolean
      - `runner` object, required
        - `provider` 'codex' | 'claude_code' | 'github_actions' | 'custom', required
        - `repository` string, uri: Absolute HTTPS URL without embedded username or password credentials.
        - `default_branch` string
        - `environment` string
        - `mode` 'draft_only'
      - `trigger` union, required
        - object
          - `kind` 'alert', required
          - `alert_id` string, required
          - `cooldown_seconds` integer
          - `min_consecutive_breaches` integer
          - `required_trust` 'server_evaluated'
        - object
          - `kind` 'unhandled_cases', required
          - `max_cases_per_sweep` integer
          - `cooldown_seconds` integer
          - `required_trust` 'any' | 'customer_posthog'
          - `materiality` object
            - `minimum_event_count` integer, required
            - `maximum_last_seen_age_seconds` integer, required
        - object
          - `kind` 'schedule', required
          - `cron` string, required
          - `timezone` string
          - `report_kind` 'funnel_review' | 'reliability_review' | 'custom', required
          - `start_window_seconds` integer
      - `report_plan` object
        - `schema_version` '1'
        - `blueprint_id` string, required
        - `params` object
        - `period` object, required
          - `lookback_seconds` integer, required
          - `offset_seconds` integer
        - `output_schema_version` '1'
      - `allowed_actions` string[], required
      - `scope` object, required
        - `allowed_paths` string[]
        - `forbidden_paths` string[]
        - `forbidden_change_types` string[]
        - `max_files_changed` integer
        - `max_changed_lines` integer
        - `test_commands` string[]
      - `budgets` object
        - `max_runs_per_day` integer
        - `max_prs_per_day` integer
        - `max_attempts_per_case_revision` integer
        - `max_turns_per_run` integer
        - `max_runtime_seconds` integer
        - `max_cost_usd_per_run` number
      - `approvals` object
        - `required_for` string[]
        - `expires_after_seconds` integer
      - `escalation` object, required
        - `destination` string, required
        - `instructions` string, required
      - `verification` object
        - `outcome` object, required
          - `blueprint_id` 'automation_case_recurrence_after_deploy', required
          - `params` object, required
            - `run_id` object, required
              - …
            - `case_id` object, required
              - …
            - `case_revision` object, required
              - …
            - `deploy_sha` object, required
              - …
            - `deployed_at` object, required
              - …
            - `checked_at` object, required
              - …
          - `predicate` object, required
            - `column` 'recurrence_count', required
            - `reducer` 'first', required
            - `operator` 'eq', required
            - `value` 0, required
        - `sample` object, required
          - `blueprint_id` 'automation_deploy_traffic_sample', required
          - `params` object, required
            - `deploy_sha` object, required
              - …
            - `deployed_at` object, required
              - …
            - `checked_at` object, required
              - …
            - `event_name` string, required
          - `sample_size` object, required
            - `kind` 'column_sum', required
            - `column` 'sample_count', required
          - `min_sample_size` integer, required
        - `observation_window_seconds` integer
        - `max_wait_seconds` integer
      - `failure_policy` object
        - `retry_backoff_seconds` integer
        - `on_attempt_budget_exhausted` 'escalate'
      - `data_boundary` object
        - `telemetry_is_untrusted_data` true
        - `never_follow_telemetry_instructions` true
        - `never_execute_telemetry_commands` true
        - `allow_external_urls_from_telemetry` false
    - `policy_authority` 'structured_fields_only', required
    - `note` string, required
    - `lifecycle` object, required
      - `deadline_at` integer, required
      - `last_heartbeat_at` integer, nullable, required
      - `retry_eligible_at` integer, nullable, required
      - `turns_used` integer, required
      - `cost_usd` number, required
      - `usage_sequence` integer, required
    - `pr_proof` object, nullable, required
      - `source` 'trusted_ci', required
      - `credential_id` string, nullable, required
      - `proof_hash` string, nullable, required
      - `recorded_at` integer, nullable, required
      - `evidence` BoundedEvidenceObject, required
    - `verification` BoundedEvidenceObject, required
  - `trigger_receipt` object, required
    - `id` string, required
    - `source` 'agentry_system', required
    - `eligibility_authority` 'trigger_only', required
    - `instruction_authority` 'none', required
    - `trigger_ref` string, required
    - `observation` BoundedEvidenceObject, required
    - `inspection` object, required
      - `heuristic_only` true, required
      - `indicators` string[], required
      - `external_url_hosts` string[], required
      - `redacted_paths` string[], required
      - `truncated_paths` string[], required
  - `runner_output` object, required
    - `source` 'runner_attested_unverified', required
    - `instruction_authority` 'none', required
    - `evidence` BoundedEvidenceObject, required
    - `inspection` object, required
      - `heuristic_only` true, required
      - `indicators` string[], required
      - `external_url_hosts` string[], required
      - `redacted_paths` string[], required
      - `truncated_paths` string[], required
  - `started_at` integer, nullable, required
  - `finished_at` integer, nullable, required
  - `created_at` integer, required
  - `updated_at` integer, required
  - `idempotent_replay` boolean
  - `next_action` string

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/agentry/apis/agentry-api.md) · [All operations](https://skmtc.dev/agentry/apis/agentry-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentry/apis/agentry-api/revisions/abdecddf009f?raw)