---
title: "List Constraints"
method: GET
path: "/constraints"
tags: ["Constraints"]
---

# List Constraints

`GET /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_absolute_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_absolute_costs is true and there is
no search term, results are sorted by rt_absolute_cost descending with nulls last.

Use include_absolute_costs, include_timestamps, and include_dataset_metadata to opt
into rt_absolute_cost/da_absolute_cost, GS timestamps, and pricing dataset metadata.

## Query parameters

- `include_absolute_costs` boolean — When true, include rt_absolute_cost and da_absolute_cost on each constraint. Uses absolute_cost_start_time and absolute_cost_end_time when provided.
- `include_timestamps` boolean — When true, include gs_created_at_utc and gs_updated_at_utc.
- `include_dataset_metadata` boolean — When true, include dataset_metadata with pricing dataset specs.
- `absolute_cost_start_time` string, date-time, nullable — Optional lower bound for the absolute cost window. When set, include rows where time index >= absolute_cost_start_time. Only used when include_absolute_costs is true.
- `absolute_cost_end_time` string, date-time, nullable — Optional upper bound for the absolute cost window. When set, include rows where time index < absolute_cost_end_time. Only used when include_absolute_costs is true.
- `api_key` string, nullable — API key for authentication (query)
- `isos` string, nullable — Comma-separated list of market IDs to filter by
- `active_after` string, date-time, nullable — Filter latest_seen_utc to be on or after this timestamp
- `limit` integer, nullable — Maximum number of results to return (default: 10000)
- `sort_order` 'asc' | 'desc'
- `search` string, nullable — Optional search term to filter by constraint_name
- `sort_column` 'constraint_name' | 'market_id' | 'earliest_seen_utc' | 'latest_seen_utc', nullable — Column to sort by. Must be one of: constraint_name, market_id, earliest_seen_utc, latest_seen_utc

## Headers

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

## Response `200`

Successful Response

- ConstraintsListResponse
  - `data` ConstraintResponse[], required
    - `gs_entity_id` string, required
    - `constraint_name` string, required
    - `market_id` string, required
    - `earliest_seen_utc` string, date-time, nullable, required
    - `latest_seen_utc` string, date-time, nullable, required
    - `available_datasets` string[], nullable, required
    - `rt_absolute_cost` number, nullable
    - `da_absolute_cost` number, nullable
    - `gs_created_at_utc` string, date-time, nullable
    - `gs_updated_at_utc` string, date-time, nullable
  - `dataset_metadata` object, nullable

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