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

# Scoped Insight Search Ids

`POST /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 inside ``scope_insight_ids``, in
relevance order.

For a client that renders a scoped universe (the Builder's entity-, event-
or dataset-scoped insight list). Ranking the corpus with the GET and
intersecting afterwards caps the wrong list: every in-scope insight below the
corpus-wide top ``limit`` is gone before the intersection runs.

## Request body

- BodyScopedInsightSearchIdsV2OntologyInsightSearchIdsPost
  - `search` string, required: Search query
  - `scope_insight_ids` integer[], required: Rank only these insights. The cap applies to the in-scope ranking, so nothing in scope is lost to a better-ranked insight outside it.
  - `insight_types` string[], nullable: Insight types
  - `min_score` number: Minimum relevance score
  - `limit` integer: Max ranked ids to return from inside the scope.

## 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-11-13** `e6e8455dcc09`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/carbonarc/apis/carbon-arc-api-documentation/changes/v2/ontology/insight-search-ids/post.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/e6e8455dcc09?raw)