## Coverage

There is no separate endpoint for the list of retailers or the list of
categories — [`GET /v1/coverage`](/reference) is how you see what exists,
and it returns one row per **RCD combination**: a retailer, a category, and
the department that category sits under.

| Field | Meaning |
|---|---|
| `retailer` | Retailer slug |
| `department` | Department slug |
| `category` | Category slug, scoped within `department` |
| `rcd` | `retailer:category:department`, ready to reuse as the `rcd` filter elsewhere |
| `corpus_rows` | Total rows this combination holds |
| `matching_rows` | Rows in this combination that also match any `start_date`/`end_date` you sent |
| `earliest_date` | Earliest `crawl_date` among the matching rows |
| `latest_date` | Most recent `crawl_date` among the matching rows |

Call it with no filters and you get every combination your team can see —
that's the full retailer/category/department vocabulary, since there's no
dedicated endpoint for retailers or categories on their own anymore. Narrow
it with `retailer`, `category`, `department`, or `rcd` to see just the
combinations you care about.

## `rcd`: the combination as one value

`rcd` is the shorthand for a combination: `retailer:category:department`,
comma-separated when you mean more than one. It's exactly the string
`GET /v1/coverage` gives back in each row's `rcd` field — copy it straight
into `/v1/sample`, `/v1/catalog`, or `/v1/coverage` instead of naming
`retailer`, `category`, and `department` separately:

```text
GET /v1/coverage?rcd=home_depot:power_tools:tools,home_depot:hand_tools:tools
```

## `meta.coverage`: coverage without a separate call

Every response from every endpoint — `/v1/sample`, `/v1/catalog`, and
`/v1/coverage` itself — carries a `coverage` block in `meta`, summed across
whatever combinations your filters matched:

```json
{ "combinations": 1, "matching_rows": 6, "corpus_rows": 2361, "earliest_date": "2026-06-14", "latest_date": "2026-08-14" }
```

That's the same shape aggregated: `combinations` is how many RCD rows
matched, `matching_rows` and `corpus_rows` are summed across them, and the
dates span all of them. One request tells you both what you got and how
much exists — see [Requests](/docs/requests).

## Not a required first step

Coverage is useful before a large pull — it answers "does
this window have enough rows before I spend a call finding out" — but
nothing here gates anything else. `/v1/sample` and `/v1/catalog` work with
filters you already know, with no coverage call in between. Guess wrong and
you get [`valid_options`](/docs/error-handling) naming the real values
instead of a working result — that's the only vocabulary lookup this API
needs, and it works from any of the three endpoints, not just this one. See
[Error handling](/docs/error-handling).