Query Parameters

Complete reference for /v1/datasets/{dataset_id}/query, the primary end point for pulling data.

This guide shows parameters for both the direct API (cURL) and the Python client (gridstatusio).

Quick Reference

I want to...	cURL Parameter	Python Client Parameter
Get latest data point	time=latest	Use start, end with limit=1 and query recent data
Query a date range	start_time, end_time	start, end
Filter by location	filter_column=location&filter_value=HB_HOUSTON	filter_column="location", filter_value="HB_HOUSTON"
Filter multiple values	filter_operator=in&filter_value=HB_HOUSTON,HB_NORTH	filter_operator="in", filter_value=["HB_HOUSTON", "HB_NORTH"]
Find values above threshold	filter_column=lmp&filter_operator=>&filter_value=100	filter_column="lmp", filter_operator=">", filter_value=100
Select specific columns	columns=interval_start_utc,lmp	columns=["interval_start_utc", "lmp"]
Get hourly averages	resample_frequency=1 hour&resample_function=mean	resample="1 hour", resample_function="mean"
Get daily peaks	resample_frequency=1 day&resample_function=max	resample="1 day", resample_function="max"
Convert to a specific timezone	timezone=America/Chicago	timezone="America/Chicago"
Convert to the market timezone for the ISO	timezone=market	timezone="market"
Get newest first	order=desc	(handled internally by client)
Limit rows returned	limit=1000	limit=1000
Download as CSV	return_format=csv	Set request_format="csv" in client constructor
Get latest forecast	publish_time=latest	publish_time="latest"
Get day-ahead forecast	publish_time=latest_before:-1 day	publish_time="latest_before:-1 day"

Time Filtering

start_time / end_time

Filter by the dataset's time index column.

cURL Parameter	Python Client Parameter	Type	Description
start_time	start	ISO 8601 datetime	Data on or after this time (inclusive)
end_time	end	ISO 8601 datetime	Data before this time (exclusive)

Formats accepted:

• 2026-01-01 (assumes midnight UTC)

• 2026-01-01T00:00:00

• 2026-01-01T00:00:00Z

• 2026-01-01T00:00:00-05:00 (with offset)

cURL

curl "https://api.gridstatus.io/v1/datasets/ercot_fuel_mix/query?start_time=2026-01-01&end_time=2026-01-02&api_key=YOUR_API_KEY"

Python

import gridstatusio as gs

client = gs.GridStatusClient(api_key="YOUR_API_KEY")

df = client.get_dataset(
    "ercot_fuel_mix",
    start="2026-01-01",
    end="2026-01-02",
)

time

Query for a specific point in time or the latest data. Note: The time parameter is only available via the direct API (cURL). In the Python client, use start/end with limit=1 to achieve similar results.

cURL Parameter	Python Client	Value	Description
time	(not available)	latest	Most recent data point
time	(not available)	ISO 8601 timestamp	Data at exact time

cURL

# Get latest data
curl "https://api.gridstatus.io/v1/datasets/ercot_fuel_mix/query?time=latest&api_key=YOUR_API_KEY"

Python

import gridstatusio as gs
from datetime import datetime, timedelta, timezone

client = gs.GridStatusClient(api_key="YOUR_API_KEY")

# Get latest data by querying recent time range with limit
df = client.get_dataset(
    "ercot_fuel_mix",
    start=datetime.now(timezone.utc) - timedelta(hours=1),
    end=datetime.now(timezone.utc),
    limit=1,
)

time_comparison

Comparison operator for the time parameter. Note: Only available via the direct API (cURL).

cURL Parameter	Python Client	Value	Description
time_comparison	(not available)	=	Exact match (default)
time_comparison	(not available)	>	After the time
time_comparison	(not available)	>=	On or after
time_comparison	(not available)	<	Before the time
time_comparison	(not available)	<=	On or before

Publish Time Filtering

For datasets with forecasts or multiple report versions. Only applies to datasets with a publish_time_column.

publish_time

