List taxonomy runs

client.taxonomy.runs.list(, ?): RunListResponse { data }

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.

ParametersExpand Collapse

query: RunListParams { tenant_id, field_id, limit, 3 more }

tenant_id: string

Tenant whose runs should be listed.

minLength1

maxLength255

field_id?: string

Optional field_id filter.

maxLength255

limit?: number

Maximum number of runs to return.

formatint64

minimum1

maximum100

scope_type?: "field" | "directory"

Optional scope type filter. Omitted means no scope type filter.

Accepts one of the following:

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

maxLength255

source_type?: string

Optional source_type filter.

maxLength255

ReturnsExpand Collapse

RunListResponse { data }

data: Array<Run { id, cluster_count, created_at, 17 more } >

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

List taxonomy runs

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

{
  "data": [
    {
      "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

{
  "data": [
    {
      "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"
    }
  ]
}