Skip to content
Elicitly

elicit_history

Give a calling agent a programmatic way to retrieve elicitation history — the gap the human-only dashboards leave.

When to use

Section titled “When to use”

An agent that lost an elicitationId, wants to reconcile what it submitted, or needs to audit past decisions has no other tool for this. It returns the summary projection only — fetch bodies by id from elicit_result.

Input

Section titled “Input”
Parameter Type Required Description
scope "me" | "org" no Default "me" — the caller’s own requests (mirrors the personal /dashboard view). "org" returns every request across the caller’s organization (mirrors /dashboard/org) and is admins only — a non-admin (or a caller with no organization) gets an error result, not partial data.
page number no 1-based. Default 1.
pageSize number no 1–100. Default 25.
asOf string no ISO 8601 timestamp anchoring the page window. Defaults to the server’s current time. Echoed back in the output — pass that same value on later page calls to keep the window stable. See The asOf anchor. 
{ "scope": "me", "page": 1, "pageSize": 25 }

Output

Section titled “Output”
{
  "items": [
    {
      "elicitationId": "…",
      "message": "Deploy to prod?",
      "status": "approved",
      "createdAt": "2026-07-30T12:00:00.000Z",
      "decidedAt": "2026-07-30T12:04:11.000Z"
    }
  ],
  "page": 1,
  "pageSize": 25,
  "asOf": "2026-07-31T09:00:00.000Z",
  "total": 137,
  "scope": "me"
}
  • items — one summary entry per request, newest first (createdAt DESC, elicitationId DESC). createdAt and decidedAt are full-precision strings; decidedAt is null for a request that hasn’t been decided yet.
  • page / pageSize — echoed back (post-clamp).
  • asOf — the anchor actually used, as an ISO string: either the value you passed or the server’s now if you omitted it (or passed something unparseable — an unparseable asOf never errors, it just falls back to now).
  • total — the count of rows matching the scope predicate as of asOf, independent of page. Use it to compute the last page: Math.ceil(total / pageSize). A page past the end returns items: [] with the real total, not an error — so the agent can tell it overshot.
  • scope — echoed back.

Item bodies — context and formSubmission — are not included here; fetch those by id from elicit_result once you have the elicitationId. elicit_history only returns the summary projection.

There is no status filter yet — every request in scope is included regardless of pending / approved / rejected / consumed / expired.

The asOf anchor

Section titled “The asOf anchor”

Unlike the dashboards’ sequential (keyset) browsing, elicit_history supports jump-to-page random access, which needs an offset plus a total count. Plain offset pagination normally drifts when new rows are inserted between page fetches — row 26 today might be row 27 tomorrow. elicit_history avoids that by pinning every page to the same asOf timestamp: it only ever returns rows with createdAt <= asOf. Because the underlying table is append-only — rows are never deleted or edited after createdAt is set — pinning the same asOf across calls freezes the exact same row set, however many new requests land in the meantime. Fetch page 1 without asOf, then pass the asOf you got back on every subsequent page for a stable, drift-free walk through the history as it stood at that moment.

Dashboards

Section titled “Dashboards”

The hosted Pro server also serves human-facing dashboards — /dashboard for an individual’s own history, /dashboard/org for an organization’s (admins only) — which elicit_history mirrors the scope and authorization rules of. The dashboards are for browsing in a browser; elicit_history is for an agent that needs the same data back as structured tool output.

Section titled “Related”