cURL Parameter	Python Client Parameter	Value	Description
publish_time	publish_time	latest_report	Only the most recently published report
publish_time	publish_time	latest	For each timestamp, the most recent forecast
publish_time	publish_time	ISO 8601 timestamp	Records published at exact time
publish_time	publish_time	latest_before:<offset>	Latest forecast published before operating time + offset
publish_time	publish_time	latest_before:<offset>@HH:MM:SS	Latest forecast before specific time on offset day
publish_time	publish_time	window:<offset>	All forecasts between offset and operating time

Offset format: <number> <unit> where unit is seconds, minutes, hours, days, weeks, months, years

cURL

# Get the most recent forecast for each hour
curl "https://api.gridstatus.io/v1/datasets/ercot_load_forecast/query?publish_time=latest&start_time=2026-01-01&end_time=2026-01-02&api_key=YOUR_API_KEY"

# Get day-ahead forecasts (published at least 1 day before)
curl "https://api.gridstatus.io/v1/datasets/ercot_load_forecast/query?publish_time=latest_before:-1 day&start_time=2026-01-01&end_time=2026-01-02&api_key=YOUR_API_KEY"

Python

import gridstatusio as gs

client = gs.GridStatusClient(api_key="YOUR_API_KEY")

# Get the most recent forecast for each hour
df = client.get_dataset(
    "ercot_load_forecast",
    start="2026-01-01",
    end="2026-01-02",
    publish_time="latest",
)

# Get day-ahead forecasts (published at least 1 day before)
df = client.get_dataset(
    "ercot_load_forecast",
    start="2026-01-01",
    end="2026-01-02",
    publish_time="latest_before:-1 day",
)

publish_time_start / publish_time_end

Filter by publication time range. Cannot be used with publish_time.

cURL Parameter	Python Client Parameter	Type	Description
publish_time_start	publish_time_start	ISO 8601 datetime	Data published on or after this time
publish_time_end	publish_time_end	ISO 8601 datetime	Data published before this time

cURL

# Get forecasts published on a specific day
curl "https://api.gridstatus.io/v1/datasets/ercot_load_forecast/query?publish_time_start=2026-01-01&publish_time_end=2026-01-02&api_key=YOUR_API_KEY"

Python

import gridstatusio as gs

client = gs.GridStatusClient(api_key="YOUR_API_KEY")

# Get forecasts published on a specific day
df = client.get_dataset(
    "ercot_load_forecast",
    start="2026-01-01",
    end="2026-01-02",
    publish_time_start="2026-01-01",
    publish_time_end="2026-01-02",
)

Column Filtering

Filter rows by column values.

cURL Parameter	Python Client Parameter	Type	Description
filter_column	filter_column	string	Column name to filter on
filter_value	filter_value	string, int, or list	Value(s) to match
filter_operator	filter_operator	string	Comparison operator (default: =)

filter_operator Values

Operator	Description
=	Equals (default)
!=	Not equals
>	Greater than
>=	Greater than or equal
<	Less than
<=	Less than or equal
in	Matches any of comma-separated values

Note: When using the in operator with cURL, pass comma-separated values. In the Python client, pass a list.

cURL

# Single value
curl "https://api.gridstatus.io/v1/datasets/ercot_lmp_by_settlement_point/query?filter_column=location&filter_value=HB_HOUSTON&start_time=2026-01-01&end_time=2026-01-02&api_key=YOUR_API_KEY"

# Multiple values
curl "https://api.gridstatus.io/v1/datasets/ercot_lmp_by_settlement_point/query?filter_column=location&filter_value=HB_HOUSTON,HB_NORTH&filter_operator=in&start_time=2026-01-01&end_time=2026-01-02&api_key=YOUR_API_KEY"

# Numeric threshold
curl "https://api.gridstatus.io/v1/datasets/ercot_lmp_by_settlement_point/query?filter_column=lmp&filter_value=100&filter_operator=>&start_time=2026-01-01&end_time=2026-01-02&api_key=YOUR_API_KEY"

