Skip to content
Kindgi

List deleted rows scheduled for purging

View as Markdown
GET
/v1/retention/scheduled
curl --request GET \
  --url 'https://example.com/v1/retention/scheduled?domain=org&pastGraceOnly=false&limit=25' \
  --header 'Authorization: Bearer <token>'

Tombstoned rows in every domain a retention policy or this server’s retention limit covers, with when each is purged (purgeAt) and what decides it: the policy (policyId), or the limit (limitApplied) when no policy covers the domain or its policy keeps rows longer. domainsMissingAdapter names the covered domains this deployment can’t purge; unpolicedDomains the ones neither covers, whose tombstones are kept; conflicts the domains two policies cover (stored before one policy per domain was enforced). limit caps the rows per domain; hasMore says some domain has more than it returned, and nextCursor (when the runtime can continue) is the cursor for the next page. Requires admin on the tenant.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
domain

The kind of record a retention policy covers. * covers every domain without a policy of its own, except memory and conversation: they hold people’s words, so only a policy naming them purges them.

string
Allowed values: org agent flow tool eval_suite guardrail mcp_endpoint env secret run artifact policy judgment judge_class provider memory conversation api_key service_account *

Only this domain. Absent: every domain.

pastGraceOnly
boolean

true: only rows past their grace, the ones a sweep would purge now.

limit
integer
default: 25 >= 1 <= 100

1..100. Default 25.

cursor
string

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”

200

Section titled “200”

Scheduled rows.

Media typeapplication/json
object
data
required
Array<object>
object
domain
required

The kind of record a retention policy covers. * covers every domain without a policy of its own, except memory and conversation: they hold people’s words, so only a policy naming them purges them.

string
Allowed values: org agent flow tool eval_suite guardrail mcp_endpoint env secret run artifact policy judgment judge_class provider memory conversation api_key service_account *
id
required

The tombstoned row’s id in its domain.

string
unregisteredAt
required
string format: date-time
purgeAt
required

unregisteredAt plus graceSeconds: when a sweep purges the row.

string format: date-time
pastGrace
required

Whether a sweep would purge the row now.

boolean
policyId

The retention policy that covers the domain. Absent when none does, and this server’s limit decides (limitApplied); always present on a server with no limit.

string
policyVersion

The policy’s version. Absent with policyId.

string
graceSeconds
required

How long the row is kept, in seconds (-1: a hold, never purged): the policy’s grace, or this server’s limit (limitApplied).

integer
limitApplied

Present when this server’s retention limit for the domain set graceSeconds: no policy covers the domain, or its policy keeps rows longer than the limit, or holds them.

boolean
hasMore

Some domain has more scheduled rows than this page returned (limit is per domain). Always sent from 0.1.4; a runtime before it sends none.

boolean
nextCursor

The cursor for the next page. Absent when hasMore: false, or when the runtime cannot continue a page.

string
domainsMissingAdapter
required

Domains a retention policy covers that this deployment can’t purge (no adapter is wired).

Array<string>
Allowed values: org agent flow tool eval_suite guardrail mcp_endpoint env secret run artifact policy judgment judge_class provider memory conversation api_key service_account *
unpolicedDomains
required

Domains no retention policy covers and this server sets no retention limit for: their tombstones are kept.

Array<string>
Allowed values: org agent flow tool eval_suite guardrail mcp_endpoint env secret run artifact policy judgment judge_class provider memory conversation api_key service_account *
conflicts

Domains more than one retention policy covers. Absent or empty: none.

Array<object>
object
domain
required

The kind of record a retention policy covers. * covers every domain without a policy of its own, except memory and conversation: they hold people’s words, so only a policy naming them purges them.

string
Allowed values: org agent flow tool eval_suite guardrail mcp_endpoint env secret run artifact policy judgment judge_class provider memory conversation api_key service_account *
policyIds
required

Every policy id that covers the domain, sorted.

Array<string>
>= 2 items
appliedPolicyId
required

The one that applies: the policy whose latest version is highest, and on equal versions the lower policy id. Unregister the others.

string
Example
{
  "data": [
    {
      "domain": "org",
      "limitApplied": true
    }
  ],
  "domainsMissingAdapter": [
    "org"
  ],
  "unpolicedDomains": [
    "org"
  ],
  "conflicts": [
    {
      "domain": "org"
    }
  ]
}

400

Section titled “400”

Unknown domain.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

403

Section titled “403”

Not a tenant admin.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also