---
title: "Get Constraint Binding Heat Map"
method: GET
path: "/constraints/binding/heat_map"
tags: ["Constraints"]
---

# Get Constraint Binding Heat Map

`GET /constraints/binding/heat_map`

Return binding costs aggregated by time bucket and constraint id.

## Query parameters

- `api_key` string, nullable — API key for authentication (query)
- `dataset_id` string, required
- `start_time` string, date-time, required — Filter to rows where time index >= start_time (ISO 8601)
- `end_time` string, date-time, required — Filter to rows where time index < end_time (ISO 8601 timestamp)
- `price_threshold` number, nullable — Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold.

## Headers

- `x-api-key` string, nullable — API key for authentication (header)

## Response `200`

Successful Response

- ConstraintBindingHeatMapResponse — Binding heat map data for the constraint-by-time card.
  - `interval_minutes` integer, nullable
  - `cells` ConstraintBindingHeatMapCellResponse[]
    - `bucket_start_utc` string, date-time, required
    - `interval_start_utc` string, date-time, required — 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` string, required
    - `shadow_price` number, required — Signed shadow price with the largest absolute value among all binding rows for this constraint in the bucket (all contingencies).
    - `cost` number, required — Sum of duration-normalized binding costs across all binding rows for this constraint in the bucket (all contingencies).
  - `unsupported_reason` string, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/gridstatus/apis/grid-status-api.md) · [All operations](https://skmtc.net/gridstatus/apis/grid-status-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gridstatus/grid-status-api/versions/fa1f094be2d4/schema)