List feedback records for a taxonomy node

GET

/v1/taxonomy/nodes/{node_id}/records

const url = 'http://localhost:8080/v1/taxonomy/nodes/019f177f-9abe-78cd-8008-f40b58e3147d/records?tenant_id=org-123';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'http://localhost:8080/v1/taxonomy/nodes/019f177f-9abe-78cd-8008-f40b58e3147d/records?tenant_id=org-123' \
  --header 'Authorization: Bearer <token>'

Returns the feedback records assigned to a node and all of its (visible) descendant nodes, via the clusters those nodes reference. Tenant-scoped; returns 404 if the node does not belong to the tenant or has been removed. An empty data therefore means the node genuinely holds no records. The limit in the response reflects the applied cap.

Authorizations

ApiKeyAuth

Parameters

Path Parameters

node_id

required

string format: uuid

Example

019f177f-9abe-78cd-8008-f40b58e3147d

Taxonomy node ID.

Query Parameters

tenant_id

required

string

>= 1 characters <= 255 characters /^[^\x00]*$/

Example

org-123

Tenant that owns the node.

limit

integer format: int64

>= 1 <= 100

Maximum number of feedback records to return.

Responses

200

Feedback records assigned to the node subtree

application/json

object

data

required

Array<object>

object

collected_at

required

When the feedback was collected

string format: date-time

created_at

required

When this record was created

string format: date-time

field_id

required

Identifier for the question/field

string

field_label

The actual question text

string

field_group_id

Stable identifier grouping related fields (for ranking, matrix, grid questions)

string

field_group_label

Human-readable question text for the group

string

field_type

required

Type of field

string

Allowed values: text categorical nps csat ces rating number boolean date

required

UUIDv7 primary key

string format: uuid

language

ISO language code. NULL bytes not allowed.

string

/^[^\x00]*$/

metadata

Arbitrary context stored with this record, returned with equivalent values (key order is normalized, and so are number exponents — 1e2 reads back as 100). Omitted when the record has no metadata; a record explicitly stored with a JSON null returns null. An object is the supported shape and the only one the request schemas accept. The wider union is for reading: the column stores whatever JSON was written, so a record created before that convention can return an array or a scalar, and an object-only response schema would make a generated client reject it.

sentiment

Sentiment polarity inferred from value_text (sentiment enrichment). Read-only; absent until the record is enriched.

string

Allowed values: very_negative negative neutral positive very_positive mixed

sentiment_score

Signed sentiment polarity from -1.0 (very negative) to 1.0 (very positive) (sentiment enrichment). Read-only; absent until the record is enriched.

number format: double

>= -1 <= 1

taxonomy

Any of:

object
null

object

status

required

string

Allowed values: classified unclassified no_active_taxonomy

run_id

required

One of:

string
null

string format: uuid

path

required

Current visible non-root nodes in root-to-leaf order; empty unless classified.

Array<object>

object

required

string format: uuid

label

required

string

level

required

integer format: int64

node_type

required

string

Allowed values: branch leaf

emotions

Emotions inferred from value_text (emotion enrichment); multi-label from a fixed set. Read-only; absent until the record is enriched, and never an empty array.

Array<string>

>= 1 items

Allowed values: joy anger sadness fear surprise disgust

source_id

Reference to survey/form/ticket ID

string

source_name

Human-readable name

string

source_type

required

Type of feedback source

string

submission_id

required

Identifier for the logical submission this record belongs to (required).

string

/^[^\x00]*$/

tenant_id

required

Tenant/organization identifier. NULL bytes not allowed.

string

/^[^\x00]*$/

translation_lang_key

BCP-47 target locale that value_text_translated was produced in (language enrichment). Read-only; absent until the record is enriched.

string

<= 35 characters

updated_at

required

When this record was last updated

string format: date-time

user_id

User ID (e.g., anonymous ID or email hash)

string

value_boolean

Boolean response

boolean

value_date

Date response

string format: date-time

value_number

Numeric response

number format: double

value_text

Text response. NULL bytes not allowed.

string

/^[^\x00]*$/

value_id

Stable id of the selected option in the source system (e.g. a survey choice id), stored alongside value_text for durable option identity. Opaque to Hub. Absent for free-text/non-choice answers. NULL bytes not allowed.

string

/^[^\x00]*$/

value_text_translated

Value_text translated into the tenant’s configured target language (language enrichment). Read-only; absent until the record is enriched.

string

/^[^\x00]*$/

limit

required

The applied maximum number of records.

integer format: int64

Example

{
  "data": [
    {
      "field_type": "text",
      "sentiment": "very_negative",
      "taxonomy": {
        "status": "classified",
        "path": [
          {
            "node_type": "branch"
          }
        ]
      },
      "emotions": [
        "joy"
      ]
    }
  ]
}

400

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

application/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

Unauthorized (missing or invalid API key)

application/problem+json

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

object

code

required

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

404

Not Found – no node with this ID for the tenant.

application/problem+json

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

object

code

required

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

Error

application/problem+json

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

object

code

required

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