# Pagination with cursors

> Page through GreenHired jobs with a signed cursor: limit is 1 to 50, next_cursor goes back as cursor with the same filters, and new jobs never shift your pages.

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

## How it works

`GET /v1/jobs` uses cursor pagination, never page numbers, so a job posted while you are paging cannot make you see one twice or miss one. Ask for a page, read `page.next_cursor`, and send it back as `cursor` with the same filters.

*curl*

```bash
# first page
curl -s "https://api.greenhired.com/v1/jobs?category=renewable-energy&limit=20" \
  -H "Authorization: Bearer $GREENHIRED_API_KEY"
# { "data": [ ...20 jobs... ], "page": { "next_cursor": "eyJ2Ijox...", "limit": 20, "has_more": true } }

# next page: the same filters plus the cursor
curl -s "https://api.greenhired.com/v1/jobs?category=renewable-energy&limit=20&cursor=eyJ2Ijox..." \
  -H "Authorization: Bearer $GREENHIRED_API_KEY"
```

*JavaScript*

```javascript
async function* allJobs(filters) {
  let cursor = null;
  do {
    const params = new URLSearchParams({ ...filters, limit: '50' });
    if (cursor) params.set('cursor', cursor);
    const res = await fetch('https://api.greenhired.com/v1/jobs?' + params, {
      headers: { Authorization: 'Bearer ' + process.env.GREENHIRED_API_KEY },
    });
    if (!res.ok) throw new Error('GreenHired API ' + res.status);
    const { data, page } = await res.json();
    yield* data;
    cursor = page.has_more ? page.next_cursor : null;
  } while (cursor);
}

for await (const job of allJobs({ category: 'renewable-energy' })) console.log(job.title);
```

*Python*

```python
import os, requests

def all_jobs(**filters):
    cursor = None
    while True:
        params = {**filters, "limit": 50}
        if cursor:
            params["cursor"] = cursor
        res = requests.get(
            "https://api.greenhired.com/v1/jobs",
            params=params,
            headers={"Authorization": "Bearer " + os.environ["GREENHIRED_API_KEY"]},
            timeout=15,
        )
        res.raise_for_status()
        body = res.json()
        yield from body["data"]
        if not body["page"]["has_more"]:
            return
        cursor = body["page"]["next_cursor"]

for job in all_jobs(category="renewable-energy"):
    print(job["title"])
```

## The rules

- `limit` is 1 to 50, default 20. Anything else is a `400`; it is never quietly changed.
- Send the `next_cursor` back as `cursor` **with the same filters** as the page it came from.
- The cursor is opaque and signed. Do not build or edit one. A cursor that was changed, cut, or used with other filters is `400 invalid_cursor`.
- On the last page `next_cursor` is `null` and `has_more` is `false`.
- Each page is one request on your key, so a loop over many pages counts against your limits. See [Rate limits](https://greenhired.com/developers/api/v1/limits/).

## Frequently asked questions

**Can I jump to page 5?**

No. Cursors only move forward from the page you have. Keep the cursors you need, or start again from the first page.

**Can I save a cursor for later?**

Cursors are signed and tied to the filters they came from, and jobs keep changing, so start again from the first page for a fresh view rather than relying on a cursor you saved days ago.

**What does invalid_cursor mean?**

You sent a cursor that was changed, cut, or used with different filters than the page it came from. Start again from the first page with the filters you want.

## Related pages

- https://greenhired.com/developers/api/v1/jobs/
- https://greenhired.com/developers/api/v1/limits/
- https://greenhired.com/developers/api/v1/errors/
