Book a demo

get_purge_readiness

Read whether an org's purge is ready

read entity tenant-private since 2026-10-01

For an org whose deletion is scheduled: whether its purge may be approved and run, as a checklist of three lines, Countdown ended, Dry run and Approvals, each pass, fail or pending with one line of evidence. Answers the countdown, the current dry run (the newest; a newer one supersedes it) with what it counted, the approvals of that dry run, ready, and the codes that block. Refused for an org with no deletion scheduled. Trade HQ staff only.

Contract

shape
entity
authority
read
evidence
none
subscription
false
permission
any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first
idempotency
safe
emits
none
MCP tool
get_purge_readiness
REST
POST https://api.containertradehq.com/v1/cap/get_purge_readiness

Idempotency: a read: calling again changes nothing

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org whose deletion is scheduled.

Response

  • org_id · string · The org.
  • state · string · Where the org is in its life: deletion_scheduled whenever this answers.
  • countdown · object · {purge_after, ended}: when the 30 day countdown ends, and whether it has.
  • dry_run · objectnull · The round's current dry run, the newest: running, ready (counts written), failed, stopped (the purge job's recount differed; stopped says how) or purged. A dry run running past ten minutes reads failed. Null when none has been run.
  • approvals · object · The approvals of the current dry run while it is ready: one principal's is the quorum (needed 1), else two different staff's. Empty otherwise: approvals of a superseded or stopped dry run no longer count.
  • checks · object[] · The checklist, in order: Countdown ended, Dry run, Approvals.
  • ready · boolean · Every line passes: the purge job may run.
  • blocking · string[] · What stands in the way, once each, in line order: countdown_running, purge_dry_run_required, purge_dry_run_running or purge_approvals_needed. Empty when ready.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "org_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The org.",
      "x-data-class": "operational"
    },
    "state": {
      "type": "string",
      "enum": [
        "active",
        "suspended",
        "deletion_scheduled",
        "purged"
      ],
      "description": "Where the org is in its life: deletion_scheduled whenever this answers.",
      "x-data-class": "operational"
    },
    "countdown": {
      "type": "object",
      "description": "{purge_after, ended}: when the 30 day countdown ends, and whether it has.",
      "x-data-class": "operational"
    },
    "dry_run": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "dry_run_id": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "running",
            "ready",
            "failed",
            "stopped",
            "purged"
          ]
        },
        "requested_at": {
          "type": "string",
          "format": "date-time"
        },
        "requested_by": {
          "type": "string"
        },
        "requested_by_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "finished_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "counts": {
          "type": [
            "object",
            "null"
          ]
        },
        "failure": {
          "type": [
            "string",
            "null"
          ]
        },
        "stopped": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "at": {
              "type": "string",
              "format": "date-time"
            },
            "code": {
              "type": "string",
              "enum": [
                "purge_counts_changed"
              ]
            },
            "detail": {
              "type": "string"
            }
          },
          "required": [
            "at",
            "code",
            "detail"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "dry_run_id",
        "status",
        "requested_at",
        "requested_by",
        "requested_by_name",
        "finished_at",
        "counts",
        "failure",
        "stopped"
      ],
      "additionalProperties": false,
      "description": "The round's current dry run, the newest: running, ready (counts written), failed, stopped (the purge job's recount differed; stopped says how) or purged. A dry run running past ten minutes reads failed. Null when none has been run.",
      "x-data-class": "operational"
    },
    "approvals": {
      "type": "object",
      "properties": {
        "count": {
          "type": "integer",
          "minimum": 0
        },
        "needed": {
          "type": "integer",
          "enum": [
            1,
            2
          ]
        },
        "principal": {
          "type": "boolean"
        },
        "approvers": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "user_id": {
                "type": "string"
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "principal": {
                "type": "boolean"
              },
              "approved_at": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "user_id",
              "name",
              "principal",
              "approved_at"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "count",
        "needed",
        "principal",
        "approvers"
      ],
      "additionalProperties": false,
      "description": "The approvals of the current dry run while it is ready: one principal's is the quorum (needed 1), else two different staff's. Empty otherwise: approvals of a superseded or stopped dry run no longer count.",
      "x-data-class": "operational"
    },
    "checks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "enum": [
              "countdown",
              "dry_run",
              "approvals"
            ]
          },
          "label": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pass",
              "fail",
              "pending"
            ]
          },
          "evidence": {
            "type": "string"
          }
        },
        "required": [
          "key",
          "label",
          "status",
          "evidence"
        ],
        "additionalProperties": false
      },
      "description": "The checklist, in order: Countdown ended, Dry run, Approvals.",
      "x-data-class": "operational"
    },
    "ready": {
      "type": "boolean",
      "description": "Every line passes: the purge job may run.",
      "x-data-class": "operational"
    },
    "blocking": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "What stands in the way, once each, in line order: countdown_running, purge_dry_run_required, purge_dry_run_running or purge_approvals_needed. Empty when ready.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "org_id",
    "state",
    "countdown",
    "dry_run",
    "approvals",
    "checks",
    "ready",
    "blocking"
  ],
  "additionalProperties": false
}

Refusals

  • capability_not_enabled · 422 · the capability's release flag is off for the caller
  • org_not_scheduled · 422 · the org has no deletion scheduled, so there is no purge to be ready for
  • org_has_no_lifecycle · 422 · the org has no lifecycle row: a ported org nothing has typed yet
  • org_has_no_type · 422 · the org has a lifecycle row and no type row; a person repairs it
  • org_is_twin · 422 · a test twin follows its live org
  • org_declared · 422 · the org is declared in db/tradehq/orgs.json and leaves by a reviewed change
  • org_purged · 422 · the org is purged; only its tombstone is left

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF
MobileF
APIF
MCPF
VoiceD4
PushN
OneBoxN
OutboundN
  • Voice: degraded: visualization
  • Push: emits nothing
  • OneBox: no document originates a purge
  • Outbound: crosses to no counterparty

Events

None emitted.

Related

None.