ROADMAP-08 — P1 — GET /runs list endpoint with pagination (store side already implemented) #100

Series: ROADMAP — filed from the 2026-10-27 whole-project assessment · Backlog task: M15-T01 · Priority: P1 · Effort: small

Problem

PostgresMemoryStore.list_runs (session filter + limit) is fully implemented and tested, and TieredMemoryStore forwards it — but no route exposes it. The cheapest high-value gap in the API surface.

Related gaps in the same PR scope:

• No pagination anywhere (store takes a limit; no offset/cursor)
• order_by(Run.created_at.desc()) does a full-scan sort the moment an endpoint exists — needs the matching index
• Generated OpenAPI models have no error responses declared (400/401/404/429/503), and RunResponse.status is a bare str instead of the RunStatus enum

Evidence

• agentkit/memory/pg_store.py:123–152 — implemented, tested, unexposed
• agentkit/memory/tiered.py:91–100 — forwarded
• agentkit/api/routes.py — only POST /runs, GET /runs/{id}, GET /runs/{id}/trace
• agentkit/db/models.py — indexes exist for session_id and (run_id, step_no) only
• agentkit/api/schemas.py:35 — status: str

Suggested fix / acceptance criteria

• GET /runs with limit/offset (or keyset on created_at) + optional session_id filter, auth-protected
• Alembic migration adds runs(created_at DESC) (or (session_id, created_at DESC)) index
• Route metadata declares its error responses; RunResponse.status becomes the RunStatus enum
• Integration tests (hermetic + real-infra tier)

Suggested branch / commit

feat/run-list-endpoint · feat(api): add GET /runs with pagination and runs.created_at index