Get the active taxonomy tree for a scope

client.taxonomy.runs.active.getTree(, ?): ActiveGetTreeResponse { root, run }

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.

ParametersExpand Collapse

query: ActiveGetTreeParams { tenant_id, field_id, scope_type, 2 more }

tenant_id: string

Tenant that owns the scope.

minLength1

maxLength255

field_id?: string

Field ID of a field scope. Must be omitted for directory scope.

minLength1

maxLength255

scope_type?: "field" | "directory"

Scope type. Omit for field scope; use directory with tenant_id only for directory taxonomy.

Accepts one of the following:

"field"

"directory"

source_id?: string

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

maxLength255

source_type?: string

Source type of a field scope. Must be omitted for directory scope.

minLength1

maxLength255

ReturnsExpand Collapse

ActiveGetTreeResponse { root, run }

root: Node { id, created_at, label, 13 more } | null

A node in a taxonomy tree. Non-root nodes have a parent; leaf nodes reference the cluster they summarize.

id: string

formatuuid

created_at: string

formatdate-time

label: string

level: number

Depth in the tree; the root is level 0.

formatint64

node_type: "root" | "branch" | "leaf"

Position of a node within the taxonomy tree.

Accepts one of the following:

"root"

"branch"

"leaf"

run_id: string

formatuuid

sort_order: number

formatint64

updated_at: string

formatdate-time

children?: Array<Node { id, created_at, label, 13 more } >

Child nodes, present when the tree is returned hierarchically.

Node { id, created_at, label, 13 more }

A node in a taxonomy tree. Non-root nodes have a parent; leaf nodes reference the cluster they summarize.

id: string

formatuuid

created_at: string

formatdate-time

label: string

level: number

Depth in the tree; the root is level 0.

formatint64

node_type: "root" | "branch" | "leaf"

Position of a node within the taxonomy tree.

Accepts one of the following:

"root"

"branch"

"leaf"

run_id: string

formatuuid

sort_order: number

formatint64

updated_at: string

formatdate-time

children?: Array<Node { id, created_at, label, 13 more } >

Child nodes, present when the tree is returned hierarchically.

Node { id, created_at, label, 13 more }

cluster_id?: string

Cluster this node summarizes; typically present on leaf nodes.

formatuuid

description?: string

metadata?: Record<string, unknown>

original_label?: string

Label as originally generated, before any rename.

parent_id?: string

Parent node ID; absent for the root node.

formatuuid

removed_at?: string

Set when the node has been soft-removed.

formatdate-time

removed_by?: string

Actor that soft-removed the node.

cluster_id?: string

Cluster this node summarizes; typically present on leaf nodes.

formatuuid

description?: string

metadata?: Record<string, unknown>

original_label?: string

Label as originally generated, before any rename.

parent_id?: string

Parent node ID; absent for the root node.

formatuuid

removed_at?: string

Set when the node has been soft-removed.

formatdate-time

removed_by?: string

Actor that soft-removed the node.

run: Run { id, cluster_count, created_at, 17 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

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.

Accepts one of the following:

"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.

Accepts one of the following:

"pending"

"running"

"succeeded"

"failed"

"canceled"

tenant_id: string

updated_at: string

formatdate-time

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.

Accepts one of the following:

"insufficient_data"

"service_unavailable"

"generation_failed"

"invalid_output"

"internal_error"

field_label?: string

Human-readable field label; absent when unknown.

finished_at?: string

formatdate-time

metrics?: Record<string, unknown>

Opaque run metrics recorded by the taxonomy service.

params?: Record<string, unknown>

Opaque run parameters recorded by Hub.

started_at?: string

formatdate-time

Get the active taxonomy tree for a scope

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);

{
  "root": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "created_at": "2019-12-27T18:11:19.117Z",
    "label": "label",
    "level": 0,
    "node_type": "root",
    "run_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "sort_order": 0,
    "updated_at": "2019-12-27T18:11:19.117Z",
    "children": [],
    "cluster_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "description": "description",
    "metadata": {
      "foo": "bar"
    },
    "original_label": "original_label",
    "parent_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "removed_at": "2019-12-27T18:11:19.117Z",
    "removed_by": "removed_by"
  },
  "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,
    "scope_type": "field",
    "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

{
  "root": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "created_at": "2019-12-27T18:11:19.117Z",
    "label": "label",
    "level": 0,
    "node_type": "root",
    "run_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "sort_order": 0,
    "updated_at": "2019-12-27T18:11:19.117Z",
    "children": [],
    "cluster_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "description": "description",
    "metadata": {
      "foo": "bar"
    },
    "original_label": "original_label",
    "parent_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "removed_at": "2019-12-27T18:11:19.117Z",
    "removed_by": "removed_by"
  },
  "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,
    "scope_type": "field",
    "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"
  }
}