Pagination

Jobs: cursors

GET /v1/jobs returns up to limit results (default 50, at most 100), newest first. When there are more, meta.next_cursor is a string. Send it back unchanged as cursor, with the same filters, to get the next page. On the last page it is null.

curl -s "https://opportunityplatform.co.uk/api/v1/jobs?borough=southwark&limit=100" \
  -H "Authorization: Bearer $OP_API_KEY"

{
  "data": [ ... ],
  "meta": {
    "returned": 100,
    "limit": 100,
    "next_cursor": "eyJ2IjoxLCJ0IjoiMjAyNi0wOS0wMVQxMDowMDowMC4wMDAwMDAiLCJpZCI6Ii4uLiJ9"
  }
}

curl -s "https://opportunityplatform.co.uk/api/v1/jobs?borough=southwark&limit=100&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $OP_API_KEY"

async function allJobs(params) {
  const jobs = [];
  let cursor = null;
  do {
    const qs = new URLSearchParams({ ...params, limit: '100', ...(cursor ? { cursor } : {}) });
    const res = await fetch(`https://opportunityplatform.co.uk/api/v1/jobs?${qs}`, {
      headers: { Authorization: `Bearer ${process.env.OP_API_KEY}` },
    });
    if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
    const body = await res.json();
    jobs.push(...body.data);
    cursor = body.meta.next_cursor;
  } while (cursor);
  return jobs;
}

Walking the cursor returns every matching job exactly once, in order, even if jobs are published while you are paging: a new job appears at the front, never in the middle of your walk.

• Cursors are opaque. Do not build or edit one; a cursor we did not issue returns 400.
• Keep the filters the same from page to page. Changing them mid-walk gives you pages from a different list.
• meta.returned is the size of this page. There is no total count of matches.
• Calls without cursor behave exactly as they did before cursors existed.

Events: page numbers

GET /v1/events pages by number: page (from 1) and limit (default 50, up to 200). total counts every event matching the same filters, including since.

Statistics: nothing to page

/v1/candidates and /v1/s106 each return one summary object, so every row comes back in one response.