Constraints

List Constraints

get

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_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_costs is true and there is no search term, results are sorted by rt_cost descending with nulls last.

Use include_costs, include_timestamps, and include_dataset_metadata to opt into rt_cost/da_cost, GS timestamps, and pricing dataset metadata.

Query parameters

include_costsbooleanOptional

When true, include rt_cost and da_cost on each constraint. Uses cost_start_time and cost_end_time when provided.

Default: false

include_timestampsbooleanOptional

When true, include gs_created_at_utc and gs_updated_at_utc.

Default: false

include_dataset_metadatabooleanOptional

When true, include dataset_metadata with pricing dataset specs.

Default: false

cost_start_timestring · date-time · nullableOptional

Optional lower bound for the cost window. When set, include rows where time index >= cost_start_time. Only used when include_costs is true.

cost_end_timestring · date-time · nullableOptional

Optional upper bound for the cost window. When set, include rows where time index < cost_end_time. Only used when include_costs is true.

api_keystring · nullableOptional

API key for authentication (query)

isosstring · nullableOptional

Comma-separated list of market IDs to filter by

active_afterstring · date-time · nullableOptional

Filter latest_seen_utc to be on or after this timestamp

limitinteger · max: 100000 · nullableOptional

Maximum number of results to return (default: 10000)

Default: 10000

sort_orderstring · enum · nullableOptional

Sort order: asc or desc. Defaults to desc when omitted.

Possible values:

searchstring · nullableOptional

Optional search term to filter by constraint_name

sort_columnstring · enum · nullableOptional

Column to sort by. Must be one of: constraint_name, market_id, earliest_seen_utc, latest_seen_utc

Possible values:

Header parameters

x-api-keystring · nullableOptional

API key for authentication (header)

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get/constraints

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-07-20T13:50:40.809Z",
      "latest_seen_utc": "2026-07-20T13:50:40.809Z",
      "available_datasets": [
        "text"
      ],
      "rt_cost": 1,
      "da_cost": 1,
      "gs_created_at_utc": "2026-07-20T13:50:40.809Z",
      "gs_updated_at_utc": "2026-07-20T13:50:40.809Z"
    }
  ],
  "dataset_metadata": {
    "ANY_ADDITIONAL_PROPERTY": {
      "ANY_ADDITIONAL_PROPERTY": [
        {
          "dataset_id": "text",
          "shadow_price_column": "text"
        }
      ]
    }
  }
}

List Contingencies

get

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)

Query parameters

api_keystring · nullableOptional

API key for authentication (query)

isosstring · nullableOptional

Comma-separated list of market IDs to filter by

active_afterstring · date-time · nullableOptional

Filter latest_seen_utc to be on or after this timestamp

limitinteger · max: 100000 · nullableOptional

Maximum number of results to return (default: 10000)

Default: 10000

sort_orderstring · enum · nullableOptional

Sort order: asc or desc. Defaults to desc when omitted.

Possible values:

searchstring · nullableOptional

Optional search term to filter by contingency_name

sort_columnstring · enum · nullableOptional

Column to sort by. Must be one of: contingency_name, market_id, earliest_seen_utc, latest_seen_utc

Possible values:

Header parameters

x-api-keystring · nullableOptional

API key for authentication (header)

Responses

200

Successful Response

application/json

gs_entity_idstringRequired

contingency_namestringRequired

market_idstring · nullableRequired

earliest_seen_utcstring · date-time · nullableRequired

latest_seen_utcstring · date-time · nullableRequired

available_datasetsstring[] · nullableRequired

gs_created_at_utcstring · date-timeRequired

gs_updated_at_utcstring · date-timeRequired

422

Validation Error

application/json

get/constraints/contingencies

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-07-20T13:50:40.809Z",
    "latest_seen_utc": "2026-07-20T13:50:40.809Z",
    "available_datasets": [
      "text"
    ],
    "gs_created_at_utc": "2026-07-20T13:50:40.809Z",
    "gs_updated_at_utc": "2026-07-20T13:50:40.809Z"
  }
]

