---
title: "Search States"
method: GET
path: "/states/search"
tags: ["States"]
---

# Search States

`GET /states/search`

## Request

- Base URL: `https://api.shovels.ai/v2`
- URL: `https://api.shovels.ai/v2/states/search`
- Auth: API key in header `X-API-Key`

Searches US states by abbreviation or name. Exact abbreviation matches come first, then exact name matches, then other matches. Each group is ordered by state abbreviation.

## Query parameters

- `q` string, required: The name to search for in the state fields.
- `cursor` string, nullable: Continuation cursor containing the match rank and state ID.
- `size` integer

## Response `200`

A list of states that match the search term.

- PaginatedStatesResponse: Paginated response for states.
  - `items` States[], required: The list of items returned in the response following given criteria.
    - `geo_id` string, required: The state abbreviation.
    - `name` string, required: The full name of the state.
  - `size` integer, required: The number of items returned in the response.
  - `next_cursor` string, nullable, required: The cursor for retrieving the next page of results.
  - `total_count` TotalCount: Capped result count with Elasticsearch-style {value, relation} shape. When the exact count is known and within the cap, relation is "eq" and value is that exact count. When the count exceeds the cap, relation is "gte" and value is the cap the count was probed against, meaning "the actual count is at least value". The cap is COUNT_CAP for every wire-facing endpoint; internal guard paths probe against their own cap, so value carries whatever cap produced it.
    - `value` integer, required: The count value; capped at the probe's cap (10,000 on the wire).
    - `relation` 'eq' | 'gte', required: "eq" means value is the exact count. "gte" means the actual count is at least value (the cap).

## Other responses

- `404`: The specified search query didn't match any states
- `422`: Validation Error

## Changes

- **2026-08-04** `685b8866c451`: 2 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status

[Operation history](https://skmtc.dev/shovels/apis/the-shovels-api-v2/changes/states/search/get.md)

---

[API](https://skmtc.dev/shovels/apis/the-shovels-api-v2.md) - [All operations](https://skmtc.dev/shovels/apis/the-shovels-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/shovels/apis/the-shovels-api-v2/revisions/e9f48948b723?raw)