Skip to content
Formbricks HubFormbricks HubFormbricks Hub

List taxonomy runs

GET
/v1/taxonomy/runs
curl --request GET \
  --url 'http://localhost:8080/v1/taxonomy/runs?tenant_id=org-123&scope_type=field' \
  --header 'Authorization: Bearer <token>'

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.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
tenant_id
required
string
>= 1 characters <= 255 characters /^[^\x00]*$/

Example 

org-123

Tenant whose runs should be listed.

scope_type

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.

string
Allowed values: field directory

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

source_type
string
<= 255 characters /^[^\x00]*$/

Optional source_type filter.

source_id
string
<= 255 characters /^[^\x00]*$/

Optional source_id filter. Omit for no filter; empty string scopes to the “no source” bucket; a concrete value matches that source.

field_id
string
<= 255 characters /^[^\x00]*$/

Optional field_id filter.

limit
integer format: int64
>= 1 <= 100

Maximum number of runs to return.

Responses

Section titled “Responses”

200

Section titled “200”

Taxonomy run history

Media typeapplication/json
object
data
required
Array<object>

A persisted taxonomy generation run.

object
id
required
string format: uuid
scope_type
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.

string
Allowed values: field directory
tenant_id
required
string
source_type
required
string
source_id
required

Empty string is the canonical “no source” bucket.

string
field_id
required
string
field_label

Human-readable field label; absent when unknown.

string
status
required

Lifecycle state of a taxonomy run. Allowed transitions are pending -> running|failed|canceled and running -> succeeded|failed|canceled.

string
Allowed values: pending running succeeded failed canceled
params

Opaque run parameters recorded by Hub.

object
key
additional properties
any
metrics

Opaque run metrics recorded by the taxonomy service.

object
key
additional properties
any
record_count
required
integer format: int64
embedding_count
required
integer format: int64
cluster_count
required
integer format: int64
node_count
required
integer format: int64
error

Sanitized failure message; present on failed runs.

string
error_code

Machine-readable reason a taxonomy run failed or a prerequisite was not met.

string
Allowed values: insufficient_data service_unavailable generation_failed invalid_output internal_error
started_at
string format: date-time
finished_at
string format: date-time
created_at
required
string format: date-time
updated_at
required
string format: date-time

Example 

{
  "data": [
    {
      "scope_type": "field",
      "status": "pending",
      "error_code": "insufficient_data"
    }
  ]
}

400

Section titled “400”

Bad Request (e.g. missing/invalid tenant_id or query parameters)

Media typeapplication/problem+json

RFC 9457 problem details (application/problem+json). Branch on the stable code member rather than on title or type.

object
code
required

Stable, machine-readable error code; the primary value to branch on. service_unavailable indicates a feature or dependency is temporarily unavailable and the request may be retried later. tenant_write_conflict indicates the write conflicted with an in-progress tenant data purge (or vice versa) and may be retried later unchanged. All other codes are terminal until the request itself is changed.

string
Allowed values: validation bad_request unauthorized forbidden not_found conflict tenant_write_conflict method_not_allowed content_too_large service_unavailable internal_server_error
detail

A human-readable explanation specific to this occurrence of the problem.

string
details

Optional structured context for this problem, e.g. resource_type on a 404.

object
key
additional properties
any
instance

A URI reference (typically the request path) identifying the specific occurrence of the problem.

string
invalid_params

Field-level validation failures (RFC 9457 “invalid_params” extension). Present on validation errors.

Array<object>
<= 100 items

A single invalid request parameter (RFC 9457 “invalid_params” extension member).

object
name
required

Dotted path to the offending request field, e.g. ‘field_type’ or ‘items[0].field_type’.

string
reason
required

Human- and agent-readable explanation of why the value is invalid, naming allowed values or constraints where applicable so the request can be corrected without guessing.

string
request_id
required

Identifier for this request, also returned in the X-Request-ID response header; include it when reporting a problem.

string
status
required

HTTP status code

integer format: int64
title
required

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string
type

A URI reference identifying the problem type.

string format: uri

Example 

