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

- Source: https://greenhired.com/developers/api/v1/limits/
- Section: GreenHired developers · API · Reference
- Last updated: 2026-11-21

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

|  | 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` |

> **Info:** The account API (personal keys) does not send the `X-RateLimit-*` headers. It answers a `429` with `Retry-After`.

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

*JavaScript*

```javascript
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');
}
```

*Python*

```python
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](mailto: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](https://greenhired.com/developers/mcp/protocol/).

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

## Related pages

- https://greenhired.com/developers/api/v1/errors/
- https://greenhired.com/developers/api/v1/pagination/
- https://greenhired.com/developers/api/v1/personal-keys/
