Pagination & sorting

The job search endpoint uses cursor-based (keyset) pagination. Each response returns a page of results and an opaque next_cursor you pass back to fetch the next page.

The cursor model

A successful GET /api/v1/jobs response has this shape:

{
  "data": [
    /* job summaries */
  ],
  "next_cursor": "eyJ2IjoicG9zdGVkX2F0Ii...",
  "limit": 100
}

• next_cursor is an opaque string. Pass it as the cursor query parameter on the next request to fetch the following page.
• When there are no more results, next_cursor is null.
• A cursor is bound to the sort value that produced it. You must send the same sort when using a cursor, otherwise the request is rejected with a 400.

Walking through pages

# First page
curl "https://www.puesto.dev/api/v1/jobs?country=US&limit=100" \
  -H "Authorization: Bearer sk_your_key_here"

# Next page — pass the previous next_cursor
curl "https://www.puesto.dev/api/v1/jobs?country=US&limit=100&cursor=eyJ2Ii..." \
  -H "Authorization: Bearer sk_your_key_here"

Keep requesting with the latest next_cursor until it comes back null.

Page size

Control page size with limit:

• Default: 100
• Maximum: 500 — values above 500 are clamped to 500.

The limit field echoed in the response is the effective page size applied to that request.

Sorting

The sort parameter selects the field for the descending keyset pagination:

Results are always returned in descending order of the sort field.

Default freshness window

When you query open listings (status=open, the default) and you do not supply any of posted_since, posted_until, or first_seen_since, results are limited to jobs posted in the last 90 days. Provide an explicit date filter to search outside that window.