> ## Documentation Index
> Fetch the complete documentation index at: https://cloro.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# List of states
> Returns a list of US states supported for state-level geo-targeting. Only US is currently supported — other country values return an empty array.
## Overview
The States endpoint returns the states available for state-level geo-targeting. State targeting is only supported for the US — passing any other country code returns an empty array.
State targeting is available on ChatGPT, Copilot, Perplexity, and Gemini. Google and AI Mode use the `location` / `uule` parameters for sub-country precision instead.
Adding the `state` parameter to a monitor request adds **+2 credits** on top of the base cost and any other add-ons.
## Request parameters
| Parameter | Type | Required | Description | Example |
| --------- | ------ | -------- | ------------------------------------------------------------- | ------- |
| `country` | string | Yes | ISO 3166-1 alpha-2 country code. Only `"US"` returns results. | `US` |
## Example usage
```bash cURL theme={null}
curl -X GET "https://api.cloro.dev/v1/states?country=US" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```python Python theme={null}
import requests
response = requests.get(
"https://api.cloro.dev/v1/states",
params={"country": "US"},
headers={"Authorization": "Bearer YOUR_API_KEY"}
)
states = response.json()
# [{"code": "AL", "name": "Alabama"}, {"code": "AK", "name": "Alaska"}, ...]
```
```javascript Node.js theme={null}
const response = await fetch('https://api.cloro.dev/v1/states?country=US', {
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const states = await response.json();
// [{"code": "AL", "name": "Alabama"}, {"code": "AK", "name": "Alaska"}, ...]
```
```json Response theme={null}
[
{ "code": "AL", "name": "Alabama" },
{ "code": "AK", "name": "Alaska" },
{ "code": "AZ", "name": "Arizona" },
{ "code": "CA", "name": "California" },
{ "code": "DC", "name": "District of Columbia" },
{ "code": "NY", "name": "New York" },
{ "code": "TX", "name": "Texas" }
]
```
## Response schema
| Field | Type | Description |
| ------ | ------ | ----------------------------------------- |
| `code` | string | USPS two-letter state code (e.g., `"CA"`) |
| `name` | string | Full state name (e.g., `"California"`) |
## Using states in monitor requests
Pass the `code` value as the `state` parameter in any supported monitor request alongside `country: "US"`:
```bash cURL theme={null}
curl -X POST "https://api.cloro.dev/v1/monitor/chatgpt" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "best Italian restaurants near me",
"country": "US",
"state": "CA"
}'
```
```python Python theme={null}
import requests
response = requests.post(
"https://api.cloro.dev/v1/monitor/chatgpt",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"prompt": "best Italian restaurants near me",
"country": "US",
"state": "CA"
}
)
```
## Common questions
### Which providers support the `state` parameter?
ChatGPT, Copilot, Perplexity, and Gemini support the `state` parameter. Google Search and AI Mode use `location` / `uule` for sub-country targeting instead.
### Can I use `state` with a non-US country?
It depends on which operation you're calling:
* **`GET /v1/states?country=GB`** (or any non-US country) — returns an empty array, no error.
* **`state` field in a monitor request** (e.g., `POST /v1/monitor/chatgpt`) with a non-US `country` — returns a **400 validation error**. The `state` field is only accepted when `country` is `"US"`.
### How does state targeting work?
When you provide `state`, cloro routes your request through a proxy located in that US state. This affects what local results, regional content, and location-specific information the AI provider returns.
## OpenAPI
````yaml api-reference/openapi.json GET /v1/states
openapi: 3.1.0
info:
title: cloro
description: API for monitoring AI responses across different providers and regions
license:
name: MIT
version: 1.0.0
servers:
- url: https://api.cloro.dev
description: Production server
security:
- bearerAuth: []
paths:
/v1/states:
get:
summary: List of states
description: >-
Returns a list of US states supported for state-level geo-targeting.
Only US is currently supported — other country values return an empty
array.
operationId: getStates
parameters:
- name: country
in: query
required: true
description: ISO 3166-1 alpha-2 country code. Only "US" returns results.
schema:
type: string
minLength: 2
maxLength: 2
pattern: ^[A-Z]{2}$
example: US
responses:
'200':
description: List of supported states
content:
application/json:
schema:
type: array
items:
type: object
properties:
code:
type: string
description: USPS two-letter state code
example: CA
name:
type: string
description: Full state name
example: California
required:
- code
- name
example:
- code: AL
name: Alabama
- code: AK
name: Alaska
- code: AZ
name: Arizona
- code: CA
name: California
- code: DC
name: District of Columbia
- code: NY
name: New York
- code: TX
name: Texas
'400':
description: Bad Request — missing or invalid country parameter
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'401':
description: Unauthorized - Authentication error
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
components:
schemas:
ValidationError:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: Request validation failed
details:
type: array
items:
type: object
properties:
field:
type: string
example: prompt
message:
type: string
example: Prompt cannot be empty
AuthenticationError:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- MISSING_API_KEY
- INVALID_API_KEY_FORMAT
- INVALID_OR_EXPIRED_API_KEY
example: MISSING_API_KEY
message:
type: string
example: Missing or invalid API key
timestamp:
type: string
format: date-time
example: '2025-01-15T12:00:00.000Z'
InternalError:
type: object
oneOf:
- properties:
success:
type: boolean
example: false
error:
type: string
example: Maximum retries exceeded
- properties:
error:
type: object
properties:
code:
type: string
example: INTERNAL_SERVER_ERROR
message:
type: string
example: Internal server error
timestamp:
type: string
format: date-time
example: '2025-01-15T12:00:00.000Z'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````