get_tenant_health · Get tenant health · Container Trade HQ API

Contract

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

Idempotency: a read: calling again changes nothing

Inputs

name	type	required	validation
org_id	org_id	required	tradehq-org-id; 1 to 20 characters The org to read.

Response

org_id · string · The org.
name · string · The org's name.
org_type · stringnull · The org's type (TRA-234); null for a ported org nothing has typed yet.
account_id · stringnull · The account the org belongs to (a twin reads its live org's); null when it has none.
window_days · integer · The window every 30-day figure covers.
last_login_at · stringnull · The newest sign-in by any member of the org; null when none has signed in.
member_count · integer · The org's members.
active_users_30d · integer · Members with a session seen in the window.
ingest_documents_30d · integer · Documents the org ingested in the window, failed ones included.
ingest_failed_30d · integer · Of those, the documents whose ingest failed.
error_rate · numbernull · ingest_failed_30d over ingest_documents_30d, from 0 to 1; null when nothing was ingested.
plan_tier · stringnull · The org's plan tier; null until TRA-238 sets one.
entitlements_defined · boolean · Whether tier-to-capability data exists to measure use against. False until TRA-238.
open_exceptions · integernull · Exceptions for the org that are open, waiting or escalated; null until TRA-294's store exists.

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"
    },
    "name": {
      "type": "string",
      "description": "The org's name.",
      "x-data-class": "operational"
    },
    "org_type": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "internal",
        "demo",
        "customer",
        "synthetic",
        "system",
        null
      ],
      "description": "The org's type (TRA-234); null for a ported org nothing has typed yet.",
      "x-data-class": "operational"
    },
    "account_id": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "format": "tradehq-account-id",
      "description": "The account the org belongs to (a twin reads its live org's); null when it has none.",
      "x-data-class": "operational"
    },
    "window_days": {
      "type": "integer",
      "description": "The window every 30-day figure covers.",
      "x-data-class": "operational"
    },
    "last_login_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "The newest sign-in by any member of the org; null when none has signed in.",
      "x-data-class": "operational"
    },
    "member_count": {
      "type": "integer",
      "description": "The org's members.",
      "x-data-class": "operational"
    },
    "active_users_30d": {
      "type": "integer",
      "description": "Members with a session seen in the window.",
      "x-data-class": "operational"
    },
    "ingest_documents_30d": {
      "type": "integer",
      "description": "Documents the org ingested in the window, failed ones included.",
      "x-data-class": "operational"
    },
    "ingest_failed_30d": {
      "type": "integer",
      "description": "Of those, the documents whose ingest failed.",
      "x-data-class": "operational"
    },
    "error_rate": {
      "type": [
        "number",
        "null"
      ],
      "description": "ingest_failed_30d over ingest_documents_30d, from 0 to 1; null when nothing was ingested.",
      "x-data-class": "operational"
    },
    "plan_tier": {
      "type": [
        "string",
        "null"
      ],
      "description": "The org's plan tier; null until TRA-238 sets one.",
      "x-data-class": "operational"
    },
    "entitlements_defined": {
      "type": "boolean",
      "description": "Whether tier-to-capability data exists to measure use against. False until TRA-238.",
      "x-data-class": "operational"
    },
    "open_exceptions": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Exceptions for the org that are open, waiting or escalated; null until TRA-294's store exists.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "org_id",
    "name",
    "org_type",
    "account_id",
    "window_days",
    "last_login_at",
    "member_count",
    "active_users_30d",
    "ingest_documents_30d",
    "ingest_failed_30d",
    "error_rate",
    "plan_tier",
    "entitlements_defined",
    "open_exceptions"
  ],
  "additionalProperties": false
}

Refusals

not yet declared

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

Surfaces

DesktopF

MobileF

APIF

MCPF

VoiceF

PushN

OneBoxN

OutboundN

Push: emits nothing
OneBox: no document originates a health reading
Outbound: staff only; crosses to no counterparty

Events

None emitted.

None.