## Retrieve

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

Returns a single taxonomy run by ID, scoped to the tenant. 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

- `Run = object { id, cluster_count, created_at, 16 more }`

  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 \
    -H "Authorization: Bearer $HUB_API_KEY"
```