reflect_history

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

Purpose

Paginated newest-first list of reflection runs. Call it to find past runs and their outcomes before drilling into status or review.

Arguments

Optional: include_archived, limit, offset, status_filter.

include_archived. Note: Defaults false; hides archived runs unless true.
limit. Note: Defaults 20, clamped 1 to 100.
offset. Note: Pagination cursor; negative behaves as 0.
status_filter. Note: One of pending, running, completed, failed, canceled; anything else is an error.

Result

Object with runs array (run_id, version, status, model, instructions, error fields, usage, created_by, timestamps), total, limit, offset, include_archived, and status_filter.

Boundaries

Non-star callers see only runs whose input project is granted; discarded entries are always excluded.

Lifecycle / side effects

Pure read over persisted runs, newest first.

Errors

Unknown status_filter fails as unknown_status. Backend failures return normal internal_error payloads.

Example

{
  "limit": 20
}

Result shape:

{
  "limit": 20,
  "offset": 0,
  "runs": [
    {
      "run_id": "<uuid>",
      "status": "completed"
    }
  ],
  "total": 1
}