GridStatus.io Hosted API — Python Client

gridstatusio is a Python client for the GridStatus.io Hosted API, which provides historical and real-time electricity market data from North American ISOs through a single REST API.

Available datasets cover load and demand, fuel and generation mix, forecasts, locational marginal prices (LMPs), interchange, ancillary services, and more. Browse 500+ datasets in the Data Catalog.

Contents

• Why the hosted API?
• Installation
• Getting started
• Return formats
• API usage
• More examples

Why the hosted API?

The hosted API differs from the open-source gridstatus library in several ways:

Use the open-source library when you want raw data directly from the ISOs with no account. We recommend this client when you want normalized, hosted data through a single API.

Installation

gridstatusio supports Python 3.10+. Install with uv or pip.

# Standard installation (includes pandas)
uv pip install gridstatusio

# With polars support (for polars DataFrames)
uv pip install gridstatusio[polars]

# With notebook support (for running example notebooks)
uv pip install gridstatusio[notebooks]

# With all optional dependencies
uv pip install gridstatusio[all]

Getting started

1. Get an API key. Sign up for a Grid Status account and copy your key from the Settings page.
2. Provide the key. Set export GRIDSTATUS_API_KEY=your_api_key, or pass it directly: GridStatusClient(api_key="<your_api_key>").
3. Find a dataset. Call client.list_datasets() or browse the Data Catalog.
4. Query the dataset. Call client.get_dataset(...) with the dataset ID and desired time range.

from gridstatusio import GridStatusClient

client = GridStatusClient()  # reads GRIDSTATUS_API_KEY from the environment

client.list_datasets()

df = client.get_dataset(
    "ercot_fuel_mix",
    start="2024-06-01",
    end="2024-06-02",
    limit=1000,
)

Dataset metadata

Use client.get_dataset_metadata(dataset_id) to get a dataset's description, available time range, columns, and more. It always returns a dictionary, with timestamp fields parsed into timezone-aware datetimes:

metadata = client.get_dataset_metadata("ercot_fuel_mix")

# {
#     "id": "ercot_fuel_mix",
#     "name": "ERCOT Fuel Mix",
#     "earliest_available_time_utc": datetime(2017, 1, 1, 6, 0, tzinfo=timezone.utc),
#     "all_columns": [{"name": "interval_start_utc", ...}, ...],
#     ...
# }

Return formats

get_dataset(...) supports pandas, polars, or Python objects. Set the return format at the client level or per-call. Dataset metadata is always returned as a dictionary.

from gridstatusio import GridStatusClient

# Set default format when creating the client
client = GridStatusClient(return_format="pandas")  # or "polars" or "python"

# Override format for a specific call
data = client.get_dataset("ercot_fuel_mix", limit=100, return_format="python")

If return_format is not specified, the client returns pandas DataFrames by default.

# Python format → list of dicts:
# [
#     {"interval_start_utc": "2025-01-01T00:00:00+00:00", "coal": 1234.5, ...},
#     {"interval_start_utc": "2025-01-01T00:05:00+00:00", "coal": 1235.2, ...},
# ]

Using without pandas (advanced)

Pandas is installed by default, but the library uses lazy loading so it's only imported when needed. In minimal environments, you can install without dependencies and use return_format="python" to avoid pandas entirely:

uv pip install gridstatusio --no-deps
uv pip install requests termcolor tabulate

from gridstatusio import GridStatusClient

# Must explicitly set return_format="python" to avoid the pandas import
client = GridStatusClient(api_key="your_key", return_format="python")
data = client.get_dataset("ercot_fuel_mix", limit=100)

If you don't set return_format="python", the client attempts to use pandas and raises an error if it isn't installed.

Checking your API usage

usage = client.get_api_usage()

Shows the limits for your API key, the start/end of the current usage period, and usage in the current period. A limit of -1 means no limit.

The free plan allows 500,000 rows per month. You can view detailed usage stats in Settings.

Retry configuration

The API enforces per-second/minute/hour rate limits. The client retries rate limits (429), server errors (5xx), and network issues with exponential backoff. See the Pricing Page for specific limits.

client = GridStatusClient(
    max_retries=3,        # Maximum retries (default: 5)
    base_delay=1.0,       # Base delay in seconds (default: 2.0)
    exponential_base=1.5, # Exponential backoff multiplier (default: 2.0)
)

Set max_retries=0 to disable retries.

Version check

The client checks PyPI for library updates on import. To disable this (e.g. in restricted environments), set:

export GSIO_SKIP_VERSION_CHECK=true

More examples

• Getting Started
• Finding Hubs and Zones in Pricing Data
• ERCOT Pricing Data
• CAISO April Net Load Analysis
• Stacked Net Load Visualization
• Resample Data to Different Frequencies

Resources

• OpenAPI spec
• LLMs manifest
• Docs assistant

Get help

For usage or data-access questions, email contact@gridstatus.io.