# Runs

## 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"
```

## Start

**post** `/v1/taxonomy/runs`

Starts a manual taxonomy generation run for a field scope. Hub validates that the field has enough
embedded text feedback (below the configured minimum returns 400 with an "insufficient data"
validation error), creates the run, and hands it to the taxonomy compute service.

Idempotent per scope: if a run is already pending or running for the same scope, the existing run
is returned with `in_progress: true` (HTTP 200) instead of starting a new one; a newly created run
returns HTTP 202 with `in_progress: false`. While a tenant data purge runs for the same tenant_id,
the request is rejected with HTTP 409 (code `tenant_write_conflict`) and may be retried. Requires
Hub embeddings and the taxonomy service to be configured; otherwise returns 503.

### Body Parameters

- `field_id: string`

- `source_type: string`

- `tenant_id: string`

- `actor_id: optional string`

  Optional identifier of the actor starting the run.

- `field_label: optional string`

  Optional human-readable field label.

- `source_id: optional string`

  Optional; empty or omitted is the canonical "no source" bucket.

### Returns

- `in_progress: boolean`

  True when an existing pending/running run for the scope was returned instead of starting a new one.

- `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 \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $HUB_API_KEY" \
    -d '{
          "field_id": "feedback",
          "source_type": "formbricks",
          "tenant_id": "org-123"
        }'
```

## 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"
```

## 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"
```

# Active

## Get Tree

**get** `/v1/taxonomy/runs/active/tree`

Returns the currently active taxonomy run and its tree for a field scope. Exactly one run is
active per scope at a time. Returns 404 when no run has been activated for the scope.

### Query Parameters

- `field_id: string`

  Field ID of the scope.

- `source_type: string`

  Source type of the scope.

- `tenant_id: string`

  Tenant that owns the scope.

- `source_id: optional string`

  Source ID of the scope; empty string is the canonical "no source" bucket.

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