v28

latestOpenAPI 3.1.0Apache-2.0raw.githubusercontent.com2026-07-082940159.9 KB

Taxonomy

Get a taxonomy run

Returns a single taxonomy run by ID, scoped to the tenant. Returns 404 if the run does not belong to the tenant.

get/v1/taxonomy/runs/{run_id}

Path parameters

run_idstring uuid required

Example:019f177f-9aa3-705e-8195-cea2aa187268

Taxonomy run ID.

Query parameters

tenant_idstring required

Example:org-123

Tenant that owns the run.

Response

The taxonomy run

idstring uuid required

scope_type'field' | 'directory' required

Taxonomy input scope. field covers one (source_type, source_id, field_id) field scope. directory covers all text feedback records for the tenant/directory and must not include source_type, source_id, or field_id.

tenant_idstring required

source_typestring required

source_idstring required

Empty string is the canonical "no source" bucket.

field_idstring required

field_labelstring

Human-readable field label; absent when unknown.

status'pending' | 'running' | 'succeeded' | 'failed' | 'canceled' required

Lifecycle state of a taxonomy run. Allowed transitions are pending -> running|failed|canceled and running -> succeeded|failed|canceled.

paramsobject

Opaque run parameters recorded by Hub.

metricsobject

Opaque run metrics recorded by the taxonomy service.

record_countinteger required

embedding_countinteger required

cluster_countinteger required

node_countinteger required

errorstring

Sanitized failure message; present on failed runs.

error_code'insufficient_data' | 'service_unavailable' | 'generation_failed' | 'invalid_output' | 'internal_error'

Machine-readable reason a taxonomy run failed or a prerequisite was not met.

started_atstring date-time

finished_atstring date-time

created_atstring date-time required

updated_atstring date-time required