List Shift Factors For Location

get

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.

Path parameters

location_gs_entity_idstringRequired

Query parameters

api_keystring · nullableOptional

API key for authentication (query)

contingency_idstring · nullableOptional

When set, only include rows with this contingency_gs_entity_id

dataset_idstring · nullableOptional

When set, only include rows with this source_dataset

exclude_zerosbooleanOptional

When true, exclude rows where estimated_shift_factor is zero before aggregating each group

Default: false

aggregation_functionstring · enumOptional

Function used to combine source rows in each group: mean, max, min, or median

Default: meanPossible values:

Header parameters

x-api-keystring · nullableOptional

API key for authentication (header)

Responses

200

Successful Response

application/json

Linear estimated shift factor aggregated per constraint for a location.

constraint_gs_entity_idstringRequired

estimated_shift_factornumberRequired

constraintstringRequired

422

Validation Error

application/json

get/constraints/locations/{location_gs_entity_id}/shift-factors

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"
  }
]

List Constraint Costs For Location

get

Get location-adjusted constraint costs over a time range.

The endpoint computes total 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.

Path parameters

location_gs_entity_idstringRequired

Query parameters

dataset_idstringRequired

start_timestring · date-timeRequired

Filter to rows where time index >= start_time (ISO 8601)

end_timestring · date-timeRequired

Filter to rows where time index < end_time (ISO 8601)

api_keystring · nullableOptional

API key for authentication (query)

Header parameters

x-api-keystring · nullableOptional

API key for authentication (header)

Responses

200

Successful Response

application/json

Constraint contingency costs adjusted by a location's shift factor.

constraint_gs_entity_idstringRequired

constraint_namestringRequired

contingency_gs_entity_idstring · nullableRequired

contingency_namestring · nullableRequired

shift_factornumberRequired

total_costnumber · nullableRequired

adjusted_costnumber · nullableRequired

422

Validation Error

application/json

get/constraints/locations/{location_gs_entity_id}/constraint-costs

GET /v1/constraints/locations/{location_gs_entity_id}/constraint-costs?dataset_id=text&start_time=2026-07-20T13%3A50%3A40.809Z&end_time=2026-07-20T13%3A50%3A40.809Z 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,
    "total_cost": 1,
    "adjusted_cost": 1
  }
]

List Constraint Impact For Location

get

Get per-constraint impact from abs(median shadow price) and shift factors.

Path parameters

location_gs_entity_idstringRequired

Query parameters

dataset_idstringRequired

start_timestring · date-timeRequired

Filter to rows where time index >= start_time (ISO 8601)

end_timestring · date-timeRequired

Filter to rows where time index < end_time (ISO 8601)

api_keystring · nullableOptional

API key for authentication (query)

Header parameters

x-api-keystring · nullableOptional

API key for authentication (header)

Responses

200

Successful Response

application/json

Per-constraint impact at a location from median shadow price and shift factor.

constraint_gs_entity_idstringRequired

constraint_namestringRequired

absolute_median_shadow_pricenumberRequired

average_shift_factornumberRequired

price_impactnumberRequired

422

Validation Error

application/json

get/constraints/locations/{location_gs_entity_id}/constraint-impact

