---
title: "Get Insights List"
method: GET
path: "/v2/ontology/insights"
tags: ["Ontology"]
---

# Get Insights List

`GET /v2/ontology/insights`

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

Fetch insights, with pagination.
Optimized for new builder workflow - only entity_id is required for filtering.
When event_id is provided, only insights linked to that event are returned.
When search + event_id are both provided, ES insight search is used treating
event_id as entity_id and event_representation as entity_representation.

## Query parameters

- `entity_id` integer, nullable: Entity ID
- `entity_representation` string, nullable: Entity Representation
- `entity` string, nullable: Entity Filter
- `subject_ids` integer[], nullable: Subject IDs
- `topic_ids` integer[], nullable: Topic IDs
- `insight_types` string[], nullable: Insight types
- `dataset_ids` string[], nullable: Dataset IDs
- `event_id` integer, nullable: Filter insights to those linked to this event (carc_id of an event EntityRepresentation). ANDed with entity_id/entity_representation when both are provided.
- `event_representation` string, nullable: Representation type of the event node (e.g. 'corpeventc'). Used alongside event_id to uniquely scope the event. When search is also provided, passed as entity_representation to ES.
- `event_category_id` integer, nullable: Filter insights to those linked to events of this category (carc_id of an EventCategory node).
- `search` string, nullable: Search term
- `include_metadata` boolean: Include full metadata (descriptions, timestamps, delay status)
- `min_score` number: Minimum search score, between 0 and 1
- `page` integer: Page number for insights list
- `size` integer: Number of insights per page
- `sort_by` string, nullable: Field to sort insights by (currently only 'label' is supported)
- `order` string: Sort direction (asc/desc)
- `rand_seed` string, nullable: Random seed for featured items
- `featured_insight_ids` integer[], nullable: Featured insight IDs

## Response `200`

Successful Response

- InsightResponse
  - `total` integer, required
  - `page` integer, required
  - `size` integer, required
  - `pages` integer, required
  - `items` InsightResponseItem[], required
    - `insight_id` integer, required
    - `label` string, required
    - `sources` string[], nullable
    - `topic_label` string, nullable
    - `topic_key` string, nullable
    - `topic_id` integer, nullable
    - `subject_label` string, nullable
    - `subject_key` string, nullable
    - `subject_id` integer, nullable
    - `dataset_id` string, nullable
    - `insight_type_label` string, required
    - `insight_type` string, required
    - `is_event` boolean, nullable
    - `historic` boolean, nullable
    - `has_entity` boolean, nullable
    - `insight_name` string, nullable
    - `description` string, nullable
    - `subject_description` string, nullable
    - `topic_description` string, nullable
    - `delay_status` object, nullable
    - `last_updated_timestamp` string, date-time, nullable
    - `blocked` integer, nullable
    - `insight_overview` integer, nullable
    - `last_reinstated_timestamp` string, date-time, nullable
    - `reinstatement_reason` string, nullable
    - `table_max_date` string, date-time, nullable
    - `relevance_score` number, nullable
    - `ontology_version` string, nullable
    - `available_entity_representations` string[], nullable

## Other responses

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

## Changes

- **2026-11-06** `73e487cff957`: 1 info
  - added the optional property `items/items/available_entity_representations` to the response with the `200` status
- **2026-10-22** `4b55ac4735ad`: 1 breaking
  - removed the request body
- **2026-09-25** `81f915d799ee`: 4 breaking, 2 warning, 1 info
  - `query` request parameter `min_score` list-of-types was narrowed by removing types `null`
  - `query` request parameter `order` list-of-types was narrowed by removing types `null`
  - added the pattern `^(asc|desc)$` to the `query` request parameter `order`
  - for the `query` request parameter `min_score`, the type changed from no type to `number`
  - …3 more
- **2026-07-26** `6ba1ca74e6c7`: 7 info
  - added the new optional `query` request parameter `event_category_id`
  - added the new optional `query` request parameter `event_id`
  - added the new optional `query` request parameter `event_representation`
  - added the optional property `items/items/has_entity` to the response with the `200` status
  - …3 more

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