List a webhook endpoint's deliveries
const url = 'https://example.com/v1/webhook-endpoints/example/deliveries?status=pending&limit=25';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://example.com/v1/webhook-endpoints/example/deliveries?status=pending&limit=25' \ --header 'Authorization: Bearer <token>'Newest first. Each delivery carries the event it delivers.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The webhook endpoint id.
Query Parameters
Section titled “Query Parameters”pending: waiting for its next attempt. delivered: the endpoint answered 2xx. failed: every attempt failed, or the endpoint was unregistered first; redeliver queues it again.
Only deliveries with this status.
1..100. Default 25.
Where the previous page ended: its nextCursor, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise 400 bad-input, and the list starts again without it. Absent → first page.
Responses
Section titled “Responses”Page of deliveries.
object
object
object
Event id, also sent as the webhook-id header; the same on every retry.
object
A finished top-level run: its identity and outcome, never its input or output. Field names match GET /v1/runs/{runId}.
object
RunId.
Why the run failed or was cancelled; null when it completed.
A failed run’s error, as GET /v1/runs/{runId} reads it back: its code, and the error’s own details when it has them. Absent unless the run failed, and from a runtime that doesn’t send it yet; read failureMessage then.
object
What the error came from, when it says: e.g. for capability-routing-failed, the router’s capability-unsatisfiable with its reasons, by provider.
The error’s own reason, when it gives one: for a turn that ended at its approval (hitl-cancelled), timeout when nobody decided in time. Absent from an older runtime and from errors without one; read code then.
The error’s own facts, for a code that has them: for rate-limit-exceeded, limit (the budget that refused: schema-compile-time or template-render-time) and budgetMs, the names the API’s 429 uses. Never the wait: read back later, it’s stale. Absent for any other code, and from an older runtime.
object
The model calls of the run tree (this run and every run it started) that the cost ledger had recorded when this run finished: a child run still running then isn’t in it. calls counts failed calls too. Absent when the runtime records no usage.
object
object
On an agent’s run: the agent, the version that ran and the conversation, as GET /v1/runs/{runId} shows them (an agent run’s flowId is agent.turn). Absent on a flow’s run, and from a runtime before Kindgi 0.1.6.
object
The agent id.
The agent version that ran (semver).
Why this version ran: named by the caller (explicit); held by the flow version a flow’s agent step runs in (flow-pin: the node’s config.version, else the version the flow version pinned when it was published); the conversation’s own (conversation); the version pinned for the run’s scope (pinned); or the latest, nothing being pinned (latest). Absent on runs from before Kindgi 0.1.4.
The whole tenant.
object
An org’s projects.
object
One project.
object
A segment path within a project: it covers every run whose path starts with it.
object
object
Lowercase, like an identifier: company, contact-role.
An Improve run ended (completed, failed or cancelled): one a person started, or one an improve schedule did. Its outcome names the suggested change it wrote, if it wrote one.
object
Event id, also sent as the webhook-id header; the same on every retry.
object
The Improve run, as GET /v1/improve-runs/{improveRunId} shows it.
object
The project it works in. Absent from older servers, and on a run started for a tenant or an org before Improve runs worked in a project.
The version an Improve run starts from: the one the project runs, pinned there (pin) or the agent’s latest (latest).
object
The version of the project’s test set it searches and proves on; absent until it’s frozen.
The test set’s cases set aside for the proof: cases of of. None with fewer than five. Absent from older servers.
object
The tiers it tries, the prompt tier first.
Which corrections its comparisons count.
For the prompt tier: the provider and model that drafts the templates.
object
For the prompt tier: how many templates it drafts.
object
The most the Improve run’s comparisons may cost, in US dollars.
The most candidates it compares.
user:<id> or service:<id>.
Candidates tried so far.
What its comparisons have cost so far (US dollars).
A change passed more cases than the version the run started from, and failed none that passed: the run wrote it as a suggested change for a reviewer to decide.
object
No change the run tried did better: reason says why, and holdOut has the best change’s numbers when one got that far.
object
The best change’s proof numbers, when one got that far: on every case, or on the set-aside part for a run stored before that.
object
The run reached its budget with nothing kept.
object
What it spent, in US dollars.
The run failed: message says why.
object
The ids of the corrections it took when it started. Absent from older servers.
Why a cancelled Improve run stopped when nobody cancelled it: a comparison’s test run was cancelled for it (that run’s cancelReason, e.g. project-suspended). It wrote no suggested change. Absent when it was cancelled.
Its comparisons so far, each a test run to open: reference (the version as it is, on each part: what the proof is held to, case by case), each candidate (the block and the values it changed, on the search part: what picks the change to suggest), and the proof (the suggested change, on all the cases at the reference’s repetitions: what keeps it or not; an Improve run from before 0.4 ran its proof on the hold-out part). Absent from older servers.
object
object
For a drafted template that was never compared: why the check refused it (what it reads or names that the agent doesn’t have, or its size).
object
For a drafted template: what the drafter meant it to change.
The improve schedule and fire that started it (GET /v1/schedules/{triggerId}/fires); absent for an Improve run a person started.
object
An approval was asked for: a reviewer’s decision is waiting. Sent once per approval (an escalation is a new approval). projectId in the endpoint’s filter narrows it to the approval’s project.
object
Event id, also sent as the webhook-id header; the same on every retry.
object
The approval an approval.requested event names. What it is about stays behind sign-in: no context, no tool call or run input.
object
The least reviewer role that may decide it.
The one reviewer it is assigned to, when it is.
Its page in the console, when the runtime knows its public address.
object
object
pending: waiting for its next attempt. delivered: the endpoint answered 2xx. failed: every attempt failed, or the endpoint was unregistered first; redeliver queues it again.
HTTP status of the last attempt; null when it got no response.
Why the last attempt failed (timeout, connection-refused, url-refused, …).
Example
{ "data": [ { "event": { "type": "run.finished", "data": { "run": { "status": "completed", "agent": { "via": "explicit", "pinnedScope": { "kind": "tenant" } } } } }, "status": "pending" } ]}Unknown status.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Missing / malformed / expired / revoked bearer token.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Not a tenant admin (permission-denied). Without an authorization store, a tenant admin is the deployment’s API token, an admin key, or a console signed in with either.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}No endpoint with that id.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try again.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}See also
GET /v1/webhook-endpoints/{endpointId}: Fetch a webhook endpointPATCH /v1/webhook-endpoints/{endpointId}: Update a webhook endpointPOST /v1/webhook-endpoints/{endpointId}/unregister: Unregister a webhook endpoint (soft delete)POST /v1/webhook-endpoints/{endpointId}/deliveries/{deliveryId}/redeliver: Redeliver an event- Error code
database-busy - Error code
permission-denied - Every error code