Utility Endpoints

Additional endpoints for metadata, monitoring, and discovery.

API Usage

GET /v1/api_usage

Monitor your consumption against subscription limits.

Response Fields:

Field	Description
plan_name	Your subscription plan
limits.api_rows_returned_limit	Max rows per billing period
limits.api_rows_per_response_limit	Max rows per response
current_period_usage.total_api_rows_returned	Rows used this period
current_period_usage.total_requests	Requests made this period

Example:

Shell

curl "https://api.gridstatus.io/v1/api_usage?api_key=YOUR_API_KEY"

Python

---

Dataset Metadata

GET /v1/datasets/{dataset_id}

Get schema and availability information for a dataset.

Response Fields:

Field	Description
id	Dataset identifier
name	Human-readable name
earliest_available_time_utc	Start of data availability
latest_available_time_utc	Most recent data timestamp
time_index_column	Primary time column name
all_columns	List of columns with types
data_frequency	Update interval (e.g., "5_MINUTES")

Example:

Shell

curl "https://api.gridstatus.io/v1/datasets/ercot_fuel_mix?api_key=YOUR_API_KEY"

Python

---

Column Values

GET /v1/datasets/{dataset_id}/columns/{column}

Get unique values in a column. Useful for discovering filter options.

Example:

Shell

curl "https://api.gridstatus.io/v1/datasets/ercot_lmp_by_settlement_point/columns/location?api_key=YOUR_API_KEY"

Python

Response:

{
    "column": "location",
    "type": "VARCHAR",
    "unique_values": ["HB_HOUSTON", "HB_NORTH", "HB_SOUTH", "HB_WEST", ...]
}

Results are based on the most recent 50,000 rows. Older values may not appear.

---

Dataset Updates

GET /v1/dataset-updates/{dataset_id}

Track update history to monitor data freshness.

Query Parameters:

Parameter	Default	Description
limit	None	Max records to return
order	asc	Sort: asc or desc

Example:

Shell

curl "https://api.gridstatus.io/v1/dataset-updates/ercot_fuel_mix?order=desc&limit=5&api_key=YOUR_API_KEY"

Python

Response Fields:

Field	Description
time_utc	When the update occurred
num_rows_inserted	New rows added
num_rows_updated	Existing rows modified
is_backfill	Whether this was historical backfill

---

Error Codes

Code	Description
401	Missing or invalid API key
403	Dataset requires paid subscription
404	Dataset or column not found
429	Rate limit exceeded