Skip to main content
GET
JavaScript
Fetch a single tenant. The id accepts the canonical tenant_… form or external_id:<value>, the key your own system knows the customer by. Since assertions create tenants keyed on external_id, the second form is usually the one you have.

Two states

state is STATE_ACTIVE for a living tenant and STATE_ERASING for one mid-erasure. An erasing tenant is on its way out: once the background work finishes, this endpoint returns NotFound. Polling here is how you follow an erasure to completion.

The record reads back your assertions

A tenant has no spec. metadata.name is the most recent name you asserted, metadata.external_id is the key you asserted it under, and metadata.updated_at tells you when the tenant was last asserted. includeInfo=true adds the subjectCount, objectiveCount, and widgetSessionCount counts, at the cost of a query each.

List tenants

The workspace-wide census, with filters.

List a tenant's subjects

Who has acted under this tenant.

Erase a tenant

The destructor, and what STATE_ERASING means.

Use your own IDs

How the external_id: form works across the API.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId
string
required

Workspace ID.

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

id
string
required

Tenant ID. Accepts the canonical tenant_… form or the external_id:<value> form.

Query Parameters

includeInfo
boolean

When true, the info field is populated.

Response

OK

Tenant is the customer's organization as a readable record rather than an echo. It carries no spec: a tenant is never configured, only asserted, so everything about it lives in the metadata envelope — external_id is the key the customer asserted it under, name is the most recent name they asserted, and updated_at is therefore when the tenant was last asserted.

metadata
object
required

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

state
enum<string>
required
read-only

The current lifecycle state of the tenant. Output only.

Available options:
STATE_UNSPECIFIED,
STATE_ACTIVE,
STATE_ERASING
info
object

TenantInfo provides read-only server-derived data about a tenant.