## Get Tree

**get** `/v1/taxonomy/runs/{run_id}/tree`

Returns the run and its taxonomy tree (visible nodes only; soft-removed nodes are excluded). Tenant-scoped; returns 404 if the run does not belong to the tenant.

### Path Parameters

- `run_id: string`

### Query Parameters

- `tenant_id: string`

  Tenant that owns the run.

### Returns

- `root: Node`

  A node in a taxonomy tree. Non-root nodes have a parent; leaf nodes reference the cluster they summarize.

  - `id: string`

  - `created_at: string`

  - `label: string`

  - `level: number`

    Depth in the tree; the root is level 0.

  - `node_type: "root" or "branch" or "leaf"`

    Position of a node within the taxonomy tree.

    - `"root"`

    - `"branch"`

    - `"leaf"`

  - `run_id: string`

  - `sort_order: number`

  - `updated_at: string`

  - `children: optional array of Node`

    Child nodes, present when the tree is returned hierarchically.

  - `cluster_id: optional string`

    Cluster this node summarizes; typically present on leaf nodes.

  - `description: optional string`

  - `metadata: optional map[unknown]`

  - `original_label: optional string`

    Label as originally generated, before any rename.

  - `parent_id: optional string`

    Parent node ID; absent for the root node.

  - `removed_at: optional string`

    Set when the node has been soft-removed.

  - `removed_by: optional string`

    Actor that soft-removed the node.

- `run: Run`

  A persisted taxonomy generation run.

  - `id: string`

  - `cluster_count: number`

  - `created_at: string`

  - `embedding_count: number`

  - `field_id: string`

  - `node_count: number`

  - `record_count: number`

  - `source_id: string`

    Empty string is the canonical "no source" bucket.

  - `source_type: string`

  - `status: "pending" or "running" or "succeeded" or 2 more`

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

    - `"pending"`

    - `"running"`

    - `"succeeded"`

    - `"failed"`

    - `"canceled"`

  - `tenant_id: string`

  - `updated_at: string`

  - `error: optional string`

    Sanitized failure message; present on failed runs.

  - `error_code: optional "insufficient_data" or "service_unavailable" or "generation_failed" or 2 more`

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

    - `"insufficient_data"`

    - `"service_unavailable"`

    - `"generation_failed"`

    - `"invalid_output"`

    - `"internal_error"`

  - `field_label: optional string`

    Human-readable field label; absent when unknown.

  - `finished_at: optional string`

  - `metrics: optional map[unknown]`

    Opaque run metrics recorded by the taxonomy service.

  - `params: optional map[unknown]`

    Opaque run parameters recorded by Hub.

  - `started_at: optional string`

### Example

```http
curl http://localhost:8080/v1/taxonomy/runs/$RUN_ID/tree \
    -H "Authorization: Bearer $HUB_API_KEY"
```