Start a taxonomy run

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 ParametersExpand Collapse

field_id: string

minLength1

maxLength255

source_type: string

minLength1

maxLength255

tenant_id: string

minLength1

maxLength255

actor_id: optional string

Optional identifier of the actor starting the run.

minLength1

maxLength255

field_label: optional string

Optional human-readable field label.

source_id: optional string

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

maxLength255

ReturnsExpand Collapse

in_progress: boolean

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

run: Run { id, cluster_count, created_at, 16 more }

A persisted taxonomy generation run.

id: string

formatuuid

cluster_count: number

formatint64

created_at: string

formatdate-time

embedding_count: number

formatint64

field_id: string

node_count: number

formatint64

record_count: number

formatint64

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.

Accepts one of the following:

"pending"

"running"

"succeeded"

"failed"

"canceled"

tenant_id: string

updated_at: string

formatdate-time

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.

Accepts one of the following:

"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

formatdate-time

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

formatdate-time

Start a taxonomy run

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"
        }'

{
  "in_progress": true,
  "run": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "cluster_count": 0,
    "created_at": "2019-12-27T18:11:19.117Z",
    "embedding_count": 0,
    "field_id": "field_id",
    "node_count": 0,
    "record_count": 0,
    "source_id": "source_id",
    "source_type": "source_type",
    "status": "pending",
    "tenant_id": "tenant_id",
    "updated_at": "2019-12-27T18:11:19.117Z",
    "error": "error",
    "error_code": "insufficient_data",
    "field_label": "field_label",
    "finished_at": "2019-12-27T18:11:19.117Z",
    "metrics": {
      "foo": "bar"
    },
    "params": {
      "foo": "bar"
    },
    "started_at": "2019-12-27T18:11:19.117Z"
  }
}

Returns Examples

{
  "in_progress": true,
  "run": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "cluster_count": 0,
    "created_at": "2019-12-27T18:11:19.117Z",
    "embedding_count": 0,
    "field_id": "field_id",
    "node_count": 0,
    "record_count": 0,
    "source_id": "source_id",
    "source_type": "source_type",
    "status": "pending",
    "tenant_id": "tenant_id",
    "updated_at": "2019-12-27T18:11:19.117Z",
    "error": "error",
    "error_code": "insufficient_data",
    "field_label": "field_label",
    "finished_at": "2019-12-27T18:11:19.117Z",
    "metrics": {
      "foo": "bar"
    },
    "params": {
      "foo": "bar"
    },
    "started_at": "2019-12-27T18:11:19.117Z"
  }
}