{
  "code": "validation",
  "detail": "One or more request parameters are invalid",
  "instance": "/v1/feedback-records",
  "invalid_params": [
    {
      "name": "field_type",
      "reason": "must be one of: text, categorical, nps, csat, ces, rating, number, boolean, date"
    }
  ],
  "request_id": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "status": 400,
  "title": "Bad Request",
  "type": "https://hub.formbricks.com/problems/bad-request"
}

401

Section titled “401”

Unauthorized (missing or invalid API key)

Media typeapplication/problem+json

RFC 9457 problem details (application/problem+json). Branch on the stable code member rather than on title or type.

object
code
required

Stable, machine-readable error code; the primary value to branch on. service_unavailable indicates a feature or dependency is temporarily unavailable and the request may be retried later. tenant_write_conflict indicates the write conflicted with an in-progress tenant data purge (or vice versa) and may be retried later unchanged. All other codes are terminal until the request itself is changed.

string
Allowed values: validation bad_request unauthorized forbidden not_found conflict tenant_write_conflict method_not_allowed content_too_large service_unavailable internal_server_error
detail

A human-readable explanation specific to this occurrence of the problem.

string
details

Optional structured context for this problem, e.g. resource_type on a 404.

object
key
additional properties
any
instance

A URI reference (typically the request path) identifying the specific occurrence of the problem.

string
invalid_params

Field-level validation failures (RFC 9457 “invalid_params” extension). Present on validation errors.

Array<object>
<= 100 items

A single invalid request parameter (RFC 9457 “invalid_params” extension member).

object
name
required

Dotted path to the offending request field, e.g. ‘field_type’ or ‘items[0].field_type’.

string
reason
required

Human- and agent-readable explanation of why the value is invalid, naming allowed values or constraints where applicable so the request can be corrected without guessing.

string
request_id
required

Identifier for this request, also returned in the X-Request-ID response header; include it when reporting a problem.

string
status
required

HTTP status code

integer format: int64
title
required

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string
type

A URI reference identifying the problem type.

string format: uri

Example 

{
  "code": "validation",
  "detail": "One or more request parameters are invalid",
  "instance": "/v1/feedback-records",
  "invalid_params": [
    {
      "name": "field_type",
      "reason": "must be one of: text, categorical, nps, csat, ces, rating, number, boolean, date"
    }
  ],
  "request_id": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "status": 400,
  "title": "Bad Request",
  "type": "https://hub.formbricks.com/problems/bad-request"
}

default

Section titled “default”

Error

Media typeapplication/problem+json

RFC 9457 problem details (application/problem+json). Branch on the stable code member rather than on title or type.

object
code
required

Stable, machine-readable error code; the primary value to branch on. service_unavailable indicates a feature or dependency is temporarily unavailable and the request may be retried later. tenant_write_conflict indicates the write conflicted with an in-progress tenant data purge (or vice versa) and may be retried later unchanged. All other codes are terminal until the request itself is changed.

string
Allowed values: validation bad_request unauthorized forbidden not_found conflict tenant_write_conflict method_not_allowed content_too_large service_unavailable internal_server_error
detail

A human-readable explanation specific to this occurrence of the problem.

string
details

Optional structured context for this problem, e.g. resource_type on a 404.

object
key
additional properties
any
instance

A URI reference (typically the request path) identifying the specific occurrence of the problem.

string
invalid_params

Field-level validation failures (RFC 9457 “invalid_params” extension). Present on validation errors.

Array<object>
<= 100 items

A single invalid request parameter (RFC 9457 “invalid_params” extension member).

object
name
required

Dotted path to the offending request field, e.g. ‘field_type’ or ‘items[0].field_type’.

string
reason
required

Human- and agent-readable explanation of why the value is invalid, naming allowed values or constraints where applicable so the request can be corrected without guessing.

string
request_id
required

Identifier for this request, also returned in the X-Request-ID response header; include it when reporting a problem.

string
status
required

HTTP status code

integer format: int64
title
required

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string
type

A URI reference identifying the problem type.

string format: uri

Example 

{
  "code": "validation",
  "detail": "One or more request parameters are invalid",
  "instance": "/v1/feedback-records",
  "invalid_params": [
    {
      "name": "field_type",
      "reason": "must be one of: text, categorical, nps, csat, ces, rating, number, boolean, date"
    }
  ],
  "request_id": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "status": 400,
  "title": "Bad Request",
  "type": "https://hub.formbricks.com/problems/bad-request"
}