GET /v1/constraints/locations/{location_gs_entity_id}/constraint-impact?dataset_id=text&start_time=2026-07-20T13%3A50%3A40.809Z&end_time=2026-07-20T13%3A50%3A40.809Z HTTP/1.1
Host: api.gridstatus.io
Accept: */*

[
  {
    "constraint_gs_entity_id": "text",
    "constraint_name": "text",
    "absolute_median_shadow_price": 1,
    "average_shift_factor": 1,
    "price_impact": 1
  }
]

List Shift Factors

get

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.

Path parameters

constraint_idstringRequired

GS entity ID of the constraint to get shift factors for

Query parameters

api_keystring · nullableOptional

API key for authentication (query)

contingency_idstring · nullableOptional

When set, only include rows with this contingency_gs_entity_id

dataset_idstring · nullableOptional

When set, only include rows with this source_dataset

exclude_zerosbooleanOptional

When true, exclude rows where estimated_shift_factor is zero before aggregating each group

Default: false

aggregation_functionstring · enumOptional

Function used to combine source rows in each group: mean, max, min, or median

Default: meanPossible values:

Header parameters

x-api-keystring · nullableOptional

API key for authentication (header)

Responses

200

Successful Response

application/json

Linear estimated shift factor aggregated per location for a constraint.

location_gs_entity_idstringRequired

estimated_shift_factornumberRequired

locationstringRequired

422

Validation Error

application/json

get/constraints/{constraint_id}/shift-factors

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"
  }
]

List Constraint Binding Rows

get

Get binding rows for a dataset with constraint display names.

Query parameters

limitinteger · min: 1 · max: 100000Optional

Maximum number of rows to return.

Default: 50000

api_keystring · nullableOptional

API key for authentication (query)

dataset_idstringRequired

start_timestring · date-time · nullableOptional

Filter to rows where time index >= start_time (ISO 8601)

end_timestring · date-time · nullableOptional

Filter to rows where time index < end_time (ISO 8601 timestamp)

price_thresholdnumber · nullableOptional

Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold.

Header parameters

x-api-keystring · nullableOptional

API key for authentication (header)

Responses

200

Successful Response

application/json

Other propertiesanyOptional

422

Validation Error

application/json

get/constraints/binding

GET /v1/constraints/binding?dataset_id=text HTTP/1.1
Host: api.gridstatus.io
Accept: */*

