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

# Get Insights List

`GET /v2/ontology/insights`

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, nullable — 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, nullable — Sort direction (asc/desc)
- `rand_seed` string, nullable — Random seed for featured items
- `featured_insight_ids` integer[], nullable — Featured insight IDs

## Request body

- object, nullable

## 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

## Other responses

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

---

[API](https://skmtc.net/carbonarc/apis/carbon-arc-api-documentation.md) · [All operations](https://skmtc.net/carbonarc/apis/carbon-arc-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/carbonarc/carbon-arc-api-documentation/revisions/bd33ea42994c/schema)