---
title: "Start a taxonomy run"
method: POST
path: "/v1/taxonomy/runs"
tags: ["Taxonomy"]
---

# Start a taxonomy run

`POST /v1/taxonomy/runs`

Starts a manual taxonomy generation run for a field or directory scope. Hub validates that the
scope 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. Omit scope_type for the existing field scope behavior; use scope_type=directory with
tenant_id only to generate one taxonomy over all text feedback in the directory.

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.

## Request body

- CreateTaxonomyRunInputBody — Request to start a manual taxonomy run. Omit scope_type or set it to `field` for the existing field-scoped behavior. Set scope_type to `directory` with only tenant_id to generate one taxonomy over all text feedback in the directory.
  - `scope_type` 'field' | 'directory' — Taxonomy input scope. `field` covers one (source_type, source_id, field_id) field scope. `directory` covers all text feedback records for the tenant/directory and must not include source_type, source_id, or field_id.
  - `tenant_id` string, required
  - `source_type` string — Required for field scope; omit for directory scope.
  - `source_id` string — Optional for field scope; empty or omitted is the canonical "no source" bucket. Omit for directory scope.
  - `field_id` string — Required for field scope; omit for directory scope.
  - `field_label` string — Optional human-readable field label.
  - `actor_id` string — Optional identifier of the actor starting the run.

## Response `200`

A run for this scope is already in progress; the existing run is returned.

- CreateTaxonomyRunOutputBody
  - `run` TaxonomyRunData, required — A persisted taxonomy generation run.
    - `id` string, uuid, required
    - `scope_type` 'field' | 'directory', required — Taxonomy input scope. `field` covers one (source_type, source_id, field_id) field scope. `directory` covers all text feedback records for the tenant/directory and must not include source_type, source_id, or field_id.
    - `tenant_id` string, required
    - `source_type` string, required
    - `source_id` string, required — Empty string is the canonical "no source" bucket.
    - `field_id` string, required
    - `field_label` string — Human-readable field label; absent when unknown.
    - `status` 'pending' | 'running' | 'succeeded' | 'failed' | 'canceled', required — Lifecycle state of a taxonomy run. Allowed transitions are pending -> running|failed|canceled and running -> succeeded|failed|canceled.
    - `params` object — Opaque run parameters recorded by Hub.
    - `metrics` object — Opaque run metrics recorded by the taxonomy service.
    - `record_count` integer, required
    - `embedding_count` integer, required
    - `cluster_count` integer, required
    - `node_count` integer, required
    - `error` string — Sanitized failure message; present on failed runs.
    - `error_code` 'insufficient_data' | 'service_unavailable' | 'generation_failed' | 'invalid_output' | 'internal_error' — Machine-readable reason a taxonomy run failed or a prerequisite was not met.
    - `started_at` string, date-time
    - `finished_at` string, date-time
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `in_progress` boolean, required — True when an existing pending/running run for the scope was returned instead of starting a new one.

## Other responses

- `202` — Run accepted and started
- `400` — Bad Request – invalid scope, or insufficient input (no text feedback for the scope, or fewer embedded records than the configured minimum).
- `401` — Unauthorized (missing or invalid API key)
- `409` — Conflict – a tenant data purge for the same tenant_id is in progress (code `tenant_write_conflict`). No run was created; retry later.
- `503` — Service Unavailable – Hub embeddings or the taxonomy compute service are not configured or did not accept the run (code `service_unavailable`). Retry later.
- `default` — Error

---

[API](https://skmtc.net/formbricks/apis/formbricks-hub-api.md) · [All operations](https://skmtc.net/formbricks/apis/formbricks-hub-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/formbricks/formbricks-hub-api/revisions/8d06d9728138/schema)