---
title: "Query rows from a dataset"
method: POST
path: "/api/v1/datasets/{id}/query"
tags: ["Data"]
---

# Query rows from a dataset

`POST /api/v1/datasets/{id}/query`

## Request

- Base URL: `https://askthegrid.com`
- URL: `https://askthegrid.com/api/v1/datasets/{id}/query`
- Auth: HTTP bearer

Structured query compiled server-side against the dataset's catalog contract, then executed through the guarded warehouse boundary: catalog allow-list, per-market scope predicate, and a hard row cap. During beta, authenticated access supports up to 10,000 rows per request and 120 requests per minute, defaulting to 100 rows. API, MCP, agent queries and exports share a daily abuse backstop of 1,000,000 rows, 2 GiB of JSON row data and 10,000 requests. The compiled SQL is returned so the caller can see exactly what ran. The MCP equivalent is the `query_data` tool.

## Path parameters

- `id` string, required

## Request body

- object
  - `market` 'ERCOT' | 'CAISO' | 'NYISO' | 'PJM' | 'SPP' | 'MISO' | 'ISONE' | 'BPAT' | 'TVA' | 'DUK' | 'CPLE' | 'CPLW' | 'FPC' | 'FPL' | 'SOCO' | 'BCA' | 'AESO' | 'IESO' | 'CENACE' | 'HQ' | 'BCH' | 'MHEB' | 'SPC' | 'NBSO' | 'NSIESO', required
  - `columns` string[]
  - `from` string
  - `to` string
  - `filters` object[]
    - `column` string, required
    - `op` 'eq' | 'in' | 'gt' | 'gte' | 'lt' | 'lte'
    - `value` union, required
      - string
      - number
      - boolean
      - union[]
        - union
          - string
          - number
  - `orderBy` string
  - `orderDir` 'asc' | 'desc'
  - `limit` integer

## Response `200`

Success

- object
  - `datasetId` string, required
  - `market` 'ERCOT' | 'CAISO' | 'NYISO' | 'PJM' | 'SPP' | 'MISO' | 'ISONE' | 'BPAT' | 'TVA' | 'DUK' | 'CPLE' | 'CPLW' | 'FPC' | 'FPL' | 'SOCO' | 'BCA' | 'AESO' | 'IESO' | 'CENACE' | 'HQ' | 'BCH' | 'MHEB' | 'SPC' | 'NBSO' | 'NSIESO', required
  - `columns` string[], required
  - `rows` object[], required
  - `rowCount` number, required
  - `truncated` boolean, required
  - `sql` string, required
  - `elapsedMs` number, required

## 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)