[
  {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
]

List Constraint Binding Intervals By Hour

get

Get filtered binding interval counts grouped by hour-of-day.

Path parameters

constraint_idstringRequired

GS entity ID of the constraint to query

Query parameters

api_keystring · nullableOptional

API key for authentication (query)

dataset_idstringRequired

timezonestring · nullableOptional

Optional IANA timezone (e.g. America/New_York). When provided, buckets are computed in this timezone.

start_timestring · date-time · nullableOptional

Filter to rows where time index >= start_time (ISO 8601)

end_timestring · date-time · nullableOptional

Filter to rows where time index < end_time (ISO 8601)

price_thresholdnumber · nullableOptional

Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold.

contingency_idstring · nullableOptional

Optional contingency GS entity ID filter.

Header parameters

x-api-keystring · nullableOptional

API key for authentication (header)

Responses

200

Successful Response

application/json

Count of filtered binding rows by local hour (requested timezone or UTC).

hourintegerRequired

countintegerRequired

422

Validation Error

application/json

get/constraints/{constraint_id}/binding_intervals_by_hour

GET /v1/constraints/{constraint_id}/binding_intervals_by_hour?dataset_id=text HTTP/1.1
Host: api.gridstatus.io
Accept: */*

[
  {
    "hour": 1,
    "count": 1
  }
]

List Constraint Stats By Interval

get

Get per-interval count, shadow-price summary stats, and total cost.

Path parameters

constraint_idstringRequired

GS entity ID of the constraint to query

Query parameters

aggregation_periodstring · enumRequired

Aggregation bucket size. One of "hour", "day", "month", "year".

Possible values:

api_keystring · nullableOptional

API key for authentication (query)

dataset_idstringRequired

timezonestring · nullableOptional

Optional IANA timezone (e.g. America/New_York). When provided, buckets are computed in this timezone.

start_timestring · date-time · nullableOptional

Filter to rows where time index >= start_time (ISO 8601)

end_timestring · date-time · nullableOptional

Filter to rows where time index < end_time (ISO 8601)

price_thresholdnumber · nullableOptional

Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold.

contingency_idstring · nullableOptional

Optional contingency GS entity ID filter.

Header parameters

x-api-keystring · nullableOptional

API key for authentication (header)

Responses

200

Successful Response

application/json

Per-interval aggregate stats for filtered constraint rows.

interval_start_utcstring · date-timeRequired

binding_intervalsinteger · nullableRequired

shadow_price_minnumber · nullableRequired

shadow_price_meannumber · nullableRequired

shadow_price_mediannumber · nullableRequired

shadow_price_maxnumber · nullableRequired

total_costnumber · nullableRequired

422

Validation Error

application/json

get/constraints/{constraint_id}/stats

GET /v1/constraints/{constraint_id}/stats?aggregation_period=hour&dataset_id=text HTTP/1.1
Host: api.gridstatus.io
Accept: */*

[
  {
    "interval_start_utc": "2026-07-20T13:50:40.809Z",
    "binding_intervals": 1,
    "shadow_price_min": 1,
    "shadow_price_mean": 1,
    "shadow_price_median": 1,
    "shadow_price_max": 1,
    "total_cost": 1
  }
]

List Constraint Binding Counts By Period

get

Summarize unique binding constraints per UTC period for a dataset.

Query parameters

aggregation_periodstring · enumOptional

UTC aggregation period for grouping counts. Supported values: hour, day, month, year.

Default: hourPossible values:

api_keystring · nullableOptional

API key for authentication (query)

dataset_idstringRequired

start_timestring · date-time · nullableOptional

Filter to rows where time index >= start_time (ISO 8601)

end_timestring · date-time · nullableOptional

Filter to rows where time index < end_time (ISO 8601 timestamp)

price_thresholdnumber · nullableOptional

Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold.

Header parameters

x-api-keystring · nullableOptional

API key for authentication (header)

Responses

200

Successful Response

application/json

Count of unique binding constraints for a single UTC aggregation period.

period_start_utcstring · date-timeRequired

binding_constraint_countintegerRequired

binding_constraint_idsstring[]Required

422

Validation Error

application/json

get/constraints/binding/counts

GET /v1/constraints/binding/counts?dataset_id=text HTTP/1.1
Host: api.gridstatus.io
Accept: */*

[
  {
    "period_start_utc": "2026-07-20T13:50:40.809Z",
    "binding_constraint_count": 1,
    "binding_constraint_ids": [
      "text"
    ]
  }
]

List Constraint Binding Costs By Period

get

Summarize total binding cost per UTC period for a dataset.

Query parameters

aggregation_periodstring · enumOptional

UTC aggregation period for grouping costs. Supported values: hour, day, month, year.

Default: hourPossible values:

api_keystring · nullableOptional

API key for authentication (query)

dataset_idstringRequired

start_timestring · date-time · nullableOptional

Filter to rows where time index >= start_time (ISO 8601)

end_timestring · date-time · nullableOptional

Filter to rows where time index < end_time (ISO 8601 timestamp)

price_thresholdnumber · nullableOptional

Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold.

Header parameters

x-api-keystring · nullableOptional

API key for authentication (header)

Responses

200

Successful Response

application/json

Total binding cost for a single UTC aggregation period.

period_start_utcstring · date-timeRequired

total_costnumber · nullableRequired

422

Validation Error

application/json

get/constraints/binding/costs

GET /v1/constraints/binding/costs?dataset_id=text HTTP/1.1
Host: api.gridstatus.io
Accept: */*

[
  {
    "period_start_utc": "2026-07-20T13:50:40.809Z",
    "total_cost": 1
  }
]

Get Constraint Binding Heat Map

get

Return binding costs aggregated by time bucket and constraint id.

Query parameters

api_keystring · nullableOptional

API key for authentication (query)

dataset_idstringRequired

start_timestring · date-timeRequired

Filter to rows where time index >= start_time (ISO 8601)

end_timestring · date-timeRequired

Filter to rows where time index < end_time (ISO 8601 timestamp)

price_thresholdnumber · nullableOptional

Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold.

Header parameters

x-api-keystring · nullableOptional

API key for authentication (header)

Responses

200

Successful Response

application/json

Binding heat map data for the constraint-by-time card.

interval_minutesinteger · nullableOptional

unsupported_reasonstring · nullableOptional

422

Validation Error

application/json

get/constraints/binding/heat_map

GET /v1/constraints/binding/heat_map?dataset_id=text&start_time=2026-07-20T13%3A50%3A40.809Z&end_time=2026-07-20T13%3A50%3A40.809Z HTTP/1.1
Host: api.gridstatus.io
Accept: */*

{
  "interval_minutes": 1,
  "cells": [
    {
      "bucket_start_utc": "2026-07-20T13:50:40.809Z",
      "interval_start_utc": "2026-07-20T13:50:40.809Z",
      "constraint_gs_entity_id": "text",
      "cost": 1
    }
  ],
  "unsupported_reason": "text"
}

Get Constraint

get

Get data for a specific constraint by its GS entity ID.

Path parameters

gs_entity_idstringRequired

GS entity ID of the constraint to query

Query parameters

api_keystring · nullableOptional

API key for authentication (query)

Header parameters

x-api-keystring · nullableOptional

API key for authentication (header)

Responses

200

Successful Response

application/json

gs_entity_idstringRequired

constraint_namestringRequired

market_idstringRequired

earliest_seen_utcstring · date-time · nullableRequired

latest_seen_utcstring · date-time · nullableRequired

available_datasetsstring[] · nullableRequired

rt_costnumber · nullableOptional

da_costnumber · nullableOptional

gs_created_at_utcstring · date-time · nullableOptional

gs_updated_at_utcstring · date-time · nullableOptional

422

Validation Error

application/json

get/constraints/{gs_entity_id}

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-07-20T13:50:40.809Z",
  "latest_seen_utc": "2026-07-20T13:50:40.809Z",
  "available_datasets": [
    "text"
  ],
  "rt_cost": 1,
  "da_cost": 1,
  "gs_created_at_utc": "2026-07-20T13:50:40.809Z",
  "gs_updated_at_utc": "2026-07-20T13:50:40.809Z"
}

Get Constraint Intervals

get

Year/month/day-level statistics on binding intervals in ISO local time.

Path parameters

constraint_idstringRequired

GS entity ID of the constraint to query

Query parameters

dataset_idstringRequired

contingency_idstring · nullableOptional

Optional contingency GS entity ID filter. Applied only when the dataset contains contingency_gs_entity_id.

api_keystring · nullableOptional

API key for authentication (query)

Header parameters

x-api-keystring · nullableOptional

API key for authentication (header)

Responses

200

Successful Response

application/json

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.

yearintegerRequired

countintegerRequired

422

Validation Error

application/json

get/constraints/{constraint_id}/intervals

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"
            ]
          }
        ]
      }
    ]
  }
]

List Contingencies For Constraint

get

Contingencies binding for a constraint in a dataset/time window.

Path parameters

constraint_idstringRequired

Constraint GS entity ID to filter by (constraint_gs_entity_id)

Query parameters

dataset_idstringRequired

include_binding_statsbooleanOptional

When true, include binding_intervals and total_cost and apply start_time/end_time/time filters. Default returns id and name only.

Default: false

start_timestring · nullableOptional

Start time (ISO timestamp) for filtering (inclusive). Requires time index column. Only used when include_binding_stats is true.

end_timestring · nullableOptional

End time (ISO timestamp) for filtering (exclusive). Requires time index column. Only used when include_binding_stats is true.

timestring · nullableOptional

Optional specific timestamp to filter results. Cannot be used with start_time or end_time. Only used when include_binding_stats is true.

api_keystring · nullableOptional

API key for authentication (query)

Header parameters

x-api-keystring · nullableOptional

API key for authentication (header)

Responses

200

Successful Response

application/json

Contingency with id, name, and optional binding stats.

idstring · nullableRequired

namestringRequired

binding_intervalsinteger · nullableOptional

total_costnumber · nullableOptional

422

Validation Error

application/json

get/constraints/{constraint_id}/contingencies

GET /v1/constraints/{constraint_id}/contingencies?dataset_id=text HTTP/1.1
Host: api.gridstatus.io
Accept: */*

[
  {
    "id": "text",
    "name": "text",
    "binding_intervals": 1,
    "total_cost": 1
  }
]

PreviousCSV Exports NextPricing Locations

Last updated 11 days ago

Was this helpful?