Read a category's demand-driven pacing state (console plane)

GET

/v1/admin/orgs/{org_id}/projects/{project_id}/categories/{id}/pacing-state

• Production
• Local

Read the demand-driven pacing snapshot: the human review cursor, the effective window/ceiling/interval, the queued count, and each draft’s in-window / redrafting / behind-cursor classification (the “redrafting…” shimmer). The agent-plane read (GET /v1/categories/{id}/pacing-state) is AgentKey-only, so the console reads the SAME view here (Clerk session). Read-only; a foreign id is 404.

Authorizations

• ClerkSession

Parameters

Path Parameters

org_id

required

string

project_id

required

string

id

required

string

Responses

200

Ok

The demand-driven pacing snapshot for a category (agent-readable, $0-LLM, M7 Slice B/§8): the human review cursor position, the effective window/ceiling/ interval, the queued count, and each queued draft’s in-window/redrafting/ behind-cursor classification. Read-only; the cursor advances from the human’s console approve/reject/edit actions.

object

category_id

required

string

cursor_review_id

The last queued draft the human acted on (the cursor); omitted when nothing reviewed yet.

string

cursor_advanced_count

required

Monotonic count of cursor advances.

integer

lookahead_window

required

Effective freshness window (default org_settings.lookahead_window=3).

integer

rework_batch_max

required

HARD per-nudge fan-out ceiling (default org_settings.rework_batch_max=10); one nudge can never fan to 500.

integer

nudge_min_interval_ms

required

Per-agent token-bucket interval that coalesces feedback storms (default 5000).

integer

queued

required

How many drafts are in the human queue (needs_review|in_review|chatting).

integer

in_window

required

Of the queued, how many sit in the freshness-guaranteed window.

integer

redrafting

required

Of the in-window, how many are stale and being redrafted (the console shimmer set).

integer

items

required

Array<object>

One queued draft’s pacing classification relative to the human review cursor + lookahead window (M7 Slice B/§8). $0-LLM (a cheap integer staleness compare).

object

review_id

required

string

state

required

Behind_cursor = the human has reviewed past it; in_window_fresh = in the freshness-guaranteed window and current-enough; in_window_redrafting = in the window but stale (a redraft is in flight; the console shows a shimmer); ahead = queued beyond the window, not yet freshness-guaranteed.

string

Allowed values: behind_cursor in_window_fresh in_window_redrafting ahead

401

Missing or invalid credential.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

403

Authenticated but lacking the required scope, or out of quota.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

404

Resource not found.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope