> For the complete documentation index, see [llms.txt](https://docs.gridstatus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gridstatus.io/developers/api-reference/constraints.md).

# Constraints

## List 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\_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.

```json
{"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/constraints":{"get":{"tags":["Constraints"],"summary":"List Constraints","description":"Get a list of constraints with optional filtering by ISOs and a search term.\n\nReturns constraints where market_id matches an item in the comma-separated\nisos list and constraint_name contains the search term. When sort_order is\nnot specified and there is a search term, results are sorted by relevance\n(shorter constraint_names first). When sort_order is not specified, there is no\nsearch term, and include_costs is false, results are sorted by latest_seen_utc\ndescending (most recently seen first), then market_id ascending, then\nconstraint_name ascending. When include_costs is true and there is no search\nterm, results are sorted by rt_cost descending with nulls last.\n\nUse include_costs, include_timestamps, and include_dataset_metadata to opt\ninto rt_cost/da_cost, GS timestamps, and pricing dataset metadata.","operationId":"list_constraints_v1_constraints_get","parameters":[{"name":"include_costs","in":"query","required":false,"schema":{"type":"boolean","description":"When true, include rt_cost and da_cost on each constraint. Uses cost_start_time and cost_end_time when provided.","default":false,"title":"Include Costs"},"description":"When true, include rt_cost and da_cost on each constraint. Uses cost_start_time and cost_end_time when provided."},{"name":"include_timestamps","in":"query","required":false,"schema":{"type":"boolean","description":"When true, include gs_created_at_utc and gs_updated_at_utc.","default":false,"title":"Include Timestamps"},"description":"When true, include gs_created_at_utc and gs_updated_at_utc."},{"name":"include_dataset_metadata","in":"query","required":false,"schema":{"type":"boolean","description":"When true, include dataset_metadata with pricing dataset specs.","default":false,"title":"Include Dataset Metadata"},"description":"When true, include dataset_metadata with pricing dataset specs."},{"name":"cost_start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Optional lower bound for the cost window. When set, include rows where time index >= cost_start_time. Only used when include_costs is true.","title":"Cost Start Time"},"description":"Optional lower bound for the cost window. When set, include rows where time index >= cost_start_time. Only used when include_costs is true."},{"name":"cost_end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Optional upper bound for the cost window. When set, include rows where time index < cost_end_time. Only used when include_costs is true.","title":"Cost End Time"},"description":"Optional upper bound for the cost window. When set, include rows where time index < cost_end_time. Only used when include_costs is true."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"isos","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated list of market IDs to filter by","title":"Isos"},"description":"Comma-separated list of market IDs to filter by"},{"name":"active_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter latest_seen_utc to be on or after this timestamp","title":"Active After"},"description":"Filter latest_seen_utc to be on or after this timestamp"},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100000,"minimum":0},{"type":"null"}],"description":"Maximum number of results to return (default: 10000)","default":10000,"title":"Limit"},"description":"Maximum number of results to return (default: 10000)"},{"name":"sort_order","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/OrderBy"},{"type":"null"}],"description":"Sort order: asc or desc. Defaults to desc when omitted.","title":"Sort Order"},"description":"Sort order: asc or desc. Defaults to desc when omitted."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional search term to filter by constraint_name","title":"Search"},"description":"Optional search term to filter by constraint_name"},{"name":"sort_column","in":"query","required":false,"schema":{"anyOf":[{"enum":["constraint_name","market_id","earliest_seen_utc","latest_seen_utc"],"type":"string"},{"type":"null"}],"description":"Column to sort by. Must be one of: constraint_name, market_id, earliest_seen_utc, latest_seen_utc","title":"Sort Column"},"description":"Column to sort by. Must be one of: constraint_name, market_id, earliest_seen_utc, latest_seen_utc"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConstraintsListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"OrderBy":{"type":"string","enum":["asc","desc"],"title":"OrderBy"},"ConstraintsListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ConstraintResponse"},"type":"array","title":"Data"},"dataset_metadata":{"anyOf":[{"additionalProperties":{"additionalProperties":{"items":{"$ref":"#/components/schemas/ConstraintPricingDatasetSpecResponse"},"type":"array"},"type":"object"},"type":"object"},{"type":"null"}],"title":"Dataset Metadata"}},"type":"object","required":["data"],"title":"ConstraintsListResponse"},"ConstraintResponse":{"properties":{"gs_entity_id":{"type":"string","title":"Gs Entity Id"},"constraint_name":{"type":"string","title":"Constraint Name"},"market_id":{"type":"string","title":"Market Id"},"earliest_seen_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Earliest Seen Utc"},"latest_seen_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Latest Seen Utc"},"available_datasets":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Available Datasets"},"rt_cost":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rt Cost"},"da_cost":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Da Cost"},"gs_created_at_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Gs Created At Utc"},"gs_updated_at_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Gs Updated At Utc"}},"type":"object","required":["gs_entity_id","constraint_name","market_id","earliest_seen_utc","latest_seen_utc","available_datasets"],"title":"ConstraintResponse"},"ConstraintPricingDatasetSpecResponse":{"properties":{"dataset_id":{"type":"string","title":"Dataset Id"},"shadow_price_column":{"type":"string","title":"Shadow Price Column"}},"type":"object","required":["dataset_id","shadow_price_column"],"title":"ConstraintPricingDatasetSpecResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## List Contingencies

> 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:\
> &#x20;   params: Query parameters (isos, search, active\_after, limit,\
> &#x20;       sort\_column, sort\_order)

```json
{"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/constraints/contingencies":{"get":{"tags":["Constraints"],"summary":"List Contingencies","description":"Get a list of contingencies with optional filtering by ISOs and a search term.\n\nReturns all rows and columns from the contingencies table where market_id\nmatches an item in the comma-separated isos list and contingency_name\ncontains the search term. When sort_order is not specified and there is a\nsearch term, results are sorted by relevance (shorter contingency_names\nfirst). When sort_order is not specified and there is no search term,\nresults are sorted by latest_seen_utc descending (most recently seen first),\nthen market_id ascending, then contingency_name ascending for consistent\nordering.\n\nArgs:\n    params: Query parameters (isos, search, active_after, limit,\n        sort_column, sort_order)","operationId":"list_contingencies_v1_constraints_contingencies_get","parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"isos","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated list of market IDs to filter by","title":"Isos"},"description":"Comma-separated list of market IDs to filter by"},{"name":"active_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter latest_seen_utc to be on or after this timestamp","title":"Active After"},"description":"Filter latest_seen_utc to be on or after this timestamp"},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100000,"minimum":0},{"type":"null"}],"description":"Maximum number of results to return (default: 10000)","default":10000,"title":"Limit"},"description":"Maximum number of results to return (default: 10000)"},{"name":"sort_order","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/OrderBy"},{"type":"null"}],"description":"Sort order: asc or desc. Defaults to desc when omitted.","title":"Sort Order"},"description":"Sort order: asc or desc. Defaults to desc when omitted."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional search term to filter by contingency_name","title":"Search"},"description":"Optional search term to filter by contingency_name"},{"name":"sort_column","in":"query","required":false,"schema":{"anyOf":[{"enum":["contingency_name","market_id","earliest_seen_utc","latest_seen_utc"],"type":"string"},{"type":"null"}],"description":"Column to sort by. Must be one of: contingency_name, market_id, earliest_seen_utc, latest_seen_utc","title":"Sort Column"},"description":"Column to sort by. Must be one of: contingency_name, market_id, earliest_seen_utc, latest_seen_utc"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ContingencyListResponse"},"title":"Response List Contingencies V1 Constraints Contingencies Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"OrderBy":{"type":"string","enum":["asc","desc"],"title":"OrderBy"},"ContingencyListResponse":{"properties":{"gs_entity_id":{"type":"string","title":"Gs Entity Id"},"contingency_name":{"type":"string","title":"Contingency Name"},"market_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market Id"},"earliest_seen_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Earliest Seen Utc"},"latest_seen_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Latest Seen Utc"},"available_datasets":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Available Datasets"},"gs_created_at_utc":{"type":"string","format":"date-time","title":"Gs Created At Utc"},"gs_updated_at_utc":{"type":"string","format":"date-time","title":"Gs Updated At Utc"}},"type":"object","required":["gs_entity_id","contingency_name","market_id","earliest_seen_utc","latest_seen_utc","available_datasets","gs_created_at_utc","gs_updated_at_utc"],"title":"ContingencyListResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## List Shift Factors For Location

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

```json
{"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/constraints/locations/{location_gs_entity_id}/shift-factors":{"get":{"tags":["Constraints"],"summary":"List Shift Factors For Location","description":"Retrieve estimated shift factors for a pricing location.\n\nQueries ClickHouse ``linear_estimated_shift_factors`` for the given\nlocation, returning one row per ``constraint_gs_entity_id``. When multiple\nsource rows share the same constraint, ``estimated_shift_factor`` is\naggregated per ``aggregation_function`` (mean, max, min, or median).\nOptional ``contingency_id`` restricts rows to a single contingency.\nOptional ``dataset_id`` filters on ``source_dataset``.\nWhen ``exclude_zeros`` is true, source rows with ``estimated_shift_factor``\nequal to zero are dropped before aggregating per constraint.","operationId":"list_shift_factors_for_location_v1_constraints_locations__location_gs_entity_id__shift_factors_get","parameters":[{"name":"location_gs_entity_id","in":"path","required":true,"schema":{"type":"string","title":"Location Gs Entity Id"}},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"contingency_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contingency ID","description":"When set, only include rows with this contingency_gs_entity_id"},"description":"When set, only include rows with this contingency_gs_entity_id"},{"name":"dataset_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dataset ID","description":"When set, only include rows with this source_dataset"},"description":"When set, only include rows with this source_dataset"},{"name":"exclude_zeros","in":"query","required":false,"schema":{"type":"boolean","title":"Exclude zeros","description":"When true, exclude rows where estimated_shift_factor is zero before aggregating each group","default":false},"description":"When true, exclude rows where estimated_shift_factor is zero before aggregating each group"},{"name":"aggregation_function","in":"query","required":false,"schema":{"enum":["mean","max","min","median"],"type":"string","title":"Aggregation function","description":"Function used to combine source rows in each group: mean, max, min, or median","default":"mean"},"description":"Function used to combine source rows in each group: mean, max, min, or median"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ShiftFactorConstraintResponse"},"title":"Response List Shift Factors For Location V1 Constraints Locations  Location Gs Entity Id  Shift Factors Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ShiftFactorConstraintResponse":{"properties":{"constraint_gs_entity_id":{"type":"string","title":"Constraint Gs Entity Id"},"estimated_shift_factor":{"type":"number","title":"Estimated Shift Factor"},"constraint":{"type":"string","title":"Constraint"}},"type":"object","required":["constraint_gs_entity_id","estimated_shift_factor","constraint"],"title":"ShiftFactorConstraintResponse","description":"Linear estimated shift factor aggregated per constraint for a location."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## List Constraint Costs For Location

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

```json
{"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/constraints/locations/{location_gs_entity_id}/constraint-costs":{"get":{"tags":["Constraints"],"summary":"List Constraint Costs For Location","description":"Get location-adjusted constraint costs over a time range.\n\nThe endpoint computes total cost per constraint/contingency pair from the\nspecified constraint dataset in ClickHouse, then multiplies each by the\nlocation's aggregated shift factor (mean) from\n``linear_estimated_shift_factors`` for the same dataset.\nFor datasets without ``contingency_gs_entity_id``, costs are computed per\nconstraint and reused across that constraint's shift-factor contingency rows.","operationId":"list_constraint_costs_for_location_v1_constraints_locations__location_gs_entity_id__constraint_costs_get","parameters":[{"name":"location_gs_entity_id","in":"path","required":true,"schema":{"type":"string","title":"Location Gs Entity Id"}},{"name":"dataset_id","in":"query","required":true,"schema":{"type":"string","title":"Dataset Id"}},{"name":"start_time","in":"query","required":true,"schema":{"type":"string","format":"date-time","description":"Filter to rows where time index >= start_time (ISO 8601)","title":"Start Time"},"description":"Filter to rows where time index >= start_time (ISO 8601)"},{"name":"end_time","in":"query","required":true,"schema":{"type":"string","format":"date-time","description":"Filter to rows where time index < end_time (ISO 8601)","title":"End Time"},"description":"Filter to rows where time index < end_time (ISO 8601)"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LocationConstraintCostResponse"},"title":"Response List Constraint Costs For Location V1 Constraints Locations  Location Gs Entity Id  Constraint Costs Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"LocationConstraintCostResponse":{"properties":{"constraint_gs_entity_id":{"type":"string","title":"Constraint Gs Entity Id"},"constraint_name":{"type":"string","title":"Constraint Name"},"contingency_gs_entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contingency Gs Entity Id"},"contingency_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contingency Name"},"shift_factor":{"type":"number","title":"Shift Factor"},"total_cost":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Cost"},"adjusted_cost":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Adjusted Cost"}},"type":"object","required":["constraint_gs_entity_id","constraint_name","contingency_gs_entity_id","contingency_name","shift_factor","total_cost","adjusted_cost"],"title":"LocationConstraintCostResponse","description":"Constraint contingency costs adjusted by a location's shift factor."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## List Constraint Impact For Location

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

```json
{"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/constraints/locations/{location_gs_entity_id}/constraint-impact":{"get":{"tags":["Constraints"],"summary":"List Constraint Impact For Location","description":"Get per-constraint impact from abs(median shadow price) and shift factors.","operationId":"list_constraint_impact_for_location_v1_constraints_locations__location_gs_entity_id__constraint_impact_get","parameters":[{"name":"location_gs_entity_id","in":"path","required":true,"schema":{"type":"string","title":"Location Gs Entity Id"}},{"name":"dataset_id","in":"query","required":true,"schema":{"type":"string","title":"Dataset Id"}},{"name":"start_time","in":"query","required":true,"schema":{"type":"string","format":"date-time","description":"Filter to rows where time index >= start_time (ISO 8601)","title":"Start Time"},"description":"Filter to rows where time index >= start_time (ISO 8601)"},{"name":"end_time","in":"query","required":true,"schema":{"type":"string","format":"date-time","description":"Filter to rows where time index < end_time (ISO 8601)","title":"End Time"},"description":"Filter to rows where time index < end_time (ISO 8601)"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LocationConstraintImpactResponse"},"title":"Response List Constraint Impact For Location V1 Constraints Locations  Location Gs Entity Id  Constraint Impact Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"LocationConstraintImpactResponse":{"properties":{"constraint_gs_entity_id":{"type":"string","title":"Constraint Gs Entity Id"},"constraint_name":{"type":"string","title":"Constraint Name"},"absolute_median_shadow_price":{"type":"number","title":"Absolute Median Shadow Price"},"average_shift_factor":{"type":"number","title":"Average Shift Factor"},"price_impact":{"type":"number","title":"Price Impact"}},"type":"object","required":["constraint_gs_entity_id","constraint_name","absolute_median_shadow_price","average_shift_factor","price_impact"],"title":"LocationConstraintImpactResponse","description":"Per-constraint impact at a location from median shadow price and shift factor."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## List Shift Factors

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

```json
{"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/constraints/{constraint_id}/shift-factors":{"get":{"tags":["Constraints"],"summary":"List Shift Factors","description":"Retrieve estimated shift factors for a constraint.\n\nQueries ClickHouse ``linear_estimated_shift_factors`` for the given\nconstraint, returning one row per ``location_gs_entity_id``. When multiple\nsource rows share the same location, ``estimated_shift_factor`` is\naggregated per ``aggregation_function`` (mean, max, min, or median).\nOptional ``contingency_id`` restricts rows to a single contingency.\nOptional ``dataset_id`` filters on ``source_dataset``.\nWhen ``exclude_zeros`` is true, source rows with ``estimated_shift_factor``\nequal to zero are dropped before aggregating per location.","operationId":"list_shift_factors_v1_constraints__constraint_id__shift_factors_get","parameters":[{"name":"constraint_id","in":"path","required":true,"schema":{"type":"string","title":"Constraint ID","description":"GS entity ID of the constraint to get shift factors for"},"description":"GS entity ID of the constraint to get shift factors for"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"contingency_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contingency ID","description":"When set, only include rows with this contingency_gs_entity_id"},"description":"When set, only include rows with this contingency_gs_entity_id"},{"name":"dataset_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dataset ID","description":"When set, only include rows with this source_dataset"},"description":"When set, only include rows with this source_dataset"},{"name":"exclude_zeros","in":"query","required":false,"schema":{"type":"boolean","title":"Exclude zeros","description":"When true, exclude rows where estimated_shift_factor is zero before aggregating each group","default":false},"description":"When true, exclude rows where estimated_shift_factor is zero before aggregating each group"},{"name":"aggregation_function","in":"query","required":false,"schema":{"enum":["mean","max","min","median"],"type":"string","title":"Aggregation function","description":"Function used to combine source rows in each group: mean, max, min, or median","default":"mean"},"description":"Function used to combine source rows in each group: mean, max, min, or median"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ShiftFactorLocationResponse"},"title":"Response List Shift Factors V1 Constraints  Constraint Id  Shift Factors Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ShiftFactorLocationResponse":{"properties":{"location_gs_entity_id":{"type":"string","title":"Location Gs Entity Id"},"estimated_shift_factor":{"type":"number","title":"Estimated Shift Factor"},"location":{"type":"string","title":"Location"}},"type":"object","required":["location_gs_entity_id","estimated_shift_factor","location"],"title":"ShiftFactorLocationResponse","description":"Linear estimated shift factor aggregated per location for a constraint."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## List Constraint Binding Rows

> Get binding rows for a dataset with constraint display names.

```json
{"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/constraints/binding":{"get":{"tags":["Constraints"],"summary":"List Constraint Binding Rows","description":"Get binding rows for a dataset with constraint display names.","operationId":"list_constraint_binding_rows_v1_constraints_binding_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100000,"minimum":1,"description":"Maximum number of rows to return.","default":50000,"title":"Limit"},"description":"Maximum number of rows to return."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"dataset_id","in":"query","required":true,"schema":{"type":"string","title":"Dataset Id"}},{"name":"start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter to rows where time index >= start_time (ISO 8601)","title":"Start Time"},"description":"Filter to rows where time index >= start_time (ISO 8601)"},{"name":"end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter to rows where time index < end_time (ISO 8601 timestamp)","title":"End Time"},"description":"Filter to rows where time index < end_time (ISO 8601 timestamp)"},{"name":"price_threshold","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold.","title":"Price Threshold"},"description":"Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true},"title":"Response List Constraint Binding Rows V1 Constraints Binding Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## List Constraint Binding Intervals By Hour

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

```json
{"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/constraints/{constraint_id}/binding_intervals_by_hour":{"get":{"tags":["Constraints"],"summary":"List Constraint Binding Intervals By Hour","description":"Get filtered binding interval counts grouped by hour-of-day.","operationId":"list_constraint_binding_intervals_by_hour_v1_constraints__constraint_id__binding_intervals_by_hour_get","parameters":[{"name":"constraint_id","in":"path","required":true,"schema":{"type":"string","title":"Constraint ID","description":"GS entity ID of the constraint to query"},"description":"GS entity ID of the constraint to query"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"dataset_id","in":"query","required":true,"schema":{"type":"string","title":"Dataset Id"}},{"name":"timezone","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional IANA timezone (e.g. America/New_York). When provided, buckets are computed in this timezone.","title":"Timezone"},"description":"Optional IANA timezone (e.g. America/New_York). When provided, buckets are computed in this timezone."},{"name":"start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter to rows where time index >= start_time (ISO 8601)","title":"Start Time"},"description":"Filter to rows where time index >= start_time (ISO 8601)"},{"name":"end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter to rows where time index < end_time (ISO 8601)","title":"End Time"},"description":"Filter to rows where time index < end_time (ISO 8601)"},{"name":"price_threshold","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold.","title":"Price Threshold"},"description":"Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold."},{"name":"contingency_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional contingency GS entity ID filter.","title":"Contingency Id"},"description":"Optional contingency GS entity ID filter."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ConstraintBindingHourCountResponse"},"title":"Response List Constraint Binding Intervals By Hour V1 Constraints  Constraint Id  Binding Intervals By Hour Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ConstraintBindingHourCountResponse":{"properties":{"hour":{"type":"integer","title":"Hour"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["hour","count"],"title":"ConstraintBindingHourCountResponse","description":"Count of filtered binding rows by local hour (requested timezone or UTC)."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## List Constraint Stats By Interval

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

```json
{"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/constraints/{constraint_id}/stats":{"get":{"tags":["Constraints"],"summary":"List Constraint Stats By Interval","description":"Get per-interval count, shadow-price summary stats, and total cost.","operationId":"list_constraint_stats_by_interval_v1_constraints__constraint_id__stats_get","parameters":[{"name":"constraint_id","in":"path","required":true,"schema":{"type":"string","title":"Constraint ID","description":"GS entity ID of the constraint to query"},"description":"GS entity ID of the constraint to query"},{"name":"aggregation_period","in":"query","required":true,"schema":{"enum":["hour","day","month","year"],"type":"string","description":"Aggregation bucket size. One of \"hour\", \"day\", \"month\", \"year\".","title":"Aggregation Period"},"description":"Aggregation bucket size. One of \"hour\", \"day\", \"month\", \"year\"."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"dataset_id","in":"query","required":true,"schema":{"type":"string","title":"Dataset Id"}},{"name":"timezone","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional IANA timezone (e.g. America/New_York). When provided, buckets are computed in this timezone.","title":"Timezone"},"description":"Optional IANA timezone (e.g. America/New_York). When provided, buckets are computed in this timezone."},{"name":"start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter to rows where time index >= start_time (ISO 8601)","title":"Start Time"},"description":"Filter to rows where time index >= start_time (ISO 8601)"},{"name":"end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter to rows where time index < end_time (ISO 8601)","title":"End Time"},"description":"Filter to rows where time index < end_time (ISO 8601)"},{"name":"price_threshold","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold.","title":"Price Threshold"},"description":"Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold."},{"name":"contingency_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional contingency GS entity ID filter.","title":"Contingency Id"},"description":"Optional contingency GS entity ID filter."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ConstraintStatsIntervalResponse"},"title":"Response List Constraint Stats By Interval V1 Constraints  Constraint Id  Stats Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ConstraintStatsIntervalResponse":{"properties":{"interval_start_utc":{"type":"string","format":"date-time","title":"Interval Start Utc"},"binding_intervals":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Binding Intervals"},"shadow_price_min":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Shadow Price Min"},"shadow_price_mean":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Shadow Price Mean"},"shadow_price_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Shadow Price Median"},"shadow_price_max":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Shadow Price Max"},"total_cost":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Cost"}},"type":"object","required":["interval_start_utc","binding_intervals","shadow_price_min","shadow_price_mean","shadow_price_median","shadow_price_max","total_cost"],"title":"ConstraintStatsIntervalResponse","description":"Per-interval aggregate stats for filtered constraint rows."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## List Constraint Binding Counts By Period

> Summarize unique binding constraints per UTC period for a dataset.

```json
{"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/constraints/binding/counts":{"get":{"tags":["Constraints"],"summary":"List Constraint Binding Counts By Period","description":"Summarize unique binding constraints per UTC period for a dataset.","operationId":"list_constraint_binding_counts_by_period_v1_constraints_binding_counts_get","parameters":[{"name":"aggregation_period","in":"query","required":false,"schema":{"enum":["hour","day","month","year"],"type":"string","description":"UTC aggregation period for grouping counts. Supported values: hour, day, month, year.","default":"hour","title":"Aggregation Period"},"description":"UTC aggregation period for grouping counts. Supported values: hour, day, month, year."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"dataset_id","in":"query","required":true,"schema":{"type":"string","title":"Dataset Id"}},{"name":"start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter to rows where time index >= start_time (ISO 8601)","title":"Start Time"},"description":"Filter to rows where time index >= start_time (ISO 8601)"},{"name":"end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter to rows where time index < end_time (ISO 8601 timestamp)","title":"End Time"},"description":"Filter to rows where time index < end_time (ISO 8601 timestamp)"},{"name":"price_threshold","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold.","title":"Price Threshold"},"description":"Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BindingConstraintCountResponse"},"title":"Response List Constraint Binding Counts By Period V1 Constraints Binding Counts Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"BindingConstraintCountResponse":{"properties":{"period_start_utc":{"type":"string","format":"date-time","title":"Period Start Utc"},"binding_constraint_count":{"type":"integer","title":"Binding Constraint Count"},"binding_constraint_ids":{"items":{"type":"string"},"type":"array","title":"Binding Constraint Ids"}},"type":"object","required":["period_start_utc","binding_constraint_count","binding_constraint_ids"],"title":"BindingConstraintCountResponse","description":"Count of unique binding constraints for a single UTC aggregation period."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## List Constraint Binding Costs By Period

> Summarize total binding cost per UTC period for a dataset.

```json
{"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/constraints/binding/costs":{"get":{"tags":["Constraints"],"summary":"List Constraint Binding Costs By Period","description":"Summarize total binding cost per UTC period for a dataset.","operationId":"list_constraint_binding_costs_by_period_v1_constraints_binding_costs_get","parameters":[{"name":"aggregation_period","in":"query","required":false,"schema":{"enum":["hour","day","month","year"],"type":"string","description":"UTC aggregation period for grouping costs. Supported values: hour, day, month, year.","default":"hour","title":"Aggregation Period"},"description":"UTC aggregation period for grouping costs. Supported values: hour, day, month, year."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"dataset_id","in":"query","required":true,"schema":{"type":"string","title":"Dataset Id"}},{"name":"start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter to rows where time index >= start_time (ISO 8601)","title":"Start Time"},"description":"Filter to rows where time index >= start_time (ISO 8601)"},{"name":"end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter to rows where time index < end_time (ISO 8601 timestamp)","title":"End Time"},"description":"Filter to rows where time index < end_time (ISO 8601 timestamp)"},{"name":"price_threshold","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold.","title":"Price Threshold"},"description":"Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BindingConstraintCostResponse"},"title":"Response List Constraint Binding Costs By Period V1 Constraints Binding Costs Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"BindingConstraintCostResponse":{"properties":{"period_start_utc":{"type":"string","format":"date-time","title":"Period Start Utc"},"total_cost":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Cost"}},"type":"object","required":["period_start_utc","total_cost"],"title":"BindingConstraintCostResponse","description":"Total binding cost for a single UTC aggregation period."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## Get Constraint Binding Heat Map

> Return binding costs aggregated by time bucket and constraint id.

```json
{"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/constraints/binding/heat_map":{"get":{"tags":["Constraints"],"summary":"Get Constraint Binding Heat Map","description":"Return binding costs aggregated by time bucket and constraint id.","operationId":"get_constraint_binding_heat_map_v1_constraints_binding_heat_map_get","parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"dataset_id","in":"query","required":true,"schema":{"type":"string","title":"Dataset Id"}},{"name":"start_time","in":"query","required":true,"schema":{"type":"string","format":"date-time","description":"Filter to rows where time index >= start_time (ISO 8601)","title":"Start Time"},"description":"Filter to rows where time index >= start_time (ISO 8601)"},{"name":"end_time","in":"query","required":true,"schema":{"type":"string","format":"date-time","description":"Filter to rows where time index < end_time (ISO 8601 timestamp)","title":"End Time"},"description":"Filter to rows where time index < end_time (ISO 8601 timestamp)"},{"name":"price_threshold","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold.","title":"Price Threshold"},"description":"Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConstraintBindingHeatMapResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ConstraintBindingHeatMapResponse":{"properties":{"interval_minutes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Interval Minutes"},"cells":{"items":{"$ref":"#/components/schemas/ConstraintBindingHeatMapCellResponse"},"type":"array","title":"Cells"},"unsupported_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unsupported Reason"}},"type":"object","title":"ConstraintBindingHeatMapResponse","description":"Binding heat map data for the constraint-by-time card."},"ConstraintBindingHeatMapCellResponse":{"properties":{"bucket_start_utc":{"type":"string","format":"date-time","title":"Bucket Start Utc"},"interval_start_utc":{"type":"string","format":"date-time","title":"Interval Start Utc","description":"UTC timestamp of the binding row with the largest absolute shadow price in this bucket; may be an irregular dataset time index (not necessarily aligned to bucket_start_utc)."},"constraint_gs_entity_id":{"type":"string","title":"Constraint Gs Entity Id"},"cost":{"type":"number","title":"Cost"}},"type":"object","required":["bucket_start_utc","interval_start_utc","constraint_gs_entity_id","cost"],"title":"ConstraintBindingHeatMapCellResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## Get Constraint

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

```json
{"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/constraints/{gs_entity_id}":{"get":{"tags":["Constraints"],"summary":"Get Constraint","description":"Get data for a specific constraint by its GS entity ID.","operationId":"get_constraint_v1_constraints__gs_entity_id__get","parameters":[{"name":"gs_entity_id","in":"path","required":true,"schema":{"type":"string","title":"GS Entity ID","description":"GS entity ID of the constraint to query"},"description":"GS entity ID of the constraint to query"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConstraintResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ConstraintResponse":{"properties":{"gs_entity_id":{"type":"string","title":"Gs Entity Id"},"constraint_name":{"type":"string","title":"Constraint Name"},"market_id":{"type":"string","title":"Market Id"},"earliest_seen_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Earliest Seen Utc"},"latest_seen_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Latest Seen Utc"},"available_datasets":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Available Datasets"},"rt_cost":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rt Cost"},"da_cost":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Da Cost"},"gs_created_at_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Gs Created At Utc"},"gs_updated_at_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Gs Updated At Utc"}},"type":"object","required":["gs_entity_id","constraint_name","market_id","earliest_seen_utc","latest_seen_utc","available_datasets"],"title":"ConstraintResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## Get Constraint Intervals

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

```json
{"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/constraints/{constraint_id}/intervals":{"get":{"tags":["Constraints"],"summary":"Get Constraint Intervals","description":"Year/month/day-level statistics on binding intervals in ISO local time.","operationId":"get_constraint_intervals_v1_constraints__constraint_id__intervals_get","parameters":[{"name":"constraint_id","in":"path","required":true,"schema":{"type":"string","title":"Constraint ID","description":"GS entity ID of the constraint to query"},"description":"GS entity ID of the constraint to query"},{"name":"dataset_id","in":"query","required":true,"schema":{"type":"string","title":"Dataset Id"}},{"name":"contingency_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contingency ID","description":"Optional contingency GS entity ID filter. Applied only when the dataset contains contingency_gs_entity_id."},"description":"Optional contingency GS entity ID filter. Applied only when the dataset contains contingency_gs_entity_id."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ConstraintIntervalResponse"},"title":"Response Get Constraint Intervals V1 Constraints  Constraint Id  Intervals Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ConstraintIntervalResponse":{"properties":{"year":{"type":"integer","title":"Year"},"count":{"type":"integer","title":"Count"},"months":{"anyOf":[{"items":{"$ref":"#/components/schemas/ConstraintIntervalMonthResponse"},"type":"array"},{"type":"null"}],"title":"Months"}},"type":"object","required":["year","count"],"title":"ConstraintIntervalResponse","description":"Year/month/day-level statistics for constraint binding intervals.\n\nYear: months with data and count in each.\nMonth: days with data and count in each.\nDay: times (HH:MM:SS strings) for unique timestamps on that day."},"ConstraintIntervalMonthResponse":{"properties":{"month":{"type":"integer","title":"Month"},"count":{"type":"integer","title":"Count"},"days":{"anyOf":[{"items":{"$ref":"#/components/schemas/ConstraintIntervalDayResponse"},"type":"array"},{"type":"null"}],"title":"Days"}},"type":"object","required":["month","count"],"title":"ConstraintIntervalMonthResponse","description":"Month-level count of unique timestamps within a year."},"ConstraintIntervalDayResponse":{"properties":{"day":{"type":"integer","title":"Day"},"count":{"type":"integer","title":"Count"},"times":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Times"}},"type":"object","required":["day","count"],"title":"ConstraintIntervalDayResponse","description":"Day-level count of unique timestamps within a month."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## List Contingencies For Constraint

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

```json
{"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/constraints/{constraint_id}/contingencies":{"get":{"tags":["Constraints"],"summary":"List Contingencies For Constraint","description":"Contingencies binding for a constraint in a dataset/time window.","operationId":"list_contingencies_for_constraint_v1_constraints__constraint_id__contingencies_get","parameters":[{"name":"constraint_id","in":"path","required":true,"schema":{"type":"string","title":"Constraint ID","description":"Constraint GS entity ID to filter by (constraint_gs_entity_id)"},"description":"Constraint GS entity ID to filter by (constraint_gs_entity_id)"},{"name":"dataset_id","in":"query","required":true,"schema":{"type":"string","title":"Dataset Id"}},{"name":"include_binding_stats","in":"query","required":false,"schema":{"type":"boolean","description":"When true, include binding_intervals and total_cost and apply start_time/end_time/time filters. Default returns id and name only.","default":false,"title":"Include Binding Stats"},"description":"When true, include binding_intervals and total_cost and apply start_time/end_time/time filters. Default returns id and name only."},{"name":"start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Start time (ISO timestamp) for filtering (inclusive). Requires time index column. Only used when include_binding_stats is true.","title":"Start Time"},"description":"Start time (ISO timestamp) for filtering (inclusive). Requires time index column. Only used when include_binding_stats is true."},{"name":"end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"End time (ISO timestamp) for filtering (exclusive). Requires time index column. Only used when include_binding_stats is true.","title":"End Time"},"description":"End time (ISO timestamp) for filtering (exclusive). Requires time index column. Only used when include_binding_stats is true."},{"name":"time","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional specific timestamp to filter results. Cannot be used with start_time or end_time. Only used when include_binding_stats is true.","title":"Time"},"description":"Optional specific timestamp to filter results. Cannot be used with start_time or end_time. Only used when include_binding_stats is true."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ContingencyResponse"},"title":"Response List Contingencies For Constraint V1 Constraints  Constraint Id  Contingencies Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ContingencyResponse":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id"},"name":{"type":"string","title":"Name"},"binding_intervals":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Binding Intervals"},"total_cost":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Cost"}},"type":"object","required":["id","name"],"title":"ContingencyResponse","description":"Contingency with id, name, and optional binding stats."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.gridstatus.io/developers/api-reference/constraints.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.