---
title: "List Constraint Stats By Interval"
method: GET
path: "/constraints/{constraint_id}/stats"
tags: ["Constraints"]
---

# List Constraint Stats By Interval

`GET /constraints/{constraint_id}/stats`

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

## Path parameters

- `constraint_id` string, required — GS entity ID of the constraint to query

## Query parameters

- `aggregation_period` 'hour' | 'day' | 'month' | 'year', required — Aggregation bucket size. One of "hour", "day", "month", "year".
- `api_key` string, nullable — API key for authentication (query)
- `dataset_id` string, required
- `timezone` string, nullable — Optional IANA timezone (e.g. America/New_York). When provided, buckets are computed in this timezone.
- `start_time` string, date-time, nullable — Filter to rows where time index >= start_time (ISO 8601)
- `end_time` string, date-time, nullable — Filter to rows where time index < end_time (ISO 8601)
- `price_threshold` number, nullable — Optional threshold. When set, only include rows where ABS(configured shadow price column) > price_threshold.
- `contingency_id` string, nullable — Optional contingency GS entity ID filter.

## Headers

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

## Response `200`

Successful Response

- ConstraintStatsIntervalResponse[]
  - `interval_start_utc` string, date-time, required
  - `binding_intervals` integer, nullable, required
  - `shadow_price_min` number, nullable, required
  - `shadow_price_mean` number, nullable, required
  - `shadow_price_median` number, nullable, required
  - `shadow_price_max` number, nullable, required
  - `total_cost` number, nullable, required

## 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)