Source: https://www.puesto.dev/docs/pagination
Markdown source: https://www.puesto.dev/docs/pagination.md
Description: Cursor-based keyset pagination, sort options, page size limits, and the default freshness window.

# 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 [#the-cursor-model]

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

```json
{
  "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 [#walking-through-pages]

```bash
# 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 [#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 [#sorting]

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

| Value           | Description                                  |
| --------------- | -------------------------------------------- |
| `posted_at`     | When the job was posted (default).           |
| `first_seen_at` | When the job was first seen by our crawlers. |

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

## Default freshness window [#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.