Python

import gridstatusio as gs

client = gs.GridStatusClient(api_key="YOUR_API_KEY")

# Single value
df = client.get_dataset(
    "ercot_lmp_by_settlement_point",
    start="2026-01-01",
    end="2026-01-02",
    filter_column="location",
    filter_value="HB_HOUSTON",
)

# Multiple values (use a list with filter_operator="in")
df = client.get_dataset(
    "ercot_lmp_by_settlement_point",
    start="2026-01-01",
    end="2026-01-02",
    filter_column="location",
    filter_value=["HB_HOUSTON", "HB_NORTH"],
    filter_operator="in",
)

# Numeric threshold
df = client.get_dataset(
    "ercot_lmp_by_settlement_point",
    start="2026-01-01",
    end="2026-01-02",
    filter_column="lmp",
    filter_value=100,
    filter_operator=">",
)

Column Selection

columns

Select specific columns to return. Reduces response size.

cURL Parameter	Python Client Parameter	Type	Description
columns	columns	comma-separated string or list	Columns to return

Note: In cURL, pass columns as a comma-separated string. In the Python client, pass a list of column names.

cURL

curl "https://api.gridstatus.io/v1/datasets/ercot_lmp_by_settlement_point/query?columns=interval_start_utc,location,lmp&start_time=2026-01-01&end_time=2026-01-02&filter_column=location&filter_value=HB_HOUSTON&api_key=YOUR_API_KEY"

Python

import gridstatusio as gs

client = gs.GridStatusClient(api_key="YOUR_API_KEY")

df = client.get_dataset(
    "ercot_lmp_by_settlement_point",
    start="2026-01-01",
    end="2026-01-02",
    columns=["interval_start_utc", "location", "lmp"],
    filter_column="location",
    filter_value="HB_HOUSTON",
)

Resampling

Aggregate data to different time frequencies. Requires start_time and end_time (or start and end in Python).

cURL Parameter	Python Client Parameter	Type	Description
resample_frequency	resample	string	Time frequency to aggregate to
resample_function	resample_function	string	Aggregation function (default: mean)
resample_by	resample_by	string or list	Columns to group by when resampling

resample_frequency / resample Values

Value	Description
1 minute	1-minute intervals
5 minutes	5-minute intervals
10 minutes	10-minute intervals
15 minutes	15-minute intervals
1 hour	Hourly
1 day	Daily
1 week	Weekly
1 month	Monthly
1 year	Yearly

Note: For cURL, URL-encode spaces as %20 (e.g., resample_frequency=1%20hour). The Python client handles this automatically.

resample_function Values

Value	Description
mean	Average (default)
sum	Total
min	Minimum
max	Maximum
count	Count of data points
stddev	Standard deviation
variance	Variance

resample_by

Columns to group by when resampling. By default, groups by time index and subseries index (if present).

cURL Parameter	Python Client Parameter	Type	Description
resample_by	resample_by	comma-separated string or list	Columns to group by

cURL

# Hourly average prices
curl "https://api.gridstatus.io/v1/datasets/ercot_lmp_by_settlement_point/query?filter_column=location&filter_value=HB_HOUSTON&resample_frequency=1%20hour&resample_function=mean&start_time=2026-01-01&end_time=2026-01-02&api_key=YOUR_API_KEY"

# Daily peak load
curl "https://api.gridstatus.io/v1/datasets/ercot_load/query?resample_frequency=1%20day&resample_function=max&start_time=2026-01-01&end_time=2026-01-08&api_key=YOUR_API_KEY"

# Monthly generation totals
curl "https://api.gridstatus.io/v1/datasets/ercot_fuel_mix/query?resample_frequency=1%20month&resample_function=sum&start_time=2026-01-01&end_time=2026-02-01&api_key=YOUR_API_KEY"

Python

import gridstatusio as gs

client = gs.GridStatusClient(api_key="YOUR_API_KEY")

