Pagination - Kosli Documentation

List operations in the Kosli API return results in pages. The SDK exposes the underlying page controls directly - there is no automatic iterator; you request each page explicitly.

Request parameters

Paginated operations accept page and perPage query parameters:

Parameter	Type	Description
`page`	`number`	Page number, starting at `1`
`perPage`	`number`	Number of results per page

import { Kosli } from "@kosli/sdk";

const kosli = new Kosli({
  httpBearer: process.env["KOSLI_API_KEY"] ?? "",
});

const result = await kosli.trails.list({}, {
  org: "my-org",
  flowName: "my-flow",
  page: 1,
  perPage: 20,
});

Response formats

Different endpoints return pagination metadata in different ways.

Pagination object in the response body

Some operations return a pagination field alongside the results. It is omitted when all results fit on one page.

const result = await kosli.trails.list({}, {
  org: "my-org",
  flowName: "my-flow",
  page: 1,
  perPage: 20,
});

if (result.pagination) {
  console.log(`Page ${result.pagination.page} of ${result.pagination.pageCount}`);
  console.log(`${result.pagination.total} total trails`);
}

The pagination object contains:

Field	Type	Description
`total`	`number`	Total number of results across all pages
`page`	`number`	Current page number
`perPage`	`number`	Results per page
`pageCount`	`number`	Total number of pages

Link header

Some operations return pagination links as a Link response header. Parse these to navigate to the next page without constructing URLs manually.

<https://app.kosli.com/api/v2/...?page=1&per_page=15>; rel="first",
<https://app.kosli.com/api/v2/...?page=2&per_page=15>; rel="prev",
<https://app.kosli.com/api/v2/...?page=4&per_page=15>; rel="next",
<https://app.kosli.com/api/v2/...?page=10&per_page=15>; rel="last"

The Link header is only present when there are multiple pages. The SDK does not parse this header automatically - access it via the raw response if needed.

Iterating all pages

Fetch pages in a loop until there are no more results:

import { Kosli } from "@kosli/sdk";

const kosli = new Kosli({
  httpBearer: process.env["KOSLI_API_KEY"] ?? "",
});

async function fetchAllTrails(org: string, flowName: string) {
  const allTrails = [];
  let page = 1;
  const perPage = 50;

  while (true) {
    const result = await kosli.trails.list({}, { org, flowName, page, perPage });

    const trails = Array.isArray(result) ? result : result.data ?? [];
    allTrails.push(...trails);

    if (!result.pagination || page >= result.pagination.pageCount) {
      break;
    }
    page++;
  }

  return allTrails;
}

​Request parameters

​Response formats

​Pagination object in the response body

​Link header

​Iterating all pages

Request parameters

Response formats

Pagination object in the response body

Link header

Iterating all pages