---
title: "Semantic search over feedback records"
method: POST
path: "/v1/feedback-records/search/semantic"
tags: ["Feedback Records"]
---

# Semantic search over feedback records

`POST /v1/feedback-records/search/semantic`

Embeds the search query and returns feedback record IDs with similarity scores (cosine, 0..1).
**Only available when embeddings are configured** (EMBEDDING_PROVIDER and EMBEDDING_MODEL set).
Supported providers: openai, google (Gemini Developer API / Google AI Studio), google-gemini (Gemini Enterprise Agent Platform API).
When embeddings are disabled, this endpoint returns 503 Service Unavailable.
Request body must include query and tenant_id (required for tenant isolation).

## Query parameters

- `limit` integer
- `cursor` string
- `min_score` number, float

## Request body

- SemanticSearchInputBody
  - `query` string, required — Search query text (embedded and compared via cosine similarity)
  - `tenant_id` string, required — Tenant ID (required for isolation; must match feedback record tenant_id)

## Response `200`

OK

- SemanticSearchResponse
  - `data` SemanticSearchResultItem[], required — List of feedback record IDs with similarity scores (0 = unrelated, 1 = identical). Consistent with list endpoints.
    - `feedback_record_id` string, uuid, required — Feedback record UUID
    - `score` number, double, required — Similarity score (0..1)
    - `field_label` string, required — Label of the feedback field (included in embedding for context). May be empty if the source record had no label.
    - `value_text` string, required — value_text of the feedback record (the text that was embedded). May be empty if the source had no text; embeddings are only created for records with non-empty value_text, but the field can be cleared after embedding creation.
  - `limit` integer, required — Limit used in query (echoed for consistency with list endpoints)
  - `next_cursor` string — Opaque cursor for the next page (keyset paging). Present only when there may be more results (full page returned). Omit when no next page. Use this exact value as the cursor query param for the next page.

## Other responses

- `400` — Bad Request (e.g. missing tenant_id, empty query, or invalid cursor)
- `503` — Service Unavailable (embeddings are not configured)
- `default` — Error

## Changes

- **2026-06-26** `17c77a1a3031` — 3 warning
  - added the new `content_too_large` enum value to the `code` response property for the response status `400`
  - added the new `content_too_large` enum value to the `code` response property for the response status `503`
  - added the new `content_too_large` enum value to the `code` response property for the response status `default`
- **2026-06-16** `d2fa5d9f2e98` — 3 warning
  - added the new `tenant_write_conflict` enum value to the `code` response property for the response status `400`
  - added the new `tenant_write_conflict` enum value to the `code` response property for the response status `503`
  - added the new `tenant_write_conflict` enum value to the `code` response property for the response status `default`
- **2026-06-03** `6907a0a9de00` — 3 breaking, 3 warning, 18 info
  - the `instance` response's property type/format changed from `string`/`uri` to `string`/`` for status `400`
  - the `instance` response's property type/format changed from `string`/`uri` to `string`/`` for status `503`
  - the `instance` response's property type/format changed from `string`/`uri` to `string`/`` for status `default`
  - removed the optional property `errors` from the response with the `400` status
  - …20 more
- …earlier changes not shown

[Full history](https://skmtc.dev/formbricks/apis/formbricks-hub-api/changes/v1/feedback-records/search/semantic/post.md)

---

[API](https://skmtc.dev/formbricks/apis/formbricks-hub-api.md) · [All operations](https://skmtc.dev/formbricks/apis/formbricks-hub-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/formbricks/formbricks-hub-api/revisions/84bba639c72b/schema)