> ## Documentation Index
> Fetch the complete documentation index at: https://widgetic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

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

> [!WARNING]
>
> `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:

```json theme={null}
{
  "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:

```typescript theme={null}
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

> [accordion] Use Reasonable Page Sizes
>
> Start with the default (20) or use 50-100 for bulk operations. Avoid requesting single items via pagination.

> [accordion] Cache Total Count
>
> The `total` count is computed on each request. For expensive queries, cache it and only refresh periodically.

> [accordion] Handle Empty Pages
>
> An empty `data` array is valid. Always check `hasNextPage` to determine if more data exists.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.