# Dataset coverage visible to the caller

`GET /v1/coverage`

What the caller can obtain: per dataset and competition, the covered period,
territory, sampling resolution, history watermark and status (`available`,
`partial`, `restricted` by the caller's grant or because no covering source may be
displayed, `unsupported` by the platform, `unavailable` right now). A `restricted`
item discloses nothing beyond its status: its period, sampling and `watermark_at` are
null and there are no source references. No item names a competition your entity reads
do not serve. The match facts (`lineups`, `statistics`, `events`, `context`) have one item
per competition (no territory) whose watermark is the newest version the item's covering
sources recorded for its fixtures, counting only the covering sources you may be shown.
Stable order: `dataset`, then `competition_id`, then `territory`. Source
references appear where source rights permit.

Parameters:
- `competition_id` (query, string, optional): Competition identifier (`cmp_<digits>`).
- `dataset` (query, enum, optional):  One of: `entities`, `lineups`, `statistics`, `events`, `context`, `coverage`, `account`.
- `cursor` (query, string, optional): Opaque page cursor from a previous `page.next_cursor`; filters must be repeated unchanged.
- `limit` (query, integer, optional): Maximum items per page.

Returns `200`: One page of coverage entries.
- `items` (array of objects):  See [the coverage item object](obj-CoverageItem.md).
- `page` (object)
  - `next_cursor` (string, nullable): Cursor for the next page, or `null` on the last page.
  - `limit` (integer)

Errors: `400` Malformed parameter or cursor (`invalid-request`).; `401` Missing or invalid credential (`unauthenticated`).; `403` Operation not permitted (`forbidden`) or restricted by grants/rights (`not-entitled`).; `422` Well-formed but unanswerable (`invalid-range`, `unsupported-historical-capability`).; `429` The per-minute rate limit is used up (`rate-limited`) or a daily allowance is exhausted (`quota-exceeded`). Failed requests (403, 404, other 4xx, 5xx) use up the per-minute rate limit too.; `500` Unexpected failure (`internal-error`); `request_id` identifies the server-side record.; `503` A service this operation depends on, or the access check, is temporarily unavailable (`unavailable`, `policy-unavailable`).

Example request (200 · Default):

```bash
curl -G https://api.example.com/v1/coverage \
  -H "X-API-Key: $ODDSFINDER_API_KEY" \
  -d competition_id=cmp_1
```

Example response (200):

```json
{
  "items": [
    {
      "dataset": "entities",
      "competition_id": "cmp_1",
      "territory": null,
      "from": "2026-08-01T00:00:00Z",
      "to": null,
      "status": "available",
      "sampling_resolution_seconds": null,
      "watermark_at": null,
      "sources": {
        "status": "included",
        "items": [
          {
            "source": "synthetic_alpha",
            "observed_at": "2026-09-25T08:55:00Z",
            "recorded_at": "2026-09-25T09:00:00Z",
            "precision": "minute"
          },
          {
            "source": "synthetic_beta",
            "observed_at": null,
            "recorded_at": "2026-09-01T00:00:00Z",
            "precision": "unknown"
          }
        ]
      }
    }
  ],
  "page": {
    "next_cursor": null,
    "limit": 50
  }
}
```