API reference · Reference

Rate limits and daily caps

Every GreenHired key has a per-minute limit and a daily cap. See the defaults, the rate-limit headers, what a 429 means, and how to back off properly.

2 min read Updated Maintained by the GreenHired team
View Markdown
On this page
  1. The limits
  2. Headers on the public API
  3. Back off properly
  4. Frequently asked questions

#The limits

Every key has a limit per minute and a cap per UTC day. Go over either and you get a 429 with Retry-After. The numbers below are the defaults; your API key may have different ones, which GET /v1/ping shows.

ItemPublic jobs API key (ghk_)Personal key (ghpk_)
Per minute60 requests60 requests, and 30 changes (anything that is not a GET)
Per day (UTC)5,000 requests1,000 for a job seeker's key, 5,000 for an employer's key
Too many per minute429 rate_limited429 rate_limited
Too many per day429 daily_cap_reached429 daily_cap_reached, resets at 00:00 UTC
Extra for job changesNot applicableA company can create 20 new jobs a day: 429 company_job_cap

A request that fails with a 4xx or 5xx still counts as a request. On the public API, a request refused for being over the limit is not counted against your daily cap.

#Headers on the public API

Every answer to a public API key carries these headers, so you can slow down before you hit a limit:

HeaderMeaning
X-RateLimit-LimitRequests the key may make per minute
X-RateLimit-RemainingRequests left in the current minute
X-RateLimit-ResetSeconds until the minute window ends
X-RateLimit-Daily-Limit, X-RateLimit-Daily-RemainingThe daily cap and what is left of it
Retry-AfterOn a 429: seconds to wait
X-API-VersionAlways 1
Cache-Controlprivate, max-age=0 on a successful data answer, no-store on every error and on /v1/ping

#Back off properly

On a 429, wait for Retry-After seconds, then try again. Do not retry in a tight loop: every refused request is still traffic. Cache what you can: /v1/categories is at most a minute old and /v1/insights/salaries at most five minutes old anyway.

async function getWithBackoff(url, key, tries = 4) {
  for (let attempt = 0; attempt < tries; attempt++) {
    const res = await fetch(url, { headers: { Authorization: 'Bearer ' + key } });
    if (res.status !== 429) return res;
    const wait = Number(res.headers.get('retry-after')) || 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  }
  throw new Error('Still rate limited after ' + tries + ' tries');
}

A daily cap does not reset until 00:00 UTC, so waiting a few seconds will not help. If you regularly hit it, write to partners@greenhired.com about a higher limit for an API key.

#Frequently asked questions

How do I see how much of my limit I have used?
GET /v1/ping on the public API shows your limits and what you used this minute and today. Every public answer also carries the X-RateLimit-* headers.
Does an MCP request count?
Yes. One MCP request is exactly one request on the key, whatever it is. A tool call is one call to the API behind it. See MCP protocol notes.
Can I get a higher limit?
For a public API key, ask the team: limits are set per key. Personal keys use the limits in the table above.