---
title: "List gaps"
method: GET
path: "/org/gaps"
tags: ["Gaps"]
---

# List gaps

`GET /org/gaps`

## Request

- Base URL: `https://apiv2.senso.ai/api/v1`
- URL: `https://apiv2.senso.ai/api/v1/org/gaps`
- Auth: API key in header `X-API-Key`

Returns a page of your organization's gap queue, the same queue the Senso app shows as the Gap Report. With no `statuses` filter only `open`, `reopened` and `addressed` gaps are returned, so an API search gap seen only once (`weak`) does not appear until you ask for it with `statuses=weak`.

Repeatable filters are sent as repeated query parameters (`?statuses=weak&statuses=open`). Values within one filter are ORed; different filters are ANDed.

## Query parameters

- `statuses` GapStatus[]
- `problems` GapProblem[]
- `surfaces` GapSurface[]
- `origin_kinds` GapOriginKind[]
- `kinds` GapKind[]
- `tag_ids` string[]
- `search` string
- `sort` 'severity' | 'recent' | 'demand'
- `limit` integer
- `offset` integer

## Response `200`

A page of the gap queue.

- GapListResponse
  - `gaps` Gap[], required
    - `gap_id` string, uuid, required
    - `kind` 'missing' | 'conflict' | 'kb_conflict' | 'flagged', required: `missing`, `conflict` (claim against the knowledge base), `kb_conflict` (two knowledge-base documents disagree) or `flagged`.
    - `problem` 'conflict' | 'not_found' | 'no_source' | 'flagged', required: The state the queue badges and counts by: `conflict` (the knowledge base disagrees), `not_found` (nothing was found for the question), `no_source` (nothing backs a claim), `flagged` (a person marked an answer wrong).
    - `status` 'weak' | 'open' | 'reopened' | 'addressed' | 'resolved' | 'dismissed' | 'dormant', required: Where a gap is in its lifecycle. `weak` is a gap with too little evidence to act on yet (an API search gap seen once). `open` and `reopened` are work to do. `addressed` means something was written that later evidence has not yet confirmed. `resolved` and `dismissed` are closed. `dormant` has not been seen for a while.
    - `claim_text` string, required: The gap in words — the claim that could not be backed up, or the question that went unanswered.
    - `occurrence_count` integer, required: How many times the gap was seen.
    - `asker_count` integer, required: Distinct signed-in people behind those sightings. Calls made with API keys are not counted here.
    - `api_occurrence_count` integer, required: Sightings that came from API-key calls. Never added into `asker_count`.
    - `surfaces` GapSurface[], required: Every surface the gap was seen on.
    - `first_seen_at` string, date-time, required
    - `last_seen_at` string, date-time, required
    - `contradicting_content_id` string, uuid: The knowledge-base content a claim contradicts. Grounding-checked.
    - `contradicting_content_title` string
    - `suggested_content_id` string, uuid: Content that may be relevant. An unverified hint, not a finding.
    - `suggested_content_title` string
    - `assigned_user_id` string, uuid
    - `assigned_user_name` string
    - `assigned_user_email` string
    - `status_changed_at` string, date-time, required
    - `awaiting_update` boolean, required: True when the latest resolution ruled which side is correct but the losing document has not been updated yet, so the gap is still `open` or `reopened`.
    - `tags` GapTag[], required
      - `tag_id` string, uuid, required
      - `name` string, required
      - `curated` boolean, required: True = part of the organization's working vocabulary; false = machine-minted, awaiting adoption.
    - `latest_resolution` GapResolution: One decision recorded against a gap.
      - `resolution_id` string, uuid, required
      - `resolution_type` 'answered' | 'content_added' | 'content_updated' | 'ruled_kb_correct' | 'ruled_claim_correct' | 'ruled_document' | 'dismissed' | 'not_relevant' | 'we_dont_do_this' | 'source_irrelevant', required: What was decided about a gap. See `POST /org/gaps/{gapId}/resolutions` for the effect of each.
      - `ruling_side` 'kb' | 'claim' | 'document'
      - `authority_content_id` string, uuid
      - `authority_content_version_id` string, uuid
      - `produced_content_id` string, uuid
      - `produced_content_version_id` string, uuid
      - `notes` string
      - `resolved_by_name` string: The person who recorded it. Absent when it was recorded with an API key.
      - `resolved_by_email` string: Absent when it was recorded with an API key.
      - `created_at` string, date-time, required
    - `origin` GapOrigin: Where a gap came from, derived from its most recent sighting.
      - `kind` 'claim' | 'unanswered_question' | 'flagged_answer' | 'documents_didnt_answer' | 'api_unanswered_question', required: What produced a gap: `claim` (a statement that could not be verified), `unanswered_question` (a Quick Search that found nothing), `flagged_answer` (an answer a person marked wrong), `documents_didnt_answer` (documents were found but the answer still declined), or `api_unanswered_question` (a search through the org API, the MCP server or the CLI that found nothing).
      - `surface` 'search_turn' | 'content' | 'question_run' | 'api_search', required: Where a gap was seen: `search_turn` (Quick Search in the Senso app), `content` (something being written), `question_run` (a tracked prompt's AI answer), or `api_search` (a search through the org API, the MCP server or the CLI).
      - `subject_id` string, uuid: The search turn, content item or question run behind the most recent sighting. For an API search gap, the most recent search that found nothing.
      - `title` string: A name for the subject — a document title, a tracked prompt, or the question asked.
      - `model_label` string: The engine that produced the answer. Absent for content, which a person wrote.
      - `eval_mode` string: How thoroughly the subject was checked. Absent for search signals, which are not judged.
      - `surface_counts` GapSurfaceCounts, required: How many times the gap was seen on each surface.
        - `search_turn` integer, required
        - `content` integer, required
        - `question_run` integer, required
        - `api_search` integer, required
      - `session_id` string, uuid: The Quick Search conversation the sighting happened in. Absent for API search gaps.
      - `geo_question_id` string, uuid: The tracked prompt behind an AI answer.
      - `kb_node_id` string, uuid: The knowledge-base document behind a content sighting. Absent when that document was deleted.
  - `total` integer, required: Gaps matching the filters, across all pages.
  - `limit` integer, required
  - `offset` integer, required

## Other responses

- `400`: The request was malformed — a bad path/query parameter or an invalid value.
- `401`: Missing or invalid credentials — supply a valid org API key in the `X-API-Key` header.
- `403`: The API key is authenticated but not permitted to access this resource.

---

[API](https://skmtc.dev/senso/apis/senso-org-api.md) - [All operations](https://skmtc.dev/senso/apis/senso-org-api/llms.txt) - [OpenAPI document](https://skmtc.dev/senso/apis/senso-org-api/revisions/d789b4fcbe84?raw)