---
title: "GET /api/v1/gaps"
method: GET
path: "/api/v1/gaps"
tags: ["registry"]
---

# GET /api/v1/gaps

`GET /api/v1/gaps`

## Request

- Base URL: `https://api.metagraph.sh`
- URL: `https://api.metagraph.sh/api/v1/gaps`
- Auth: none required

Fetch interface gap report.

## Query parameters

- `netuid` integer
- `coverage_level` 'native-only' | 'manifested' | 'probed'
- `curation_level` 'native' | 'candidate-discovered' | 'community-seeded' | 'machine-verified' | 'maintainer-reviewed' | 'adapter-backed'
- `fields` string
- `limit` integer
- `cursor` integer
- `page_snapshot` string
- `sort` 'coverage_level' | 'curation_level' | 'gap_count' | 'name' | 'netuid'
- `order` 'asc' | 'desc'

## Response `200`

Canonical artifact wrapped in the Metagraphed API envelope.

- object
  - `data` object, required: Registry-wide interface gap report page. Mirrors GET /api/v1/gaps (and MCP list_gaps).
    - `contract_version` string
    - `gaps` object[], required
      - `coverage_level` 'native-only' | 'manifested' | 'probed', required
      - `curation_level` 'native' | 'candidate-discovered' | 'community-seeded' | 'machine-verified' | 'maintainer-reviewed' | 'adapter-backed', required
      - `gap_count` integer
      - `gap_priority` integer
      - `gap_severity` 'critical' | 'warning' | 'info'
      - `gaps` Gaps, required
        - `gap_notes` string[], required
        - `missing_kinds` SurfaceKind[], required
        - `moving_target_surfaces` string[]
        - `supported_kinds` SurfaceKind[], required
      - `name` string, required
      - `netuid` integer, required
      - `schema_parity` object
        - `capture_cadence_hours` number, required: The capture lane's declared cadence in hours. Compare it against the backing entries' `snapshot.observed_at` (GET /api/v1/schemas) to judge whether this measurement rests on a current capture. No age is baked: this document is served for hours after it is built, so a build-stamped age would be wrong on arrival.
        - `captured_path_count` integer, required: Paths the subnet's captured spec(s) declare, summed across captured specs.
        - `captured_schema_count` integer, required: Captured machine-readable specs backing this measurement.
        - `declared_non_get_count` integer, nullable, required: Declared POST/PUT/PATCH/DELETE operations. NULL when the captured entries predate the capture-time stamp -- unmeasured, not zero.
        - `flagged` boolean, required: True when the subnet declares more paths than the catalogue registers as routes -- a caller reading only the registry cannot tell which routes are missing. Judge its currency from the entry's `observed_at` against the schema index's `capture_cadence_hours`.
        - `registered_non_get_count` integer, required: Registered surfaces declaring a non-GET method (#11146 phase 3).
        - `registered_route_surface_count` integer, required: Registered concrete route surfaces (subnet-api/sse/data-artifact; the openapi spec surface itself is not a route).
      - `slug` string, required
    - `generated_at` string, required
    - `notes` union: Public-safe notes; may be a string or a string list depending on the adapter.
      - string
      - string[]
    - `schema_version` 1, required
  - `meta` ResponseMeta, required
    - `artifact_path` string
    - `cache` 'short' | 'standard' | 'static'
    - `catalog_paging` object
      - `reason` 'catalog_changed' | 'catalog_budget_exceeded' | 'catalog_unavailable', required
    - `contract_version` string, required
    - `generated_at` string, nullable: Deterministic build content marker (epoch by default); not a wall clock. Use published_at for human-facing freshness.
    - `observed_through` string, date-time, nullable: How far the tier that answered this request has observed at all. A payload reporting no activity at or before this time is a measured absence; one whose subject is newer is outside coverage, not empty. Null when the horizon is unreadable.
    - `pagination` PaginationMeta
      - `collection` string, required
      - `cursor` integer, required
      - `limit` integer, required
      - `next_cursor` integer, nullable, required
      - `order` 'asc' | 'desc'
      - `returned` integer, required
      - `snapshot` string: Present only for page_snapshot paging. Echo as page_snapshot on subsequent pages; a changed collection or query requires a restart.
      - `sort` string, nullable
      - `total` integer, required
    - `published_at` string, date-time, nullable: Real publish time from the KV latest pointer, distinct from generated_at. Null before the first publish or when the control KV is unbound.
    - `source` string
    - `stale_contract` object: Present ONLY when the served artifact was built under an older contract than the live one (serve-time drift, #1001) — the body may predate a schema change. Mirrored on the x-metagraph-stale-contract response header for monitoring.
      - `built_under` string, required: Contract version the served artifact was built under.
      - `live` string, required: Current (live) contract version the Worker is running.
  - `ok` true, required
  - `schema_version` 1, required

## Other responses

- `304`: ETag matched and the cached response is still valid.
- `400`: Query parameters were malformed or unsupported.
- `404`: Artifact or API route was not found.
- `405`: HTTP method is not supported.
- `500`: Unexpected backend error.

---

[API](https://skmtc.dev/metagraph/apis/metagraphed-api.md) · [All operations](https://skmtc.dev/metagraph/apis/metagraphed-api/llms.txt) · [OpenAPI document](https://skmtc.dev/metagraph/apis/metagraphed-api/revisions/e29036024bb1?raw)