# Pagination

> List endpoints return up to limit items (default 25, maximum 100) plus meta.next_cursor and meta.has_more. Pass next_cursor back as ?cursor= until has_more is false. Cursors are opaque; lists are in ascending id order.

## How it works

Every list endpoint uses cursor pagination. A response looks like this:

```json
{
  "data": [ { "id": 101 }, { "id": 102 } ],
  "meta": {
    "next_cursor": "eyJ1c2Vycy5pZCI6MTAyLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
    "has_more": true
  }
}
```

To get the next page, send the same request with `cursor` set to `meta.next_cursor`. Keep the other query parameters the same. When `has_more` is `false`, `next_cursor` is `null` and you have everything.

| Parameter | Default | Notes |
|---|---|---|
| `limit` | 25 | 1 to 100. A value outside that range is clamped to it. The progress lists default to 50. |
| `cursor` | none | The `meta.next_cursor` from the previous page. Treat it as an opaque string: don't build or change it. |

Lists are ordered by ascending id: courses, folders, events, groups and users by their own id; a user's enrolments and progress by course id; a course's enrolments and progress by user id. New items therefore appear on later pages, and paging is stable while data changes.

## Fetching every page

```bash
curl "https://your-team.continuumlearn.com/api/v2/users?limit=100" \
  -H "Authorization: Bearer $CONTINUUM_API_KEY"

# then, with the cursor from meta.next_cursor:
curl "https://your-team.continuumlearn.com/api/v2/users?limit=100&cursor=eyJ1c2Vycy5pZCI6MTAyLC..." \
  -H "Authorization: Bearer $CONTINUUM_API_KEY"
```

```php
<?php
function allPages(GuzzleHttp\Client $client, string $path, array $query = []): Generator
{
    $query['limit'] = 100;
    do {
        $page = json_decode($client->get($path, ['query' => $query])->getBody(), true);
        yield from $page['data'];
        $query['cursor'] = $page['meta']['next_cursor'];
    } while ($page['meta']['has_more']);
}

foreach (allPages($client, 'users', ['status' => 'active']) as $user) {
    echo $user['email'], PHP_EOL;
}
```

```js
async function* allPages(path, query = {}) {
  const params = new URLSearchParams({ ...query, limit: '100' });
  while (true) {
    const res = await fetch(`https://your-team.continuumlearn.com/api/v2/${path}?${params}`, {
      headers: { Authorization: `Bearer ${process.env.CONTINUUM_API_KEY}` },
    });
    const page = await res.json();
    yield* page.data;
    if (!page.meta.has_more) break;
    params.set('cursor', page.meta.next_cursor);
  }
}

for await (const user of allPages('users', { status: 'active' })) {
  console.log(user.email);
}
```

## Incremental syncs

Pulling everything every night is wasteful. Where an endpoint has a change filter, store the time you started your last sync and pass it next time:

| Endpoint | Change filter |
|---|---|
| `GET /courses` | `updated_since` (ISO 8601): courses whose record changed since then. |
| `GET /users` | `updated_since`: users whose account changed since then. The API also moves this date when it changes a user's custom fields or groups. |
| `GET /courses/{id}/enrolments` | `enrolled_since`: direct enrolments created since then. |
| `GET /courses/{id}/progress` | `completed_since`: learners who completed the course since then. |

`users.updated_at` is the account's own date, which is shared across every Continuum team the person belongs to, so a change made in another team can bring a user into your results. That is harmless, but it means "changed" is a superset of "changed in my team".

For changes as they happen, without polling, use [webhooks](https://continuumlearn.com/developers/webhooks).

## Pages with fewer items than the limit

`GET /events` filters out ended and expired events after fetching each page (unless you pass `status=all`), so a page can hold fewer than `limit` items, or none, while `has_more` is still `true`. Keep following the cursor until `has_more` is `false`.

## Frequently asked questions

### Can I jump to page 5?

No. Cursor pagination only moves forward from one page to the next. That is what keeps it fast and stable on large lists.

### How long does a cursor last?

A cursor encodes a position in the list, not a stored result set, so it doesn't expire. Results reflect the data at the time each page is requested.
