Authentication, plans, and errors

Every Clair API uses one origin and one key. Paid plans are sold per API.


Origin	`https://api.clair.im`
Header	`Authorization: Bearer YOUR_KEY`
Keys	Dashboard → API keys

curl -G https://api.clair.im/v1/google-search \
  -H "Authorization: Bearer YOUR_KEY" \
  --data-urlencode "q=inflation" \
  --data-urlencode "page=1"

Every API has a free tier of 200 requests a month, with no card and a 10 requests/minute cap. Start it on the API’s page in the dashboard. Create a key once and copy it; Clair cannot show the secret again.

Plans and requests

Each API is its own subscription, and an account can hold any number of them. A call to an API the account does not subscribe to returns 403 with not_subscribed.

Free: 200 requests a month per API, no card. The API stops when the month’s requests run out.
Pro, Ultra, Mega: a monthly price with included requests. After those, each request is billed at the tier’s rate until the tier’s monthly ceiling.
Pay as you go: no monthly fee and no included requests. Every request is billed until the ceiling.

Prices and ceilings for each API are on its page in the API catalog. When a period’s requests or ceiling are used up, calls return 429 with quota_exceeded until the next period or a plan change. Unused included requests do not roll over. Every call costs one request, whichever endpoint it hits. A call rejected with 400 for bad parameters is not charged. A call that ends in a 5xx is refunded. A 4xx, such as not_found for a profile that does not exist, is an answer about your input and is charged.

Family	Requests	Examples
Google Search	1	`GET /v1/google-search`
Google Maps	1	`GET /v1/google-maps/search` or `/v1/google-maps/place`
Google News	1	`GET /v1/google-news`
Reuters	1	`GET /v1/reuters/search` or `/v1/reuters/article`, one page each
Bloomberg, AP	1	`GET /v1/bloomberg/search`, `/v1/bloomberg/article`, `/v1/ap/search`, `/v1/ap/article`, one page each
Glassdoor	1	`GET /v1/glassdoor/jobs`, `/v1/glassdoor/job`, `/v1/glassdoor/companies`, `/v1/glassdoor/company`, `/v1/glassdoor/salaries`
Indeed	1	`GET /v1/indeed/jobs` or `/v1/indeed/job`, one page each
Greenhouse	1	`GET /v1/greenhouse/jobs` or `/v1/greenhouse/job`, one page each
Amazon	1	`GET /v1/amazon/search`, `/v1/amazon/product`, `/v1/amazon/reviews`, `/v1/amazon/offers`, `/v1/amazon/lookup`, `/v1/amazon/seller`, `/v1/amazon/seller-products`, `/v1/amazon/bestsellers`, `/v1/amazon/categories`
Crunchbase	1	`GET /v1/crunchbase/organization` or `/v1/crunchbase/person`, one profile
Product Hunt	1	`GET /v1/producthunt/launches` or `GET /v1/producthunt/product`
Trustpilot	1	`GET /v1/trustpilot/reviews`, `/v1/trustpilot/search`, `/v1/trustpilot/categories`, `/v1/trustpilot/review`
Website contacts	1	`GET /v1/contacts`

Each page on a live scraper is a new billed request.

Rate limits

The rate limit is per account, not per API or per key. It follows the fastest plan the account holds:

Plan	Limit
Free	10 requests / minute
Pay as you go	5 requests / second
Pro	5 requests / second
Ultra	10 requests / second
Mega	20 requests / second

Past the limit, calls return 429 with rate_limit_exceeded and a Retry-After header.

Response headers

Header	Meaning
`X-Request-ID`	Unique id for the call. Include it when reporting a problem.
`X-Credits-Remaining`	Included requests left on this API’s subscription this period. `0` on pay as you go or once billed overage starts.
`RateLimit-Limit`	The account’s rate limit for the current window.
`RateLimit-Remaining`	Requests left in the current window.
`Retry-After`	Seconds to wait, sent with `429` rate limits and `503`.

Errors

Mounted endpoints return a stable error code and human detail. Branch on the code; do not parse detail.

{ "error": "bad_request", "detail": "q is required" }

Status	`error`	Meaning
`400`	`bad_request`	A parameter failed validation.
`400`	`bad_cursor`	The cursor is malformed, bound to different inputs, or this endpoint does not paginate.
`400`	`locked_parameter`	A pin-locked filter was sent (for example `limit` on a live scrape, or `sources` on a publisher API).
`400`	`unsupported_parameter`	This endpoint does not accept that parameter (for example `q` on Reuters).
`401`	`unauthorized`	Missing or invalid Bearer key.
`403`	`forbidden`	This key cannot query that API.
`403`	`not_subscribed`	The account has no subscription to this API. Start its free tier or a plan.
`404`	`not_found`	No Trustpilot profile, Product Hunt product, Crunchbase permalink, or canonical resource.
`413`	`payload_too_large`	The request body is too large.
`429`	`quota_exceeded`	This API’s requests for the period, or its ceiling, are used up.
`429`	`rate_limit_exceeded`	The account rate limit was hit. Wait `Retry-After` seconds.
`500`	`internal`	Unexpected origin error.
`502`	`scrape_failed`	The live page could not be fetched or parsed. The request is not charged.
`503`	`authentication_unavailable`	The key could not be verified right now. Retry.
`503`	`credits_unavailable`	The request balance could not be checked right now. Retry; nothing was charged.
`503`	`dependency_unavailable`	The platform is briefly unavailable. Retry.
`503`	`product_unavailable`	This API is temporarily unavailable.
`503`	`overloaded`	This endpoint hit its per-machine concurrency limit.
`504`	`timeout`	The live scrape exceeded its deadline.

Every 503 is temporary and carries Retry-After; retry with backoff.

Pagination

Listings use 1-based page. Most return next_cursor: null. Glassdoor sets next_cursor to the next page number; Bloomberg section rails set it to a lineup cursor, passed back as cursor. Indeed search is one page: Indeed shows later pages only to signed-in visitors. Do not send limit. Google Search pages are 10 organic hits (page max 10). Reuters listings are one page. Google News search pages up to 10 (next_cursor is the next page); Google News and Product Hunt listings are a single page (page must be 1). Bloomberg search and AP search paginate with page. Publisher articles are the same API’s /article endpoint with a listing url. Trustpilot, Glassdoor, and Amazon forward page to the public listing. Crunchbase takes a permalink and returns one organization or person.

​Plans and requests

​Rate limits

​Response headers

​Errors

​Pagination

Plans and requests

Rate limits

Response headers

Errors

Pagination