Pagination

How pagination works in the Widgetic API

List endpoints in the Widgetic API page their results, so large datasets stay efficient to read. Each endpoint’s reference page says which of the parameters below it accepts.

​

Request Parameters

Parameter	Type	Default	Max	Description
page	integer	1	-	Page number (1-indexed)
size	integer	20	100	Number of items per page
sort	string	varies	-	Sort field and direction, on the lists that take it

​

Example Request

curl -X GET "https://api.widgetic.com/v1/widgets?page=2&size=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /widgets returns the whole list when you pass neither page nor size. For an account with many widgets that response can be cut short, and nothing in it says so. Always page it when you do not know how many widgets an account holds.

​

Response Format

Paginated responses include a meta object with pagination details:

{
  "success": true,
  "data": [
    { "id": "...", "name": "Widget 1" },
    { "id": "...", "name": "Widget 2" }
  ],
  "meta": {
    "page": 2,
    "size": 50,
    "total": 150,
    "limit": 50,
    "offset": 50,
    "hasNextPage": true,
    "hasPreviousPage": true
  }
}

​

Meta Fields

Field	Type	Description
page	integer	Current page number
size	integer	Items per page
total	integer	Total number of items
limit	integer	Same as size
offset	integer	Number of items skipped
hasNextPage	boolean	Whether more pages exist after this one
hasPreviousPage	boolean	Whether pages exist before this one

​

Sorting

Some list endpoints take a sort parameter. GET /widgets does not: it is always newest first. Where it is accepted, use the format field:direction:

• Ascending: sort=created_at:asc
• Descending: sort=created_at:desc

​

Common Sort Fields

Field	Description
created_at	Creation timestamp
updated_at	Last update timestamp
name	Alphabetical by name

​

SDK Example

Using the TypeScript SDK:

import { WidgetsApi } from '@widgetic/api-sdk-ts';

const widgets = new WidgetsApi('YOUR_API_KEY');

// Fetch page 2 with 50 items
const { data, meta } = await widgets.getWidgets({
  page: 2,
  size: 50
});

console.log(`Page ${meta?.page} of ${Math.ceil((meta?.total ?? 0) / (meta?.size ?? 1))}`);
console.log(`Showing ${data.length} of ${meta?.total} items`);

// Iterate through all pages
async function* getAllWidgets() {
  let page = 1;
  let hasMore = true;
  
  while (hasMore) {
    const { data, meta } = await widgets.getWidgets({ page, size: 100 });
    yield* data;
    hasMore = meta?.hasNextPage ?? false;
    page++;
  }
}

for await (const widget of getAllWidgets()) {
  console.log(widget.name);
}

​

Best Practices

Use Reasonable Page Sizes

Start with the default (20) or use 50-100 for bulk operations. Avoid requesting single items via pagination.

Cache Total Count

The total count is computed on each request. For expensive queries, cache it and only refresh periodically.

Handle Empty Pages

An empty data array is valid. Always check hasNextPage to determine if more data exists.