---
title: "List Constraint Costs For Location"
method: GET
path: "/constraints/locations/{location_gs_entity_id}/constraint-costs"
tags: ["Constraints"]
---

# List Constraint Costs For Location

`GET /constraints/locations/{location_gs_entity_id}/constraint-costs`

## Request

- Base URL: `https://api.gridstatus.io/v1`
- URL: `https://api.gridstatus.io/v1/constraints/locations/{location_gs_entity_id}/constraint-costs`
- Auth: none declared
- TypeScript: <https://skmtc.dev/gridstatus/apis/grid-status-api/docs/constraints/locations/:location_gs_entity_id/constraint-costs/get.ts> (a function with typed inputs; its response is checked against the schema)

Get location-adjusted constraint costs over a time range.

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

Pass ``group_by=constraint`` to roll contingency-grained rows up to one row
per constraint (sum of ``adjusted_cost``, mean ``shift_factor``; contingency
fields are null). ``absolute_cost`` is summed when the dataset has a
contingency column; otherwise the shared per-constraint cost is kept once.

## Path parameters

- `location_gs_entity_id` string, required

## Query parameters

- `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)
- `group_by` 'constraint' | 'constraint_contingency': Row grain. `constraint_contingency` (default) returns one row per constraint/contingency pair. `constraint` rolls those rows up to one row per constraint (sum of adjusted_cost, mean shift factor; absolute_cost summed only when the dataset has a contingency column).
- `api_key` string, nullable: API key for authentication (query)

## Headers

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

## Response `200`

Successful Response

- LocationConstraintCostResponse[]
  - `constraint_gs_entity_id` string, required
  - `constraint_name` string, required
  - `contingency_gs_entity_id` string, nullable, required
  - `contingency_name` string, nullable, required
  - `shift_factor` number, required
  - `absolute_cost` number, nullable, required
  - `adjusted_cost` number, nullable, required

## Other responses

- `422`: Validation Error

## Changes

- **2026-08-20** `de58449b43e2`: 1 breaking, 1 info
  - removed the required property `items/total_cost` from the response with the `200` status
  - added the required property `items/absolute_cost` to the response with the `200` status
- **2026-08-08** `fa1f094be2d4`: 1 info
  - added the new optional `query` request parameter `group_by`

[Operation history](https://skmtc.dev/gridstatus/apis/grid-status-api/changes/constraints/locations/:location_gs_entity_id/constraint-costs/get.md)

---

[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.dev/gridstatus/apis/grid-status-api/revisions/7bd80b24a469?raw)