reflect_status

Category: reflection
Access: read
Audience: advanced (ordinary users do not normally call this directly)

Purpose

Returns one run's state, inputs, and decision counts. Call it to check progress before reviewing, deciding, or applying.

Arguments

Required: run_id.

run_id.

Result

Object with run (run_id, version, status, model, instructions, error fields, usage, created_by, timestamps), inputs array, and candidate_counts (pending, accept, reject, defer, total).

Boundaries

Unfiltered or foreign runs read as not-found for non-star callers; discarded entries read as absent exactly like missing ones.

Lifecycle / side effects

Pure read over the persisted run, its inputs, and live decision counts.

Errors

Unknown, discarded, or foreign runs fail as not_found. Missing run_id rejected by validation. Backend failures return normal internal_error payloads.

Example

{
  "run_id": "<uuid>"
}

Result shape:

{
  "candidate_counts": {
    "accept": 1,
    "defer": 0,
    "pending": 2,
    "reject": 0,
    "total": 3
  },
  "inputs": [],
  "run": {
    "run_id": "<uuid>",
    "status": "completed"
  }
}