Pagination

List endpoints in the Temps API are paginated, either by page number or by an opaque cursor. Most page-based endpoints take page and page_size (default 20, maximum 100); the project and deployment lists take page and per_page (default 10, maximum 100). To fetch everything, keep requesting the next page until you have total items, or until a cursor endpoint stops returning a cursor.

Page-based pagination

Page numbers start at 1. The page-size parameter name and the response shape depend on the endpoint, so check the endpoint in the OpenAPI spec at /api/docs on your instance.

Parameters

Name
page
Type
integer
Description
The page number to retrieve (1-indexed). Defaults to 1.
Name
page_size
Type
integer
Description
Items per page on endpoints that use the shared pagination parameters (for example webhooks, error tracking, backups and teams). Defaults to 20; values are clamped to 1–100.
Name
per_page
Type
integer
Description
Items per page on the project and deployment lists. Defaults to 10, must be between 1 and 100 (the project list rejects other values with 400).

Response metadata

The project list returns its items under projects, and the deployment list under deployments, alongside:

Name
total
Type
integer
Description
The total number of items across all pages.
Name
page
Type
integer
Description
The current page number.
Name
per_page
Type
integer
Description
The number of items per page.

Other endpoints wrap results differently. Error tracking lists, for example, return data plus a pagination object with page, page_size, total_count and total_pages.

Paginated request

curl -G https://your-temps-instance.com/api/projects \
  -H "Authorization: Bearer tk_your_api_key" \
  -d page=2 \
  -d per_page=10

Paginated response

{
  "projects": [
    {
      "id": 11,
      "name": "my-app",
      "slug": "my-app"
    },
    {
      "id": 12,
      "name": "api-service",
      "slug": "api-service"
    }
  ],
  "total": 25,
  "page": 2,
  "per_page": 10
}

Iterate every page

Request pages in order until you have collected total items (or a page comes back empty). This loop fetches every project 100 at a time:

Page-number loop

const base = 'https://your-temps-instance.com/api'
const headers = { Authorization: `Bearer ${process.env.TEMPS_API_KEY}` }

const projects = []
for (let page = 1; ; page++) {
  const res = await fetch(`${base}/projects?page=${page}&per_page=100`, { headers })
  const body = await res.json()
  projects.push(...body.projects)
  if (body.projects.length === 0 || page * body.per_page >= body.total) break
}

If items are created while you iterate, page boundaries can shift. For a consistent snapshot, iterate quickly or de-duplicate by id.

Sorting

Most list endpoints return the newest items first. Where an endpoint supports other sort orders, the parameters are listed in its OpenAPI entry at /api/docs.

Cursor-based pagination

Endpoints that return large datasets, such as blob storage listing and log search, use an opaque cursor instead of page numbers. Pass the cursor from one response as the cursor query parameter of the next request, and stop when no cursor comes back.

Parameters

Name
cursor
Type
string
Description
An opaque continuation token from the previous response. Omit for the first request.
Name
limit
Type
integer
Description
Maximum number of items to return (varies by endpoint).

The field that carries the next cursor differs by endpoint: blob listing (GET /api/blob) returns cursor and hasMore; log search returns next_cursor, which is null on the last page.

Blob listing response

{
  "blobs": [
    {
      "pathname": "images/logo.png",
      "size": 15234,
      "contentType": "image/png"
    }
  ],
  "cursor": "eyJrZXkiOiJpbWFnZXMvbG9nby5wbmcifQ==",
  "hasMore": true
}

Cursor loop (blob listing)

const blobs = []
let cursor: string | undefined
do {
  const params = new URLSearchParams({ project_id: '1', limit: '100' })
  if (cursor) params.set('cursor', cursor)
  const res = await fetch(`${base}/blob?${params}`, { headers })
  const body = await res.json()
  blobs.push(...body.blobs)
  cursor = body.hasMore ? body.cursor : undefined
} while (cursor)

SDK usage

The Node SDK passes pagination through the query option and returns the response body as data:

Node SDK

import { TempsClient } from '@temps-sdk/node-sdk';

const client = new TempsClient({
  baseUrl: 'https://your-temps-instance.com',
  apiKey: 'your-api-key'
});

// Fetch page 1 of projects
const { data } = await client.projects.list({
  query: { page: 1, per_page: 20 }
});

console.log(`Showing ${data.projects.length} of ${data.total} projects`);