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.
#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.
| Item | Public jobs API key (ghk_) | Personal key (ghpk_) |
|---|---|---|
| Per minute | 60 requests | 60 requests, and 30 changes (anything that is not a GET) |
| Per day (UTC) | 5,000 requests | 1,000 for a job seeker's key, 5,000 for an employer's key |
| Too many per minute | 429 rate_limited | 429 rate_limited |
| Too many per day | 429 daily_cap_reached | 429 daily_cap_reached, resets at 00:00 UTC |
| Extra for job changes | Not applicable | A 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:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests the key may make per minute |
X-RateLimit-Remaining | Requests left in the current minute |
X-RateLimit-Reset | Seconds until the minute window ends |
X-RateLimit-Daily-Limit, X-RateLimit-Daily-Remaining | The daily cap and what is left of it |
Retry-After | On a 429: seconds to wait |
X-API-Version | Always 1 |
Cache-Control | private, 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');
} import time, requests
def get_with_backoff(url, key, tries=4):
for attempt in range(tries):
res = requests.get(url, headers={"Authorization": "Bearer " + key}, timeout=15)
if res.status_code != 429:
return res
time.sleep(int(res.headers.get("Retry-After", 2 ** attempt)))
raise RuntimeError("Still rate limited after %d 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/pingon the public API shows your limits and what you used this minute and today. Every public answer also carries theX-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.
Was this page helpful?