Book a demo

run_purge_dry_run

Run a purge dry run

act entity tenant-private since 2026-10-01

Counts what purging an org whose deletion is scheduled would delete, and deletes nothing: its rows per table, the R2 objects and bytes its attachments hold, its test twin, its data shares and the members it would leave with no org. Answers 202 with the dry run's id while the count runs; get_purge_readiness says when it lands. A new dry run supersedes the last, and approvals of the last no longer count. The purge job counts again before it deletes and stops if anything differs. Trade HQ staff only.

Contract

shape
entity
authority
act
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
keyed
emits
org.purge_dry_run
MCP tool
run_purge_dry_run
decision_set
approve, reject, escalate
REST
POST https://api.containertradehq.com/v1/cap/run_purge_dry_run

Through MCP this call returns an approval request first; see Approvals.

Idempotency: keyed by the caller's Idempotency-Key, which is required: the same key and inputs replay the first result, the same key with other inputs is 409 idempotency_key_reused

Inputs

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

Response

  • dry_run_id · string · The dry run: pd and eighteen characters, derived from the Idempotency-Key.
  • org_id · string · The org.
  • status · string · running when first answered (202); a replay answers where it is now.
  • supersedes · stringnull · The dry run this one replaced as the round's current one, whose approvals no longer count; null for the round's first.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "dry_run_id": {
      "type": "string",
      "description": "The dry run: pd and eighteen characters, derived from the Idempotency-Key.",
      "x-data-class": "operational"
    },
    "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"
    },
    "status": {
      "type": "string",
      "enum": [
        "running",
        "ready",
        "failed",
        "stopped",
        "purged"
      ],
      "description": "running when first answered (202); a replay answers where it is now.",
      "x-data-class": "operational"
    },
    "supersedes": {
      "type": [
        "string",
        "null"
      ],
      "description": "The dry run this one replaced as the round's current one, whose approvals no longer count; null for the round's first.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "dry_run_id",
    "org_id",
    "status",
    "supersedes"
  ],
  "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 count
  • purge_dry_run_running · 409 · a dry run of this org is still counting; wait for it to land
  • purge_dry_run_busy · 429 · as many dry runs as front-door counts at once are counting or waiting; try again in a minute
  • idempotency_key_reused · 409 · this Idempotency-Key already made a dry run of another org, or by someone else
  • retry_key_mismatch · 409 · the Idempotency-Key was already used with different inputs
  • retry_key_in_flight · 409 · a request with this Idempotency-Key is still running
  • retry_key_lost · 409 · another request took over this Idempotency-Key first; no dry run was made
  • 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
MobileD6
APIF
MCPF*
VoiceD6
PushF
OneBoxN
OutboundN
  • Mobile: degraded: authority
  • MCP: approval required
  • Voice: degraded: authority
  • OneBox: no document originates a purge
  • Outbound: crosses to no counterparty

Events

Related

None.