Skip to content
Kindgi

List deleted rows scheduled for purging

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 covers, with when each is purged (purgeAt) and the policy that decides it. domainsMissingAdapter names the covered domains this deployment can’t purge; unpolicedDomains the ones no policy 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 the policy’s grace: when a sweep purges the row.

string format: date-time
pastGrace
required

Whether a sweep would purge the row now.

boolean
policyId
required

The retention policy that applies.

string
policyVersion
required
string
graceSeconds
required

The policy’s grace, in seconds (-1: a hold, never purged).

integer
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: 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"
    }
  ],
  "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"
  }
}