# Hourly average prices
df = client.get_dataset(
    "ercot_lmp_by_settlement_point",
    start="2026-01-01",
    end="2026-01-02",
    filter_column="location",
    filter_value="HB_HOUSTON",
    resample="1 hour",
    resample_function="mean",
)

# Daily peak load
df = client.get_dataset(
    "ercot_load",
    start="2026-01-01",
    end="2026-01-08",
    resample="1 day",
    resample_function="max",
)

# Monthly generation totals
df = client.get_dataset(
    "ercot_fuel_mix",
    start="2026-01-01",
    end="2026-02-01",
    resample="1 month",
    resample_function="sum",
)

Timezone

timezone

Convert timestamps to a specific timezone. Returns both UTC and local columns.

cURL Parameter	Python Client Parameter	Type	Description
timezone	timezone	string	IANA timezone, market, or UTC (default)

Timezone Values

Value	Description
IANA timezone	e.g., America/Chicago, America/New_York
market	Auto-detect from dataset's source ISO
UTC	UTC (default)

Common timezones:

ISO	Timezone
CAISO	US/Pacific
ERCOT, SPP	US/Central
IESO, MISO	EST (year-round)
ISO-NE, NYISO, PJM	US/Eastern

cURL

curl "https://api.gridstatus.io/v1/datasets/ercot_fuel_mix/query?timezone=America/Chicago&start_time=2026-01-01&end_time=2026-01-02&limit=5&api_key=YOUR_API_KEY"

Python

import gridstatusio as gs

client = gs.GridStatusClient(api_key="YOUR_API_KEY")

df = client.get_dataset(
    "ercot_fuel_mix",
    start="2026-01-01",
    end="2026-01-02",
    timezone="America/Chicago",
    limit=5,
)
# DataFrame includes both interval_start_utc and interval_start_local columns

Response adds local time columns:

JSON

{
    "interval_start_local": "2025-12-31T18:00:00-06:00",
    "interval_start_utc": "2026-01-01T00:00:00+00:00"
}

Pagination

The API supports both cursor and offset based pagination. For more, see Pagination documentation.

cURL Parameter	Python Client Parameter	Type	Description
limit	limit	int	Maximum total rows to return across all pages
page_size	page_size	int	Rows per page. Maximum varies by subscription plan
page	(handled internally)	int	Page number for offset-based pagination (starts at 1)
cursor	use_cursor_pagination	string/bool	Cursor for pagination or boolean to enable cursor mode

Note: The Python client handles pagination automatically. Set use_cursor_pagination=True (default) for efficient cursor-based pagination, or False for page-based pagination.

cURL

# First request
curl "https://api.gridstatus.io/v1/datasets/ercot_fuel_mix/query?page_size=1000&start_time=2026-01-01&end_time=2026-01-02&api_key=YOUR_API_KEY"

# Response includes cursor for next page

# Use cursor for subsequent requests
curl "https://api.gridstatus.io/v1/datasets/ercot_fuel_mix/query?cursor=CURSOR_FROM_RESPONSE&api_key=YOUR_API_KEY"

Python

import gridstatusio as gs

client = gs.GridStatusClient(api_key="YOUR_API_KEY")

# Client handles pagination automatically
# Set limit to control total rows returned
df = client.get_dataset(
    "ercot_fuel_mix",
    start="2026-01-01",
    end="2026-01-02",
    limit=1000,  # Maximum rows to return
    page_size=500,  # Rows per API request
    use_cursor_pagination=True,  # Use cursor pagination (default)
)

Sorting

order

cURL Parameter	Python Client Parameter	Value	Description
order	(not available)	asc	Ascending, oldest first (default)
order	(not available)	desc	Descending, newest first

Note: The order parameter is only available via the direct API (cURL). The Python client returns data in ascending order by default. To get the newest data first, you can sort the resulting DataFrame in Python.

cURL

curl "https://api.gridstatus.io/v1/datasets/ercot_fuel_mix/query?order=desc&limit=10&api_key=YOUR_API_KEY"

Python

import gridstatusio as gs

