---
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 absolute costs and shadow-price aggregates by bucket and constraint.

## 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)
- `timezone` string, nullable — Optional IANA timezone used for daily bucket boundaries. Defaults to the dataset market timezone.
- `bucket_mode` 'auto' | 'raw' | 'hourly' | 'daily' — Bucket resolution. Raw preserves the native interval; hourly and daily use explicit buckets. Auto derives resolution from the native interval and selected range. Explicit modes that exceed the range limit resolve to the nearest available mode.
- `group_by` 'constraint' | 'constraint_contingency' — Group rows by constraint and contingency by default, or by constraint only.
- `days_of_week` string, nullable — Optional comma-separated market-local days of the week, where Monday is 1 and Sunday is 7. An empty value matches no rows.
- `hours` string, nullable — Optional comma-separated market-local hour starts from 0 through 23. An empty value matches no rows.

## Headers

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

## Response `200`

Successful Response

- union
  - ConstraintBindingHeatMapSupportedResponse — Absolute binding cost and shadow-price aggregates for a supported dataset.
    - `timezone` string, required
    - `group_by` 'constraint' | 'constraint_contingency', required
    - `supports_contingency_grouping` boolean, required
    - `constraint_names` object
    - `contingency_names` object
    - `native_interval_minutes` integer, required
    - `interval_minutes` integer, required
    - `bucket_mode` 'raw' | 'hourly' | 'daily', required
    - `available_bucket_modes` string[], required — Bucket modes available for the native interval and range.
    - `cells` ConstraintBindingHeatMapCellResponse[]
      - `absolute_cost` number, nullable, required — Total absolute cost: the sum of duration-weighted absolute shadow prices, or null when any binding row has an unknown absolute cost.
      - `peak_shadow_price` number, required — Signed shadow price with the greatest absolute value.
      - `mean_shadow_price` number, required — Mean shadow price.
      - `binding_interval_count` integer, required — Number of underlying binding rows.
      - `bucket_start_utc` string, date-time, required
      - `interval_start_utc` string, date-time, required — UTC timestamp of the shadow price with the greatest absolute value in the bucket. It may be an irregular dataset time index.
      - `constraint_gs_entity_id` string, required
      - `contingency_gs_entity_id` string, nullable
    - `row_summaries` ConstraintBindingHeatMapRowSummaryResponse[]
      - `constraint_gs_entity_id` string, required
      - `contingency_gs_entity_id` string, nullable
      - `metrics` ConstraintBindingHeatMapMetrics, required
        - `absolute_cost` number, nullable, required — Total absolute cost: the sum of duration-weighted absolute shadow prices, or null when any binding row has an unknown absolute cost.
        - `peak_shadow_price` number, required — Signed shadow price with the greatest absolute value.
        - `mean_shadow_price` number, required — Mean shadow price.
        - `binding_interval_count` integer, required — Number of underlying binding rows.
    - `unsupported_reason` unknown
  - ConstraintBindingHeatMapUnsupportedResponse — Binding heat map metadata for a dataset that cannot be displayed.
    - `timezone` string, required
    - `group_by` 'constraint' | 'constraint_contingency', required
    - `supports_contingency_grouping` boolean, required
    - `constraint_names` object
    - `contingency_names` object
    - `native_interval_minutes` unknown
    - `interval_minutes` unknown
    - `bucket_mode` unknown
    - `available_bucket_modes` string[]
    - `cells` ConstraintBindingHeatMapCellResponse[]
      - `absolute_cost` number, nullable, required — Total absolute cost: the sum of duration-weighted absolute shadow prices, or null when any binding row has an unknown absolute cost.
      - `peak_shadow_price` number, required — Signed shadow price with the greatest absolute value.
      - `mean_shadow_price` number, required — Mean shadow price.
      - `binding_interval_count` integer, required — Number of underlying binding rows.
      - `bucket_start_utc` string, date-time, required
      - `interval_start_utc` string, date-time, required — UTC timestamp of the shadow price with the greatest absolute value in the bucket. It may be an irregular dataset time index.
      - `constraint_gs_entity_id` string, required
      - `contingency_gs_entity_id` string, nullable
    - `row_summaries` ConstraintBindingHeatMapRowSummaryResponse[]
      - `constraint_gs_entity_id` string, required
      - `contingency_gs_entity_id` string, nullable
      - `metrics` ConstraintBindingHeatMapMetrics, required
        - `absolute_cost` number, nullable, required — Total absolute cost: the sum of duration-weighted absolute shadow prices, or null when any binding row has an unknown absolute cost.
        - `peak_shadow_price` number, required — Signed shadow price with the greatest absolute value.
        - `mean_shadow_price` number, required — Mean shadow price.
        - `binding_interval_count` integer, required — Number of underlying binding rows.
    - `unsupported_reason` string, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/gridstatus/apis/grid-status-api.md) · [All operations](https://skmtc.dev/gridstatus/apis/grid-status-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/gridstatus/grid-status-api/revisions/43e6e1047e53/schema)