GridStatus.io Hosted API

• Python client for accessing the GridStatus.io Hosted API.
• Browse all available datasets in our Data Catalog.

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

• Sign up for a Grid Status account and get your API key from the Settings page
• Set your API key as an environment variable: export GRIDSTATUS_API_KEY=your_api_key or pass to the client with client = GridStatusClient(api_key="<your_api_key>")
• You're now ready to start querying. List datasets with:

from gridstatusio import GridStatusClient
client = GridStatusClient()

data = client.get_dataset('ercot_fuel_mix', limit=100, start='2025-01-01', end='2025-01-02')

• To see all available datasets, use client.list_datasets() or check out the complete Grid Status catalog at https://www.gridstatus.io/datasets

• To get metadata for a single dataset (description, available time range, columns, and more), use client.get_dataset_metadata(dataset_id). 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", ...}, ...],
#     ...
# }

• NOTE: the Grid Status API has a 500,000 rows per month limit on the free plan. This limit is very easy to exceed when querying data, especially real time prices.

  • Make sure to add limit to all of your get_dataset calls to avoid quickly exceeding the limit.

• For more detailed examples, check out this notebook: Getting Started

• Other notebooks in the Examples directory:

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

Return Formats

The client supports three return formats for data: pandas DataFrames, polars DataFrames, and Python objects (list of dictionaries). You can specify the format at the client level or per-call.

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

Format Options

Default Behavior

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

Example: Python Format

from gridstatusio import GridStatusClient

client = GridStatusClient(return_format="python")
data = client.get_dataset('ercot_fuel_mix', limit=5)

# Returns a list of dictionaries
# [
#     {"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, ...},
#     ...
# ]

Example: Polars Format

from gridstatusio import GridStatusClient

client = GridStatusClient(return_format="polars")
df = client.get_dataset('ercot_fuel_mix', limit=100)

# Returns a polars DataFrame
print(type(df))  # <class 'polars.dataframe.frame.DataFrame'>

Using Without Pandas (Advanced)

While pandas is a required dependency, the library uses lazy loading so pandas is only imported when actually needed. This allows advanced users to use the library without pandas in minimal environments:

# Install without dependencies (advanced usage only)
uv pip install gridstatusio --no-deps

# Then manually install only the required non-pandas dependencies
uv pip install requests termcolor tabulate

When using the library without pandas:

from gridstatusio import GridStatusClient

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

# Returns list of dicts - no pandas required

Note: If you don't specify return_format="python", the client will attempt to use pandas and raise an error if it's not installed.

Checking your API usage

usage = client.get_api_usage()

• This shows the limits for your API key, the start and end of the current usage period, and the API usage in the current period. Note a limit of -1 means no limit.

Retry Configuration

• The Grid Status API has rate limits that restrict the number of requests that are allowed each second, minute and hour. If rate limits are hit the client will automatically retry the request after a delay. You can configure the maximum number of retries using the max_retries parameter when initializing the client. If you find yourself hitting rate limits, you may need to add a delay between your requests. The Grid Status Pricing Page contains more details on specific rate limits.
• The client retries failed requests due to rate limits (429), server errors (5xx), and network issues using exponential backoff. You can customize retry behavior:

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

The retry delay follows the formula delay = base_delay * (exponential_base ** retry_count).

Retries are useful when:

• You're making pagination-heavy requests and risk hitting short-term rate limits
• A request fails due to a temporary server error
• A network issue or timeout interrupts the request

To disable retries entirely, set max_retries=0.

Version Check

The client checks for updates to the library when it is imported. It does this by making a call to the library on PyPI. For certain applications, this call can be problematic, and can be disabled by setting the environment variable GSIO_SKIP_VERSION_CHECK to true.

export GSIO_SKIP_VERSION_CHECK=true

Open Source

If you prefer to use an open source library that fetches data directly from the source, you can check out this github repo.

Get Help

We'd love to answer any usage or data access questions! Please let us know by emailing us at contact@gridstatus.io