client = gs.GridStatusClient(api_key="YOUR_API_KEY")

# Get data (returns in ascending order)
df = client.get_dataset(
    "ercot_fuel_mix",
    start="2026-01-01",
    end="2026-01-02",
    limit=10,
)

# Sort descending in pandas if needed
df = df.sort_values("interval_start_utc", ascending=False)

Response Format

cURL Parameter	Python Client Parameter	Type	Description
return_format	request_format*	string	Response format: json (default), csv
json_schema	(set automatically)	string	JSON structure
download	(not available)	bool	Return as downloadable file

*Set request_format in the client constructor, not per request.

return_format Values

Value	Description
json	JSON response (default)
csv	CSV response

json_schema Values

Structure of JSON response.

Value	Description
array-of-objects	[{col1: val1, col2: val2}, ...] (default)
array-of-arrays	[[val1, val2], ...] (more compact)

Note: The Python client automatically uses array-of-arrays for efficiency.

download

Set to true to return as downloadable file attachment (cURL only).

cURL

# Download as CSV
curl "https://api.gridstatus.io/v1/datasets/ercot_fuel_mix/query?return_format=csv&start_time=2026-01-01&end_time=2026-01-02&api_key=YOUR_API_KEY" -o data.csv

Python

import gridstatusio as gs

# Set request format in constructor
client = gs.GridStatusClient(
    api_key="YOUR_API_KEY",
    request_format="csv",  # or "json" (default)
)

df = client.get_dataset(
    "ercot_fuel_mix",
    start="2026-01-01",
    end="2026-01-02",
)

# Save to CSV locally
df.to_csv("data.csv", index=False)

Complete Example

Combining multiple parameters:

cURL

curl "https://api.gridstatus.io/v1/datasets/ercot_lmp_by_settlement_point/query?\
start_time=2026-01-01&\
end_time=2026-01-02&\
filter_column=location&\
filter_value=HB_HOUSTON,HB_NORTH&\
filter_operator=in&\
columns=interval_start_utc,location,lmp&\
resample_frequency=1%20hour&\
resample_function=mean&\
timezone=America/Chicago&\
order=desc&\
api_key=YOUR_API_KEY"

Python

import gridstatusio as gs

client = gs.GridStatusClient(api_key="YOUR_API_KEY")

df = client.get_dataset(
    "ercot_lmp_by_settlement_point",
    start="2026-01-01",
    end="2026-01-02",
    filter_column="location",
    filter_value=["HB_HOUSTON", "HB_NORTH"],  # List of values for "in" operator
    filter_operator="in",
    columns=["interval_start_utc", "location", "lmp"],
    resample="1 hour",
    resample_function="mean",
    timezone="America/Chicago",
)

# Sort descending if needed (Python client returns ascending by default)
df = df.sort_values("interval_start_utc", ascending=False)

Parameter Reference Summary

cURL Parameter	Python Client Parameter	Notes
start_time	start	ISO 8601 datetime
end_time	end	ISO 8601 datetime
time	(not available)	Use start/end with limit=1 in Python
time_comparison	(not available)	cURL only
publish_time	publish_time	Same values
publish_time_start	publish_time_start	ISO 8601 datetime
publish_time_end	publish_time_end	ISO 8601 datetime
filter_column	filter_column	Same
filter_value	filter_value	cURL: comma-separated, Python: string/int/list
filter_operator	filter_operator	Same values
columns	columns	cURL: comma-separated, Python: list
resample_frequency	resample	Same values (e.g., "1 hour")
resample_function	resample_function	Same values
resample_by	resample_by	cURL: comma-separated, Python: string/list
timezone	timezone	Same values
limit	limit	Same
page_size	page_size	Same
page	(handled internally)	Python client handles pagination
cursor	use_cursor_pagination	Python: boolean to enable
order	(not available)	Sort DataFrame in Python
return_format	request_format*	Set in constructor
json_schema	(set automatically)	Python client uses array-of-arrays
download	(not available)	Use df.to_csv() in Python