> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alterscope.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Coverage Manifest

> Honest coverage. Verify exactly what you are buying before you buy it.

The data coverage manifest is the institutional-trust artifact of the
Alterscope API. It is a machine-readable inventory of which markets, vaults,
feeds, and protocols we have complete data for, and where we have known gaps.
You can stake risk decisions on the answer because the answer names its own
gaps.

There are two endpoints:

* `GET /v2/data-manifest` returns the top-level summary across every scope.
* `GET /v2/data-manifest/coverage` returns per-row coverage with named gaps,
  sorted worst-covered first.

## Refresh cadence

Both endpoints are cached for **5 minutes**. The actual cache age is reported
on every response at `meta._agentic.freshness.age_seconds`, and the next
refresh is at `meta._agentic.freshness.next_update_at`. The cache TTL is
honest: a non-zero `age_seconds` means the snapshot is older than zero seconds,
not "fresh because we said so."

## Endpoint: `GET /v2/data-manifest`

Open access. Returns the cross-scope inventory.

```bash theme={null}
curl -s https://api.alterscope.org/v2/data-manifest
```

```json theme={null}
{
  "data": {
    "generated_at": "2026-05-04T12:00:00Z",
    "markets": {
      "total": 968,
      "classified": 545,
      "fresh": 300,
      "stale": 200,
      "unverifiable": 45,
      "unknown": 423
    },
    "feeds": {
      "total": 350,
      "with_metadata": 350,
      "with_history": 16,
      "complete": 16
    },
    "vaults": {
      "total": 12,
      "governance_indexed": 12
    },
    "protocols": {
      "morpho-blue": { "markets": 968, "vaults": 12 }
    }
  },
  "meta": {
    "_agentic": {
      "freshness": {
        "age_seconds": 12,
        "status": "fresh",
        "update_cadence_seconds": 300
      }
    }
  }
}
```

The honest framing matters: `markets.unknown = 423` means 423 markets have
classification rows but the staleness probe could not assign a verdict yet.
That is the gap, not a bug, and it is the contract this endpoint exists to
expose.

## Endpoint: `GET /v2/data-manifest/coverage`

Team plan or higher. Returns per-row coverage with completeness percentages
and gap arrays.

```bash theme={null}
curl -s -H "Authorization: Bearer sk_live_..." \
  "https://api.alterscope.org/v2/data-manifest/coverage?scope=oracle_feed&min_completeness_pct=0&limit=10"
```

```json theme={null}
{
  "data": [
    {
      "chain": "ethereum",
      "scope": "oracle_feed",
      "scope_id": "0xfeed1...",
      "label": "ETH/USD",
      "classified": true,
      "has_metadata": true,
      "history_completeness_pct": 0.0,
      "last_update_at": null,
      "gaps": [
        { "kind": "missing_history" }
      ]
    }
  ],
  "meta": {
    "total": 10,
    "has_more": true,
    "cursor": "MzAuMDoz",
    "_agentic": {
      "freshness": { "age_seconds": 8, "status": "fresh" }
    }
  }
}
```

### Query parameters

| Param                  | Description                                                         |
| ---------------------- | ------------------------------------------------------------------- |
| `scope`                | One of `oracle_feed`, `morpho_market`, `morpho_vault`, `protocol`.  |
| `scope_id`             | Filter to a single scope id (e.g. a feed address or vault address). |
| `min_completeness_pct` | Filter rows with completeness at or above this percent. Default 0.  |
| `cursor`               | Opaque cursor from the previous response's `meta.cursor`.           |
| `limit`                | Page size. Default 50, max 500.                                     |

### Sort order

Rows are ordered by `history_completeness_pct` ASC, then `id` ASC. Worst-
covered first is intentional. Customers asking "what is the gap" should not
have to scroll past the well-covered rows to find it.

### Gap kinds

| Kind               | Meaning                                                                      |
| ------------------ | ---------------------------------------------------------------------------- |
| `missing_metadata` | Row has no metadata in its registry table.                                   |
| `missing_history`  | Row has metadata but no time-series rows yet.                                |
| `stale`            | Row has data but the latest update is older than the heartbeat.              |
| `unverifiable`     | The row's freshness semantics are not modelled (e.g. non-V2 oracle adapter). |

### `last_update_at` contract

`last_update_at` reflects when the underlying data last changed (most recent
oracle price, governance event, or registry write), not when the manifest row
was computed. Manifest computation time is on `meta._agentic.freshness.computed_at`.

### `completeness_pct` math

`completeness_pct = rows_present / rows_expected_if_full * 100`.

Per scope:

| Scope           | `rows_present`                                                  | `rows_expected_if_full`                                   |
| --------------- | --------------------------------------------------------------- | --------------------------------------------------------- |
| `oracle_feed`   | rows in `oracle_price_history` for the feed                     | `(now - earliest_observed) / heartbeat_seconds`           |
| `morpho_market` | 1 if classified and staleness is non-unknown, else 0            | 1                                                         |
| `morpho_vault`  | distinct event types observed in `metamorpho_governance_events` | 7 (timelock, guardian, allocator, cap, fee, owner, queue) |
| `protocol`      | sum of per-market `completeness_pct` divided by 100             | total markets in protocol                                 |

The math is documented in the handler source so it can be audited at the
`grep` boundary, not just here.

## Tier gating

| Tier                     | `GET /v2/data-manifest` | `GET /v2/data-manifest/coverage` |
| ------------------------ | ----------------------- | -------------------------------- |
| Free, Analyst            | open                    | 402 with upgrade URL             |
| Team, Enterprise, Custom | open                    | full per-row response            |