---
title: "Insight Search Ids"
method: GET
path: "/v2/ontology/insight-search-ids"
tags: ["Ontology"]
---

# Insight Search Ids

`GET /v2/ontology/insight-search-ids`

## Request

- Base URL: `https://api.carbonarc.co` (the document declares no server; this is the origin it was published from)
- URL: `https://api.carbonarc.co/v2/ontology/insight-search-ids`
- Auth: none declared

Semantically-matched insight ids, in relevance order.

Restores semantic search to the insight pickers (PRO-3373). They had moved
to substring matching over the in-memory catalog, which cost recall — a
query matched "employer" but not "employment" — and silently dropped
everything related-but-not-lexically-similar even on queries that did
match.

Search runs against turbopuffer and returns ids only; the client intersects
against the catalog it already holds, in the order returned. No Neo4j round
trip happens — ``search_insight`` hydrates hits against the graph inside the
vector call, and this path uses a graph-free retriever instead, which is what
moving the corpus into the browser was supposed to buy.

## Query parameters

- `search` string, required: Search query
- `insight_types` string[], nullable: Insight types
- `min_score` number: Minimum relevance score
- `limit` integer: Max ranked ids to return. Defaults to full-corpus coverage, which is what a client filtering the whole catalog locally needs. A typeahead rendering a short list should pass its own row cap instead of asking for the corpus on every keystroke.

## Request body

- object, nullable

## Response `200`

Successful Response

- InsightSearchIdsResponse: Semantically-matched insight ids, **in relevance order**. Same bargain as :class:`InsightLinkedResponse` — the client holds the catalog, so a search costs an id list rather than a hydrated listing, and no graph materialization happens on the search path. One difference, and it is load-bearing: these ids are ordered by the vector search's fused ranking, so a client must map over them in order rather than filter its own corpus by membership. An adjacency filter can keep catalog order because nothing ranks it; a search result that loses its order looks broken even when the ids are right. ``truncated`` reports that the search returned as many hits as it was allowed, so lower-ranked matches were cut.
  - `insight_ids` integer[], required
  - `total` integer, required
  - `truncated` boolean

## Other responses

- `404`: Not Found
- `422`: Validation Error

## Changes

- **2026-09-03** `475c0fdb4aaf`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/carbonarc/apis/carbon-arc-api-documentation/changes/v2/ontology/insight-search-ids/get.md)

---

[API](https://skmtc.dev/carbonarc/apis/carbon-arc-api-documentation.md) · [All operations](https://skmtc.dev/carbonarc/apis/carbon-arc-api-documentation/llms.txt) · [OpenAPI document](https://skmtc.dev/carbonarc/apis/carbon-arc-api-documentation/revisions/7362ca3a398d?raw)