Pagination

Biqli list endpoints use cursor pagination. Cursors remain stable when records share the same creation time and avoid the shifting-page problems associated with page numbers. List results are ordered from newest to oldest by creation time. A public resource ID from the current result set acts as the cursor.

Supported endpoints

The same pagination contract is used when listing:

Each endpoint supports additional filters documented on its reference page.

Parameters

Parameter	Type	Default	Description
`page_size`	integer	`50`	Number of resources to return. Minimum `1`, maximum `100`.
`starting_after`	string	—	Return the next, older page after this public resource ID.
`ending_before`	string	—	Return the previous, newer page before this public resource ID.

starting_after and ending_before are mutually exclusive. Sending both returns 422 validation_error. The cursor must use the resource type expected by the endpoint. For example, the links endpoint accepts biq_lnk_..., while the domains endpoint accepts biq_dom_....

Pagination object

Every list response contains its named collection and a pagination object:

{
  "links": [
    {
      "id": "biq_lnk_01M17YFAR0FEN7R66T99JH820N",
      "short_url": "https://biq.li/r4Q87",
      "long_url": "https://example.com/newer"
    },
    {
      "id": "biq_lnk_01M17Y6XGP07PR11S3DRFCX6Y9",
      "short_url": "https://biq.li/KUpd3Em",
      "long_url": "https://example.com/older"
    }
  ],
  "pagination": {
    "page_size": 2,
    "has_more": true,
    "next_cursor": "biq_lnk_01M17Y6XGP07PR11S3DRFCX6Y9",
    "previous_cursor": null
  },
  "status": "success"
}

Field	Description
`page_size`	Requested page size, even when fewer resources are returned.
`has_more`	`true` when another older page is available.
`next_cursor`	Send as `starting_after` to retrieve that older page; `null` at the end.
`previous_cursor`	Send as `ending_before` to retrieve the newer page; `null` on the first page.

Use the returned cursor values directly. Do not construct them from array positions or assume the last result always has another page.

Move forward through results

Request the first page

Omit both cursors:

curl --request GET \
  --url 'https://biq.li/api/v1/link?page_size=2' \
  --header "Authorization: Bearer $BIQLI_API_KEY" \
  --header 'Accept: application/json'

Move backward

To return to the previous, newer page, send the current response’s previous_cursor as ending_before:

curl --request GET \
  --url 'https://biq.li/api/v1/link?page_size=2&ending_before=biq_lnk_01M17YFAR0FEN7R66T99JH820N' \
  --header "Authorization: Bearer $BIQLI_API_KEY" \
  --header 'Accept: application/json'

The returned collection is still ordered newest to oldest. Biqli does not reverse the visible ordering when moving backward.

Iterate through every result

The following server-side examples retrieve every link using the largest page size and stop only when next_cursor becomes null:

API_BASE='https://biq.li/api/v1'
cursor=''

while true; do
  url="${API_BASE}/link?page_size=100"
  if [ -n "$cursor" ]; then
    url="${url}&starting_after=${cursor}"
  fi

  response="$(curl --fail-with-body --silent --show-error \
    --request GET \
    --url "$url" \
    --header "Authorization: Bearer $BIQLI_API_KEY" \
    --header 'Accept: application/json')" || exit 1

  jq -c '.links[]' <<<"$response"
  cursor="$(jq -r '.pagination.next_cursor // empty' <<<"$response")"

  [ -n "$cursor" ] || break
done

const apiKey = process.env.BIQLI_API_KEY;
let cursor;

do {
  const url = new URL('https://biq.li/api/v1/link');
  url.searchParams.set('page_size', '100');
  if (cursor) url.searchParams.set('starting_after', cursor);

  const response = await fetch(url, {
    headers: {
      Authorization: `Bearer ${apiKey}`,
      Accept: 'application/json',
    },
  });
  const data = await response.json();

  if (!response.ok) {
    throw new Error(`${data.error?.code}: ${data.error?.message}`);
  }

  for (const link of data.links) {
    console.log(link);
  }

  cursor = data.pagination.next_cursor;
} while (cursor);

Keep filters stable

A cursor is resolved inside the workspace and the filters used for that request. Repeat the same filters and page_size on every page:

GET /link?active=true&tag_ids=biq_tag_...&page_size=100
GET /link?active=true&tag_ids=biq_tag_...&page_size=100&starting_after=biq_lnk_...

Changing a filter can make the cursor unavailable in the new result set. Biqli then returns 404 resource_not_found for the pagination cursor.

Cursor pagination is not a database snapshot. Resources created while you traverse older pages can appear on newer pages, and deleting the resource used as a cursor can invalidate the next request. Restart from the first page if a cursor is no longer available.

Common mistakes

Problem	Result
Sending both cursor parameters	`422 validation_error`
Using the wrong resource-prefix cursor	`422 validation_error` or `404 resource_not_found`
Using a cursor from another workspace	`404 resource_not_found`
Changing filters between pages	The cursor may return `404 resource_not_found`
Treating `page_size` as a page number	Repeated or missing data in client logic
Stopping only when the collection is empty	One unnecessary request; stop when `next_cursor` is `null`

Read Errors for the complete error envelope and retry guidance.

GETTING STARTED

BIQLI LINKS API

Supported endpoints

Parameters

Move forward through results

Move backward

Iterate through every result

Keep filters stable

Common mistakes

​Supported endpoints

​Parameters

​Pagination object

​Move forward through results

​Move backward

​Iterate through every result

​Keep filters stable

​Common mistakes

Supported endpoints

Parameters

Pagination object

Move forward through results

Move backward

Iterate through every result

Keep filters stable

Common mistakes