Get States

GET 
/api/v1/states

Fetch a list of states, with pagination and filtering by country.

Request

Responses

200

Successfully retrieved the list of states.

400

Canonical personal-token bad request, including PUBLIC_POSITION_REQUIRED or PUBLIC_ACTOR_OVERRIDE_NOT_ALLOWED.

401

The Bearer personal token is missing, malformed, inactive, expired, revoked, or CIDR-blocked. Personal-token 401 responses include the Bearer challenge. Temporary validation outages return 503 instead.

Response Headers

WWW-Authenticate

403

Canonical personal-token authorization denial, including unavailable or unauthorized position selection.

404

States not found

429

Rate limit exceeded

Response Headers

X-RateLimit-Plan

Active public API plan applied to the request. Free and Kickstarter are blocked before rate buckets are consumed.

X-RateLimit-Bucket

Rate-limit bucket used for the request. List-style POST endpoints are counted as reads; mutation endpoints are counted as writes.

X-RateLimit-Limit

Maximum number of requests allowed for the active bucket in the current one-second rate-limit window.

X-RateLimit-Limit-Read

Maximum read requests allowed per second for the active plan. Pro is 100; Unlimited is 500.

X-RateLimit-Limit-Write

Maximum write requests allowed per second for the active plan. Pro is 25; Unlimited is 125.

X-RateLimit-Remaining

Number of requests remaining for the active bucket in the current one-second rate-limit window.

X-RateLimit-Reset

Unix timestamp, in seconds, when the current rate-limit window resets.

Retry-After

HTTP date when the current limit resets. Present on 429 responses.

500

Internal Server Error

503

Personal access token validation is temporarily unavailable.