---
title: "Linked Insight Ids"
method: GET
path: "/v2/ontology/insights/linked"
tags: ["Ontology"]
---

# Linked Insight Ids

`GET /v2/ontology/insights/linked`

## 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/insights/linked`
- Auth: none declared

Insight ids linked to the requested entity / event scope.

The browser already holds the whole store from ``/all-insights``,
so scoping a browse only needs graph adjacency: it intersects these ids
with the corpus it has instead of refetching a listing. Adjacency is not
user-specific — provider access is already applied to the store the ids
are intersected with.

Scopes AND together, the same way the paginated listing stacks its entity
and event pre-filters. Adjacency does not vary with subject/topic/dataset
filters, so those are not accepted here — the caller narrows the
intersection it already holds.

``candidate_id`` asks the picker's second question against the same
intersection: which of the entities on screen would empty it. That belongs
here rather than on the entity listing, which is response-cached across all
of its filters — folding a per-selection answer into that key would give
every distinct selection its own copy of every page, for one bit per row.

## Query parameters

- `entity_id` integer[], nullable: Entity carc_ids (paired with entity_representation)
- `entity_representation` string[], nullable: Representations paired 1:1 with entity_id
- `event_id` integer, nullable: carc_id of an event EntityRepresentation (paired with event_representation).
- `event_representation` string, nullable: Representation type of the event node (e.g. 'corpeventc').
- `event_category_id` integer, nullable: carc_id of an EventCategory — insights linked to any event under it.
- `candidate_id` integer[], nullable: carc_ids of entities being offered as additions to the scope (paired with candidate_representation). Each one is reported back in incompatible_entities if it shares no insight with the scope.
- `candidate_representation` string[], nullable: Representations paired 1:1 with candidate_id

## Request body

- object, nullable

## Response `200`

Successful Response

- InsightLinkedResponse: Insight ids linked to the requested entity / event scope. Adjacency only — the client already holds the store and intersects locally, so scoping a browse costs an id list, not a listing. ``incompatible_entities`` answers the picker's other question in the same round trip: of the candidate entities on screen, which ones share nothing with the scope, so their cards must be disabled rather than allowed into a group that has nothing left to query. Only the incompatible pairs are listed, because on a browse page they are the rare case and absence is the answer the client acts on by doing nothing. Absence is deliberately not a positive answer. A candidate the precompute cannot resolve is omitted for the same reason the adjacency lookup declines rather than returning an empty list, so a client must read "not listed" as selectable, never as verified-compatible.
  - `insight_ids` integer[], required
  - `incompatible_entities` array[]
    - unknown[]
      - unknown

## Other responses

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

## Changes

- **2026-09-03** `475c0fdb4aaf`: 3 info
  - added the new optional `query` request parameter `candidate_id`
  - added the new optional `query` request parameter `candidate_representation`
  - added the optional property `incompatible_entities` to the response with the `200` status
- **2026-07-31** `1d445d2a69b5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/carbonarc/apis/carbon-arc-api-documentation/changes/v2/ontology/insights/linked/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)