---
title: "Search the full dataset catalog"
method: GET
path: "/api/v1/catalog"
tags: ["Data"]
---

# Search the full dataset catalog

`GET /api/v1/catalog`

## Request

- Base URL: `https://askthegrid.com`
- URL: `https://askthegrid.com/api/v1/catalog`
- Auth: HTTP bearer

The complete catalog with schema contracts. For the developer-facing index of readable datasets, prefer `GET /api/v1/datasets`.

## Query parameters

- `q` string
- `agent` string
- `include` string
- `scope` string

## Response `200`

Success

- object
  - `datasets` object[], required
    - `id` string, required
    - `name` string, required
    - `table` string, required
    - `source` string, required
    - `category` 'Prices' | 'Ancillary Services' | 'Congestion & Constraints' | 'Load' | 'Generation' | 'Interchange' | 'Outages & Grid Events' | 'Infrastructure' | 'Weather' | 'Hydrology', required
    - `description` string, required
    - `frequency` string, required
    - `primaryKey` string[], required
    - `timeColumn` string, nullable, required
    - `marketScopes` string[], required
    - `agentAccess` 'sql' | 'none', required
    - `contract` object, required
      - `version` 3, required
      - `grain` string, required
      - `evidence` 'observed' | 'forecast' | 'cleared_day_ahead_market' | 'reference' | 'mixed', required
      - `canonicalization` string, required
      - `time` object, required
        - `eventColumn` string, nullable, required
        - `publicationColumn` string
        - `eventSemantics` 'instant' | 'interval_start' | 'interval_end' | 'date_label', required
        - `timezone` 'UTC', required
      - `aggregationRules` string[], required
      - `cautions` string[], required
      - `causalEvidence` 'none' | 'component' | 'constraint' | 'attribution', required
      - `scope` object, required
        - `markets` string[], required
        - `sql` union[], required
          - union
            - object
              - …
            - object
              - …
            - object
              - …
      - `query` object, required
        - `historicalOnly` boolean
        - `readMode` 'plain' | 'final', required
        - `intervalMinutes` number, nullable, required
        - `publicationColumn` string, nullable, required
        - `vintageSelection` union, required
          - object
            - `mode` 'closest_to_event', required
            - `partitionBy` string[], required
            - `maxPostEventMinutes` number, required
          - object
            - `mode` 'latest_available', required
            - `partitionBy` string[], required
        - `requiredFilters` object[], required
          - `column` string, required
          - `operator` 'eq', required
          - `value` union, required
            - string
            - number
            - boolean
          - `purposes` string[]
          - `reason` string, required
        - `freshnessMaxAgeMinutes` number, nullable, required
        - `emptyResultMeaning` 'unknown' | 'authoritative_for_filtered_scope', required
      - `measureContracts` object[], required
        - `name` string, required
        - `description` string, required
        - `unit` string
        - `expression` string
        - `inputs` string[]
        - `additivityGroup` string
        - `populatedWhen` object[]
          - `column` string, required
          - `values` string[], required
      - `entityContracts` object[], required
        - `column` string, required
        - `role` 'identity' | 'selector'
        - `aliases` object, required
      - `relationships` object[], required
        - `datasetId` string, required
        - `kind` 'companion' | 'comparison' | 'derivation', required
        - `supports` string[], required
        - `alignment` string, required
        - `expression` string
      - `sqlRequirements` object[]
        - `pattern` string, required
        - `reason` string, required
        - `purposes` string[]
    - `columns` object[]
      - `name` string, required
      - `type` string, required
      - `role` 'event_time' | 'publication_time' | 'key' | 'measure' | 'dimension', required
    - `schemaError` string

## Other responses

- `400`: The request did not match the contract.
- `401`: Missing or invalid credentials.
- `429`: Rate limit exceeded. Wait `Retry-After` seconds; `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` report the budget. Signed-in sessions and API keys have larger budgets than anonymous callers.

---

[API](https://skmtc.dev/askthegrid/apis/ask-the-grid-api.md) · [All operations](https://skmtc.dev/askthegrid/apis/ask-the-grid-api/llms.txt) · [OpenAPI document](https://skmtc.dev/askthegrid/apis/ask-the-grid-api/revisions/9cd80115e395?raw)