API reference · Public jobs API

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.

1 min read Updated Maintained by the GreenHired team
View Markdown
On this page
  1. How it works
  2. The rules
  3. Frequently asked questions

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

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

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

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