Skip to main content
GET
/
v1
/
states
List of states
curl --request GET \
  --url https://api.cloro.dev/v1/states \
  --header 'Authorization: Bearer <token>'
[
  {
    "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"
  }
]

​
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

ParameterTypeRequiredDescriptionExample
countrystringYesISO 3166-1 alpha-2 country code. Only "US" returns results.US

​
Example usage

curl -X GET "https://api.cloro.dev/v1/states?country=US" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
[
  { "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

FieldTypeDescription
codestringUSPS two-letter state code (e.g., "CA")
namestringFull 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": 
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"
  }'

​
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.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
country
string
required

ISO 3166-1 alpha-2 country code. Only "US" returns results.

Required string length: 2
Pattern: ^[A-Z]{2}$

Response

List of supported states

​
code
string
required

USPS two-letter state code

Example:

"CA"

​
name
string
required

Full state name

Example:

"California"

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" }
]