Constraints
Get a list of constraints with optional filtering by ISOs and a search term.
Returns constraints where market_id matches an item in the comma-separated isos list and constraint_name contains the search term. When sort_order is not specified and there is a search term, results are sorted by relevance (shorter constraint_names first). When sort_order is not specified, there is no search term, and include_absolute_costs is false, results are sorted by latest_seen_utc descending (most recently seen first), then market_id ascending, then constraint_name ascending. When include_absolute_costs is true and there is no search term, results are sorted by rt_absolute_cost descending with nulls last.
Use include_absolute_costs, include_timestamps, and include_dataset_metadata to opt into rt_absolute_cost/da_absolute_cost, GS timestamps, and pricing dataset metadata.
When true, include rt_absolute_cost and da_absolute_cost on each constraint. Uses absolute_cost_start_time and absolute_cost_end_time when provided.
falseWhen true, include gs_created_at_utc and gs_updated_at_utc.
falseWhen true, include dataset_metadata with pricing dataset specs.
falseOptional lower bound for the absolute cost window. When set, include rows where time index >= absolute_cost_start_time. Only used when include_absolute_costs is true.
Optional upper bound for the absolute cost window. When set, include rows where time index < absolute_cost_end_time. Only used when include_absolute_costs is true.
API key for authentication (query)
Comma-separated list of market IDs to filter by
Filter latest_seen_utc to be on or after this timestamp
Maximum number of results to return (default: 10000)
10000Sort order: asc or desc. Defaults to desc when omitted.
Optional search term to filter by constraint_name
Column to sort by. Must be one of: constraint_name, market_id, earliest_seen_utc, latest_seen_utc
API key for authentication (header)
Successful Response
Validation Error
GET /v1/constraints HTTP/1.1
Host: api.gridstatus.io
Accept: */*
{
"data": [
{
"gs_entity_id": "text",
"constraint_name": "text",
"market_id": "text",
"earliest_seen_utc": "2026-01-01T00:00:00.000Z",
"latest_seen_utc": "2026-01-01T00:00:00.000Z",
"available_datasets": [
"text"
],
"rt_absolute_cost": 1,
"da_absolute_cost": 1,
"gs_created_at_utc": "2026-01-01T00:00:00.000Z",
"gs_updated_at_utc": "2026-01-01T00:00:00.000Z"
}
],
"dataset_metadata": {
"ANY_ADDITIONAL_PROPERTY": {
"ANY_ADDITIONAL_PROPERTY": [
{
"dataset_id": "text",
"shadow_price_column": "text"
}
]
}
}
}Get a list of contingencies with optional filtering by ISOs and a search term.
Returns all rows and columns from the contingencies table where market_id matches an item in the comma-separated isos list and contingency_name contains the search term. When sort_order is not specified and there is a search term, results are sorted by relevance (shorter contingency_names first). When sort_order is not specified and there is no search term, results are sorted by latest_seen_utc descending (most recently seen first), then market_id ascending, then contingency_name ascending for consistent ordering.
Args: params: Query parameters (isos, search, active_after, limit, sort_column, sort_order)
API key for authentication (query)
Comma-separated list of market IDs to filter by
Filter latest_seen_utc to be on or after this timestamp
Maximum number of results to return (default: 10000)
10000Sort order: asc or desc. Defaults to desc when omitted.
Optional search term to filter by contingency_name
Column to sort by. Must be one of: contingency_name, market_id, earliest_seen_utc, latest_seen_utc
API key for authentication (header)
Successful Response
Validation Error
GET /v1/constraints/contingencies HTTP/1.1
Host: api.gridstatus.io
Accept: */*
[
{
"gs_entity_id": "text",
"contingency_name": "text",
"market_id": "text",
"earliest_seen_utc": "2026-01-01T00:00:00.000Z",
"latest_seen_utc": "2026-01-01T00:00:00.000Z",
"available_datasets": [
"text"
],
"gs_created_at_utc": "2026-01-01T00:00:00.000Z",
"gs_updated_at_utc": "2026-01-01T00:00:00.000Z"
}
]Retrieve estimated shift factors for a pricing location.
Queries ClickHouse linear_estimated_shift_factors for the given location, returning one row per constraint_gs_entity_id. When multiple source rows share the same constraint, estimated_shift_factor is aggregated per aggregation_function (mean, max, min, or median). Optional contingency_id restricts rows to a single contingency. Optional dataset_id filters on source_dataset. When exclude_zeros is true, source rows with estimated_shift_factor equal to zero are dropped before aggregating per constraint.
API key for authentication (query)
When set, only include rows with this contingency_gs_entity_id
When set, only include rows with this source_dataset
When true, exclude rows where estimated_shift_factor is zero before aggregating each group
falseFunction used to combine source rows in each group: mean, max, min, or median
meanPossible values: API key for authentication (header)
Successful Response
Linear estimated shift factor aggregated per constraint for a location.
Validation Error
GET /v1/constraints/locations/{location_gs_entity_id}/shift-factors HTTP/1.1
Host: api.gridstatus.io
Accept: */*
[
{
"constraint_gs_entity_id": "text",
"estimated_shift_factor": 1,
"constraint": "text"
}
]Get location-adjusted constraint costs over a time range.
The endpoint computes absolute cost per constraint/contingency pair from the specified constraint dataset in ClickHouse, then multiplies each by the location's aggregated shift factor (mean) from linear_estimated_shift_factors for the same dataset. For datasets without contingency_gs_entity_id, costs are computed per constraint and reused across that constraint's shift-factor contingency rows.
Pass group_by=constraint to roll contingency-grained rows up to one row per constraint (sum of adjusted_cost, mean shift_factor; contingency fields are null). absolute_cost is summed when the dataset has a contingency column; otherwise the shared per-constraint cost is kept once.
Filter to rows where time index >= start_time (ISO 8601)
Filter to rows where time index < end_time (ISO 8601)
Row grain. constraint_contingency (default) returns one row per constraint/contingency pair. constraint rolls those rows up to one row per constraint (sum of adjusted_cost, mean shift factor; absolute_cost summed only when the dataset has a contingency column).
constraint_contingencyPossible values: API key for authentication (query)
API key for authentication (header)
Successful Response
Constraint costs adjusted by a location's shift factor.
Default grain is constraint + contingency. When the endpoint is called with
group_by=constraint, contingency fields are null and costs/shift factors
are rolled up across contingencies for each constraint. adjusted_cost is
always summed; absolute_cost is summed only when the underlying dataset has
a contingency column (otherwise the shared per-constraint cost is kept once).
Validation Error
GET /v1/constraints/locations/{location_gs_entity_id}/constraint-costs?dataset_id=text&start_time=2026-01-01T00%3A00%3A00.000Z&end_time=2026-01-01T00%3A00%3A00.000Z HTTP/1.1
Host: api.gridstatus.io
Accept: */*
[
{
"constraint_gs_entity_id": "text",
"constraint_name": "text",
"contingency_gs_entity_id": "text",
"contingency_name": "text",
"shift_factor": 1,
"absolute_cost": 1,
"adjusted_cost": 1
}
]Retrieve estimated shift factors for a constraint.
Queries ClickHouse linear_estimated_shift_factors for the given constraint, returning one row per location_gs_entity_id. When multiple source rows share the same location, estimated_shift_factor is aggregated per aggregation_function (mean, max, min, or median). Optional contingency_id restricts rows to a single contingency. Optional dataset_id filters on source_dataset. When exclude_zeros is true, source rows with estimated_shift_factor equal to zero are dropped before aggregating per location.
GS entity ID of the constraint to get shift factors for
API key for authentication (query)
When set, only include rows with this contingency_gs_entity_id
When set, only include rows with this source_dataset
When true, exclude rows where estimated_shift_factor is zero before aggregating each group
falseFunction used to combine source rows in each group: mean, max, min, or median
meanPossible values: API key for authentication (header)
Successful Response
Linear estimated shift factor aggregated per location for a constraint.
Validation Error
GET /v1/constraints/{constraint_id}/shift-factors HTTP/1.1
Host: api.gridstatus.io
Accept: */*
[
{
"location_gs_entity_id": "text",
"estimated_shift_factor": 1,
"location": "text"
}
]Retrieve start/end substation coordinates for a constraint.
Returns nullable start and end lat/lon from the market's constraint geometry table. Markets without a geometry table return 400. Unknown constraint ids return 404.
GS entity ID of the constraint to get facility location for
API key for authentication (query)
API key for authentication (header)
Successful Response
Start/end substation coordinates for a constraint.
Either endpoint may be null when that constraint has no mapped coords. Markets without a geometry table are rejected by the endpoint (400).
Validation Error
GET /v1/constraints/{constraint_id}/location HTTP/1.1
Host: api.gridstatus.io
Accept: */*
{
"constraint_gs_entity_id": "text",
"constraint_name": "text",
"start": {
"latitude": 1,
"longitude": 1,
"name": "text"
},
"end": {
"latitude": 1,
"longitude": 1,
"name": "text"
}
}Get binding rows for a dataset with constraint display names.
Maximum number of rows to return.
50000API key for authentication (query)
Filter to rows where time index >= start_time (ISO 8601)
Filter to rows where time index < end_time (ISO 8601 timestamp)
Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold.
API key for authentication (header)
Successful Response
Validation Error
GET /v1/constraints/binding?dataset_id=text HTTP/1.1
Host: api.gridstatus.io
Accept: */*
[
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
]Get unique binding constraints for a dataset/time window with locations.
Scans binding observations for dataset_id in [start_time, end_time), collapses peak-|shadow| per (constraint, interval), keeps the top limit constraints by peak |shadow|, joins facility coordinates and contingency identity/names, and returns one object per constraint with nested observations, ordered by that ranking.
Maximum number of unique binding constraints to return (all intervals for each are included).
50000API key for authentication (query)
Filter to rows where time index >= start_time (ISO 8601)
Filter to rows where time index < end_time (ISO 8601 timestamp)
API key for authentication (header)
Successful Response
Binding constraints for a dataset/time window, merged with substations.
Validation Error
GET /v1/constraints/binding/locations?dataset_id=text&start_time=2026-01-01T00%3A00%3A00.000Z&end_time=2026-01-01T00%3A00%3A00.000Z HTTP/1.1
Host: api.gridstatus.io
Accept: */*
{
"constraints": [
{
"constraint_gs_entity_id": "text",
"constraint_name": "text",
"start": {
"latitude": 1,
"longitude": 1,
"name": "text"
},
"end": {
"latitude": 1,
"longitude": 1,
"name": "text"
},
"observations": [
{
"interval_start_utc": "2026-01-01T00:00:00.000Z",
"shadow_price": 1,
"contingency_gs_entity_id": "text",
"contingency_name": "text"
}
]
}
]
}Get filtered binding interval counts grouped by hour-of-day.
GS entity ID of the constraint to query
API key for authentication (query)
Optional IANA timezone (e.g. America/New_York). When provided, buckets are computed in this timezone.
Filter to rows where time index >= start_time (ISO 8601)
Filter to rows where time index < end_time (ISO 8601)
Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold.
Optional contingency GS entity ID filter.
API key for authentication (header)
Successful Response
Count of filtered binding rows by local hour (requested timezone or UTC).
Validation Error
GET /v1/constraints/{constraint_id}/binding_intervals_by_hour?dataset_id=text HTTP/1.1
Host: api.gridstatus.io
Accept: */*
[
{
"hour": 1,
"count": 1
}
]Get per-interval count, shadow-price summary stats, and absolute cost.
GS entity ID of the constraint to query
Aggregation bucket size. One of "hour", "day", "month", "year".
API key for authentication (query)
Optional IANA timezone (e.g. America/New_York). When provided, buckets are computed in this timezone.
Filter to rows where time index >= start_time (ISO 8601)
Filter to rows where time index < end_time (ISO 8601)
Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold.
Optional contingency GS entity ID filter.
API key for authentication (header)
Successful Response
Per-interval aggregate stats for filtered constraint rows.
Validation Error
GET /v1/constraints/{constraint_id}/stats?aggregation_period=hour&dataset_id=text HTTP/1.1
Host: api.gridstatus.io
Accept: */*
[
{
"interval_start_utc": "2026-01-01T00:00:00.000Z",
"binding_intervals": 1,
"shadow_price_min": 1,
"shadow_price_mean": 1,
"shadow_price_median": 1,
"shadow_price_max": 1,
"absolute_cost": 1
}
]Summarize unique binding constraints per UTC period for a dataset.
UTC aggregation period for grouping counts. Supported values: hour, day, month, year.
hourPossible values: API key for authentication (query)
Filter to rows where time index >= start_time (ISO 8601)
Filter to rows where time index < end_time (ISO 8601 timestamp)
Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold.
API key for authentication (header)
Successful Response
Count of unique binding constraints for a single UTC aggregation period.
Validation Error
GET /v1/constraints/binding/counts?dataset_id=text HTTP/1.1
Host: api.gridstatus.io
Accept: */*
[
{
"period_start_utc": "2026-01-01T00:00:00.000Z",
"binding_constraint_count": 1,
"binding_constraint_ids": [
"text"
]
}
]Summarize absolute binding cost per UTC period for a dataset.
UTC aggregation period for grouping absolute costs. Supported values: hour, day, month, year.
hourPossible values: API key for authentication (query)
Filter to rows where time index >= start_time (ISO 8601)
Filter to rows where time index < end_time (ISO 8601 timestamp)
Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold.
API key for authentication (header)
Successful Response
Absolute binding cost for a single UTC aggregation period.
Validation Error
GET /v1/constraints/binding/absolute-costs?dataset_id=text HTTP/1.1
Host: api.gridstatus.io
Accept: */*
[
{
"period_start_utc": "2026-01-01T00:00:00.000Z",
"absolute_cost": 1
}
]Return absolute costs and shadow-price aggregates by bucket and constraint.
API key for authentication (query)
Filter to rows where time index >= start_time (ISO 8601)
Filter to rows where time index < end_time (ISO 8601 timestamp)
Optional IANA timezone used for daily bucket boundaries. Defaults to the dataset market timezone.
Bucket resolution. Raw preserves the native interval; hourly and daily use explicit buckets. Auto derives resolution from the native interval and selected range. Explicit modes that exceed the range limit resolve to the nearest available mode.
autoPossible values: Group rows by constraint and contingency by default, or by constraint only.
constraint_contingencyPossible values: Optional comma-separated market-local days of the week, where Monday is 1 and Sunday is 7. An empty value matches no rows.
Optional comma-separated market-local hour starts from 0 through 23. An empty value matches no rows.
API key for authentication (header)
Successful Response
Validation Error
GET /v1/constraints/binding/heat_map?dataset_id=text&start_time=2026-01-01T00%3A00%3A00.000Z&end_time=2026-01-01T00%3A00%3A00.000Z HTTP/1.1
Host: api.gridstatus.io
Accept: */*
{
"timezone": "text",
"group_by": "constraint",
"supports_contingency_grouping": true,
"constraint_names": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"contingency_names": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"native_interval_minutes": 1,
"interval_minutes": 1,
"bucket_mode": "raw",
"available_bucket_modes": [
"raw"
],
"cells": [
{
"absolute_cost": 1,
"peak_shadow_price": 1,
"mean_shadow_price": 1,
"binding_interval_count": 1,
"bucket_start_utc": "2026-01-01T00:00:00.000Z",
"interval_start_utc": "2026-01-01T00:00:00.000Z",
"constraint_gs_entity_id": "text",
"contingency_gs_entity_id": "text"
}
],
"row_summaries": [
{
"constraint_gs_entity_id": "text",
"contingency_gs_entity_id": "text",
"metrics": {
"absolute_cost": 1,
"peak_shadow_price": 1,
"mean_shadow_price": 1,
"binding_interval_count": 1
}
}
],
"unsupported_reason": null
}Get data for a specific constraint by its GS entity ID.
GS entity ID of the constraint to query
API key for authentication (query)
API key for authentication (header)
Successful Response
Validation Error
GET /v1/constraints/{gs_entity_id} HTTP/1.1
Host: api.gridstatus.io
Accept: */*
{
"gs_entity_id": "text",
"constraint_name": "text",
"market_id": "text",
"earliest_seen_utc": "2026-01-01T00:00:00.000Z",
"latest_seen_utc": "2026-01-01T00:00:00.000Z",
"available_datasets": [
"text"
],
"rt_absolute_cost": 1,
"da_absolute_cost": 1,
"gs_created_at_utc": "2026-01-01T00:00:00.000Z",
"gs_updated_at_utc": "2026-01-01T00:00:00.000Z"
}Year/month/day-level statistics on binding intervals in ISO local time.
GS entity ID of the constraint to query
Optional contingency GS entity ID filter. Applied only when the dataset contains contingency_gs_entity_id.
API key for authentication (query)
API key for authentication (header)
Successful Response
Year/month/day-level statistics for constraint binding intervals.
Year: months with data and count in each. Month: days with data and count in each. Day: times (HH:MM:SS strings) for unique timestamps on that day.
Validation Error
GET /v1/constraints/{constraint_id}/intervals?dataset_id=text HTTP/1.1
Host: api.gridstatus.io
Accept: */*
[
{
"year": 1,
"count": 1,
"months": [
{
"month": 1,
"count": 1,
"days": [
{
"day": 1,
"count": 1,
"times": [
"text"
]
}
]
}
]
}
]Contingencies binding for a constraint in a dataset/time window.
Constraint GS entity ID to filter by (constraint_gs_entity_id)
When true, include binding_intervals and absolute_cost and apply start_time/end_time/time filters. Default returns id and name only.
falseStart time (ISO timestamp) for filtering (inclusive). Requires time index column. Only used when include_binding_stats is true.
End time (ISO timestamp) for filtering (exclusive). Requires time index column. Only used when include_binding_stats is true.
Optional specific timestamp to filter results. Cannot be used with start_time or end_time. Only used when include_binding_stats is true.
API key for authentication (query)
API key for authentication (header)
Successful Response
Contingency with id, name, and optional binding stats.
Validation Error
GET /v1/constraints/{constraint_id}/contingencies?dataset_id=text HTTP/1.1
Host: api.gridstatus.io
Accept: */*
[
{
"id": "text",
"name": "text",
"binding_intervals": 1,
"absolute_cost": 1
}
]Last updated
Was this helpful?