# Runs ## List `client.taxonomy.runs.list(RunListParamsquery, RequestOptionsoptions?): RunListResponse` **get** `/v1/taxonomy/runs` Returns taxonomy run history for a tenant, most recent first. Optionally filter by scope_type, 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. ### Parameters - `query: RunListParams` - `tenant_id: string` Tenant whose runs should be listed. - `field_id?: string` Optional field_id filter. - `limit?: number` Maximum number of runs to return. - `scope_type?: "field" | "directory"` Optional scope type filter. Omitted means no scope type filter. - `"field"` - `"directory"` - `source_id?: 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?: string` Optional source_type filter. ### Returns - `RunListResponse` - `data: Array` - `id: string` - `cluster_count: number` - `created_at: string` - `embedding_count: number` - `field_id: string` - `node_count: number` - `record_count: number` - `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. - `"field"` - `"directory"` - `source_id: string` Empty string is the canonical "no source" bucket. - `source_type: string` - `status: "pending" | "running" | "succeeded" | 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?: string` Sanitized failure message; present on failed runs. - `error_code?: "insufficient_data" | "service_unavailable" | "generation_failed" | 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?: string` Human-readable field label; absent when unknown. - `finished_at?: string` - `metrics?: Record` Opaque run metrics recorded by the taxonomy service. - `params?: Record` Opaque run parameters recorded by Hub. - `started_at?: string` ### Example ```typescript import FormbricksHub from '@formbricks/hub'; const client = new FormbricksHub({ apiKey: process.env['HUB_API_KEY'], // This is the default and can be omitted }); const runs = await client.taxonomy.runs.list({ tenant_id: 'org-123' }); console.log(runs.data); ``` ## Start `client.taxonomy.runs.start(RunStartParamsbody, RequestOptionsoptions?): RunStartResponse` **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. ### Parameters - `body: RunStartParams` - `tenant_id: string` - `actor_id?: string` Optional identifier of the actor starting the run. - `field_id?: string` Required for field scope; omit for directory scope. - `field_label?: string` Optional human-readable field label. - `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. - `"field"` - `"directory"` - `source_id?: string` Optional for field scope; empty or omitted is the canonical "no source" bucket. Omit for directory scope. - `source_type?: string` Required for field scope; omit for directory scope. ### Returns - `RunStartResponse` - `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` - `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. - `"field"` - `"directory"` - `source_id: string` Empty string is the canonical "no source" bucket. - `source_type: string` - `status: "pending" | "running" | "succeeded" | 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?: string` Sanitized failure message; present on failed runs. - `error_code?: "insufficient_data" | "service_unavailable" | "generation_failed" | 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?: string` Human-readable field label; absent when unknown. - `finished_at?: string` - `metrics?: Record` Opaque run metrics recorded by the taxonomy service. - `params?: Record` Opaque run parameters recorded by Hub. - `started_at?: string` ### Example ```typescript import FormbricksHub from '@formbricks/hub'; const client = new FormbricksHub({ apiKey: process.env['HUB_API_KEY'], // This is the default and can be omitted }); const response = await client.taxonomy.runs.start({ tenant_id: 'org-123', actor_id: 'user-42', field_id: 'feedback', scope_type: 'field', source_id: 'survey-abc', source_type: 'formbricks', }); console.log(response.in_progress); ``` ## Retrieve `client.taxonomy.runs.retrieve(stringrunID, RunRetrieveParamsquery, RequestOptionsoptions?): Run` **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. ### Parameters - `runID: string` - `query: RunRetrieveParams` - `tenant_id: string` Tenant that owns the run. ### Returns - `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` - `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. - `"field"` - `"directory"` - `source_id: string` Empty string is the canonical "no source" bucket. - `source_type: string` - `status: "pending" | "running" | "succeeded" | 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?: string` Sanitized failure message; present on failed runs. - `error_code?: "insufficient_data" | "service_unavailable" | "generation_failed" | 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?: string` Human-readable field label; absent when unknown. - `finished_at?: string` - `metrics?: Record` Opaque run metrics recorded by the taxonomy service. - `params?: Record` Opaque run parameters recorded by Hub. - `started_at?: string` ### Example ```typescript import FormbricksHub from '@formbricks/hub'; const client = new FormbricksHub({ apiKey: process.env['HUB_API_KEY'], // This is the default and can be omitted }); const run = await client.taxonomy.runs.retrieve('019f177f-9aa3-705e-8195-cea2aa187268', { tenant_id: 'org-123', }); console.log(run.id); ``` ## Get Tree `client.taxonomy.runs.getTree(stringrunID, RunGetTreeParamsquery, RequestOptionsoptions?): RunGetTreeResponse` **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. ### Parameters - `runID: string` - `query: RunGetTreeParams` - `tenant_id: string` Tenant that owns the run. ### Returns - `RunGetTreeResponse` - `root: Node | null` 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" | "branch" | "leaf"` Position of a node within the taxonomy tree. - `"root"` - `"branch"` - `"leaf"` - `run_id: string` - `sort_order: number` - `updated_at: string` - `children?: Array` Child nodes, present when the tree is returned hierarchically. - `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" | "branch" | "leaf"` Position of a node within the taxonomy tree. - `"root"` - `"branch"` - `"leaf"` - `run_id: string` - `sort_order: number` - `updated_at: string` - `children?: Array` Child nodes, present when the tree is returned hierarchically. - `cluster_id?: string` Cluster this node summarizes; typically present on leaf nodes. - `description?: string` - `metadata?: Record` - `original_label?: string` Label as originally generated, before any rename. - `parent_id?: string` Parent node ID; absent for the root node. - `removed_at?: string` Set when the node has been soft-removed. - `removed_by?: string` Actor that soft-removed the node. - `cluster_id?: string` Cluster this node summarizes; typically present on leaf nodes. - `description?: string` - `metadata?: Record` - `original_label?: string` Label as originally generated, before any rename. - `parent_id?: string` Parent node ID; absent for the root node. - `removed_at?: string` Set when the node has been soft-removed. - `removed_by?: 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` - `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. - `"field"` - `"directory"` - `source_id: string` Empty string is the canonical "no source" bucket. - `source_type: string` - `status: "pending" | "running" | "succeeded" | 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?: string` Sanitized failure message; present on failed runs. - `error_code?: "insufficient_data" | "service_unavailable" | "generation_failed" | 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?: string` Human-readable field label; absent when unknown. - `finished_at?: string` - `metrics?: Record` Opaque run metrics recorded by the taxonomy service. - `params?: Record` Opaque run parameters recorded by Hub. - `started_at?: string` ### Example ```typescript import FormbricksHub from '@formbricks/hub'; const client = new FormbricksHub({ apiKey: process.env['HUB_API_KEY'], // This is the default and can be omitted }); const response = await client.taxonomy.runs.getTree('019f177f-9aa3-705e-8195-cea2aa187268', { tenant_id: 'org-123', }); console.log(response.root); ``` ## Retrieve Record Counts `client.taxonomy.runs.retrieveRecordCounts(stringrunID, RunRetrieveRecordCountsParamsquery, RequestOptionsoptions?): RunRetrieveRecordCountsResponse` **get** `/v1/taxonomy/runs/{run_id}/record-counts` Returns the feedback-record count for every visible node in a taxonomy run. Each count is a subtree total, so a topic (branch) reports the sum of its subtopics and the root reports the run total. Tenant-scoped; returns 404 if the run does not belong to the tenant. ### Parameters - `runID: string` - `query: RunRetrieveRecordCountsParams` - `tenant_id: string` Tenant that owns the run. ### Returns - `RunRetrieveRecordCountsResponse` - `counts: Array` Per-node feedback-record counts, one entry per visible node. - `node_id: string` Taxonomy node ID. - `record_count: number` Number of feedback records in the node's subtree. ### Example ```typescript import FormbricksHub from '@formbricks/hub'; const client = new FormbricksHub({ apiKey: process.env['HUB_API_KEY'], // This is the default and can be omitted }); const response = await client.taxonomy.runs.retrieveRecordCounts( '019f177f-9aa3-705e-8195-cea2aa187268', { tenant_id: 'org-123' }, ); console.log(response.counts); ``` # Active ## Get Tree `client.taxonomy.runs.active.getTree(ActiveGetTreeParamsquery, RequestOptionsoptions?): ActiveGetTreeResponse` **get** `/v1/taxonomy/runs/active/tree` Returns the currently active taxonomy run and its tree for a field or directory scope. Exactly one run is active per scope at a time. Returns 404 when no run has been activated for the scope. ### Parameters - `query: ActiveGetTreeParams` - `tenant_id: string` Tenant that owns the scope. - `field_id?: string` Field ID of a field scope. Must be omitted for directory scope. - `scope_type?: "field" | "directory"` Scope type. Omit for field scope; use directory with tenant_id only for directory taxonomy. - `"field"` - `"directory"` - `source_id?: string` Source ID of the scope; empty string is the canonical "no source" bucket. - `source_type?: string` Source type of a field scope. Must be omitted for directory scope. ### Returns - `ActiveGetTreeResponse` - `root: Node | null` 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" | "branch" | "leaf"` Position of a node within the taxonomy tree. - `"root"` - `"branch"` - `"leaf"` - `run_id: string` - `sort_order: number` - `updated_at: string` - `children?: Array` Child nodes, present when the tree is returned hierarchically. - `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" | "branch" | "leaf"` Position of a node within the taxonomy tree. - `"root"` - `"branch"` - `"leaf"` - `run_id: string` - `sort_order: number` - `updated_at: string` - `children?: Array` Child nodes, present when the tree is returned hierarchically. - `cluster_id?: string` Cluster this node summarizes; typically present on leaf nodes. - `description?: string` - `metadata?: Record` - `original_label?: string` Label as originally generated, before any rename. - `parent_id?: string` Parent node ID; absent for the root node. - `removed_at?: string` Set when the node has been soft-removed. - `removed_by?: string` Actor that soft-removed the node. - `cluster_id?: string` Cluster this node summarizes; typically present on leaf nodes. - `description?: string` - `metadata?: Record` - `original_label?: string` Label as originally generated, before any rename. - `parent_id?: string` Parent node ID; absent for the root node. - `removed_at?: string` Set when the node has been soft-removed. - `removed_by?: 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` - `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. - `"field"` - `"directory"` - `source_id: string` Empty string is the canonical "no source" bucket. - `source_type: string` - `status: "pending" | "running" | "succeeded" | 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?: string` Sanitized failure message; present on failed runs. - `error_code?: "insufficient_data" | "service_unavailable" | "generation_failed" | 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?: string` Human-readable field label; absent when unknown. - `finished_at?: string` - `metrics?: Record` Opaque run metrics recorded by the taxonomy service. - `params?: Record` Opaque run parameters recorded by Hub. - `started_at?: string` ### Example ```typescript import FormbricksHub from '@formbricks/hub'; const client = new FormbricksHub({ apiKey: process.env['HUB_API_KEY'], // This is the default and can be omitted }); const response = await client.taxonomy.runs.active.getTree({ tenant_id: 'org-123' }); console.log(response.root); ```