## List

**get** `/v1/taxonomy/runs`

Returns taxonomy run history for a tenant, most recent first. Optionally filter by source_type,
field_id, and source_id. source_id is a tri-state filter: omit it for no source filter, pass an
empty string to scope to the canonical "no source" bucket, or pass a concrete value to match that
source.

### Query Parameters

- `tenant_id: string`

  Tenant whose runs should be listed.

- `field_id: optional string`

  Optional field_id filter.

- `limit: optional number`

  Maximum number of runs to return.

- `source_id: optional string`

  Optional source_id filter. Omit for no filter; empty string scopes to the "no source"
  bucket; a concrete value matches that source.

- `source_type: optional string`

  Optional source_type filter.

### Returns

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