Pagination

List operations return their results one page at a time. A page is an object with the page’s items and a nextCursor:

{
  "items": [
    { "id": "e6a41be9630d4261b6f3131923fdc4ce", "title": "15--STEP ASSY" }
  ],
  "nextCursor": "NEXT_PAGE_CURSOR"
}

Parameters

Parameter	Default	Meaning
`cursor`	None	The `nextCursor` of the previous page. Leave it out for the first page.
`limit`	50	The most items a page may hold, from 1 to 200.
`sort`	Varies	On lists that take it, one field from the operation’s own list. A leading `-` sorts descending.

To read a whole list, request the first page, then repeat the request with cursor set to the last answer’s nextCursor. Stop when nextCursor is null. That page is the last one.

A limit outside 1 to 200 is refused with 400 (bad-request).

Items with equal sort values keep a stable order across pages.

Cursors

A cursor is opaque. Don’t parse it, build one, or change it.
A cursor continues after the last item of the page that returned it. It is not a page number.
A cursor is valid for at least 24 hours after it is issued.
A cursor belongs to the request that produced it: the operation, its filters, its sort, and the organization and user. Send the same filters and sort with the cursor. A cursor that was altered, has expired, or is sent with other filters, another sort, or by another caller is refused with 400 and the Problem type invalid-cursor. It doesn’t say which of these it was.

When you get invalid-cursor, start the list again from the first page. Don’t retry the same cursor. Don’t plan a read that takes longer than 24 hours between two pages.

API_BASE='https://api-staging.fedwright.com/v1'
cursor=''
while :; do
  page=$(curl -fsS -G "$API_BASE/notices" \
    -H "Authorization: Bearer $token" \
    --data-urlencode 'limit=100' \
    --data-urlencode "cursor=$cursor")
  printf '%s' "$page" | jq -c '.items[]'
  cursor=$(printf '%s' "$page" | jq -r '.nextCursor // empty')
  [ -n "$cursor" ] || break
done

An empty cursor= parameter is the same as none. The script sends it on the first request.

Search

Search has its own paging, because its results are ranked, not ordered by a field. At most 5,000 results can be paged through. To reach others, narrow the filters.

`searchNotices`

POST /search takes its paging in the body, next to the query: limit (default 50, at most 200) and cursor. Send the same query with each cursor. The last page has a null nextCursor.

A cursor is valid only for the version of the search index that issued it. When the index is rebuilt, an earlier cursor is refused with 400 (invalid-cursor), and the search must start again. While you page, changes to notices can shift or repeat results between pages.

`searchAllDatasets`

GET /search pages by offset: limit (default 10, at most 25) and offset (default 0, at most 4975). The answer has nextOffset, the offset that returns the next page, or null on the last page. estimatedTotalHits is an estimate, not an exact count.