Skip to main content
GET/migrations/pending

List Pending Migrations

Returns the list of pending-migration records for the project, filterable by status (queued, applied, rejected, or cancelled) via the ?status= query parameter.

Terminal rows (applied, rejected, cancelled) are retained indefinitely for audit-trail integrity.

Requires any project member role (PROJECT_VIEWER or above).

Authorized by the IAM action migrations:read (every project role holds it by default; a workload needs it on its bound IAM policy; a project service token reads as its scope's role).

Parameters
projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Responses
HTTPK9O CodeDescription
200Success
401K9O_SESSION_EXPIREDYour session has expired; re-authenticate and retry.
403K9O_ACCESS_DENIEDYou must hold at least a viewer role on the project to list pending migrations.
403K9O_IAM_POLICY_DENIEDThe bound IAM policy ceiling denies migrations:read (for a workload: its bound policy does not grant it).
Response body (200)
data *object[]

Pending migrations in the requested status (default queued), most recently queued first.

id *string

The pending migration's id (pmig_...).

version *integer

The migration's version, an integer from 1 to 2147483647.

Versions apply in ascending order.

slug *string

The migration's slug, as given when it was submitted.

checksum *string

SHA-256 (hex) of the migration's canonical JSON (version, slug, up, down, policy).

Re-applying a version with a different checksum is refused.

status *"queued" | "pending_approval" | "applied" | "rejected" | "cancelled"

queued: waiting for a project admin to apply it. pending_approval: it touches a protected collection (or loosens a collection's gate scope), so a linked approval that a different admin must grant governs it. applied, rejected, cancelled: decided.

affectedCollections *string[]

The collections the migration's operations and policy section touch.

approvalId *any

The linked approval (apr_...) when the migration is governed by one; otherwise null.

One of: string
or: null
queuedAt *string <date-time>

When the migration was queued.

queuedBy *string

The id of the principal who queued it.

decidedAt *any

When it was applied, rejected or cancelled; null while undecided.

One of: string <date-time>
or: null
decidedBy *any

The id of the principal who decided it; null while undecided.

One of: string
or: null
decisionReason *any

The reason recorded when it was rejected (empty when none was given) or cancelled (always empty); null while undecided or when it was applied.

One of: string
or: null
meta *any

Request metadata: cost, timing and correlation ids.

TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.migrations.listPending()

Showing example in TypeScript

Response example (200)
{
  "data": [
    {
      "id": "string",
      "version": 0,
      "slug": "string",
      "checksum": "string",
      "status": "queued",
      "affectedCollections": [
        "string"
      ],
      "approvalId": "string",
      "queuedAt": "string",
      "queuedBy": "string",
      "decidedAt": "string",
      "decidedBy": "string",
      "decisionReason": "string"
    }
  ]
}

More in Storage & Schema