---
title: "Update Run"
method: PATCH
path: "/api/v1/runs/{run_id}"
tags: ["runs"]
---

# Update Run

`PATCH /api/v1/runs/{run_id}`

## Request

- Base URL: `https://api.badgeia.com`
- URL: `https://api.badgeia.com/api/v1/runs/{run_id}`
- Auth: none declared

Update run status and result fields (used by agents to report outcomes).

**Model Sweep result contract (PRD-016, requires `SWEEPS_ENABLED`):**
report which model served the run plus token counts and Badge computes
the cost axis for your Hiring Frontier — no SDK, plain curl:

```bash
curl -X PATCH "$API/api/v1/runs/$RUN_ID" \
  -H "Content-Type: application/json" -b "$COOKIES" \
  -d '{
    "status": "completed", "success": true,
    "model": "claude-haiku-4-5",
    "input_tokens": 18234, "output_tokens": 2101,
    "unit_cost_override_usd": 0.021
  }'
```

Cost resolution for non-metered runs: known `model` in the pricing
table → computed from tokens; else `unit_cost_override_usd` (total $
for this run, 0–100) when given; else cost stays null. Any self-report
marks the run `self_reported` — it plots amber on the frontier and can
never mint a verified cert. Metered runs (Badge dispatched on a
customer key) reject these fields with 409 `run_is_metered`; while the
flag is off they return 400 `sweeps_disabled`.

## Path parameters

- `run_id` string, uuid, required

## Request body

- RunStatusUpdate
  - `status` 'pending' | 'running' | 'completed' | 'failed' | 'timeout', required
  - `success` boolean, nullable
  - `output` string, nullable
  - `error_message` string, nullable
  - `latency_ms` integer, nullable
  - `input_tokens` integer, nullable
  - `output_tokens` integer, nullable
  - `total_cost_usd` number, nullable
  - `retry_count` integer, nullable
  - `model` string, nullable
  - `unit_cost_override_usd` number, nullable: Per-task TOTAL cost for the run in USD. Sanity-capped at 100.

## Response `200`

Successful Response

- RunRead
  - `id` string, uuid, required
  - `agent_id` string, uuid, required
  - `agent_display_name` string, nullable
  - `agent_identity_state` 'active' | 'deactivated' | 'unavailable', nullable
  - `task_id` string, uuid, required
  - `status` 'pending' | 'running' | 'completed' | 'failed' | 'timeout', required
  - `started_at` string, date-time, nullable, required
  - `completed_at` string, date-time, nullable, required
  - `latency_ms` integer, nullable, required
  - `success` boolean, nullable, required
  - `output` string, nullable, required
  - `output_withheld` boolean
  - `error_message` string, nullable, required
  - `input_tokens` integer, nullable, required
  - `output_tokens` integer, nullable, required
  - `total_cost_usd` number, nullable, required
  - `evidence_cost_usd` number, nullable
  - `evidence_cost_source` string
  - `evidence_cost_partial` boolean
  - `evidence_priced_call_count` integer
  - `evidence_unpriced_call_count` integer
  - `evidence_total_call_count` integer
  - `retry_count` integer, required
  - `created_at` string, date-time, required
  - `answer_exposed` boolean
  - `provider_cost_authority` string, nullable
  - `screening_session_id` string, uuid, nullable
  - `repeat_index` integer, nullable
  - `repeat_total` integer, nullable
  - `architecture_hash` string, nullable
  - `previous_architecture_hash` string, nullable
  - `architecture_changed` boolean, nullable
  - `architecture_comparable` boolean
  - `architecture_change_summary` object, nullable
  - `architecture_span_count` integer
  - `certification_id` string, uuid, nullable
  - `certification_sequence` integer, nullable
  - `requested_model` string, nullable
  - `returned_model` string, nullable
  - `llm_provider` string, nullable
  - `usage_source` string, nullable
  - `model_pricing_id` string, uuid, nullable
  - `pricing_input_cost_per_million` number, nullable
  - `pricing_output_cost_per_million` number, nullable
  - `pricing_effective_date` string, date, nullable
  - `error_class` string, nullable
  - `response_status` integer, nullable
  - `error_body_excerpt` string, nullable
  - `execution_mode` string, nullable
  - `verification_hash` string, nullable
  - `signed_at` string, date-time, nullable
  - `key_id` string, nullable
  - `public_certificate_state` 'verified' | 'simulated' | 'unsigned' | 'invalid'
  - `suite_id` string, nullable
  - `suite_version` integer, nullable
  - `model` string, nullable
  - `cost_provenance` string, nullable
  - `cost_basis` 'metered' | 'traced' | 'traced_partial' | 'self_reported' | 'unavailable', nullable
  - `scored_cost_usd` number, nullable
  - `provenance_level` string, nullable
  - `manifest_hash` string, nullable
  - `provenance_flags` string[], required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/badgeia/apis/badge.md) · [All operations](https://skmtc.dev/badgeia/apis/badge/llms.txt) · [OpenAPI document](https://skmtc.dev/badgeia/apis/badge/revisions/7e7f7fee8b77?raw)