Pagination

All list endpoints in the Notiflows API support cursor-based pagination to efficiently navigate through large collections of resources. This pagination method uses cursors (opaque strings) to mark positions in the dataset, allowing you to fetch pages of results in either direction.

How It Works

Cursor-based pagination provides a stable and efficient way to paginate through data. Unlike offset-based pagination, cursors remain stable even as data is added or removed, making them ideal for real-time data that changes frequently.

Query Parameters

All list endpoints accept the following pagination parameters:

Response Format

All paginated responses follow this structure:

{
  "items": [...],
  "page": {
    "limit": 25,
    "after": "cursor_string_for_next_page",
    "before": "cursor_string_for_previous_page",
    "has_more_after": true,
    "has_more_before": false
  }
}

Page Object Properties

The page object in the response contains the following properties:

Examples

Fetching the First Page

To fetch the first page of results, make a request without any pagination parameters:

curl -X GET "https://api.notiflows.com/api/admin/v1/users" \
  -H "x-notiflows-api-key: your-api-key" \
  -H "x-notiflows-secret-key: your-secret-key"

Response:

{
  "items": [
    { "id": "user-1", "external_id": "ext-1", ... },
    { "id": "user-2", "external_id": "ext-2", ... },
    ...
  ],
  "page": {
    "limit": 25,
    "after": "eyJpZCI6InVzZXItMjUifQ==",
    "before": null,
    "has_more_after": true,
    "has_more_before": false
  }
}

Fetching the Next Page

To fetch the next page, use the after cursor from the previous response:

curl -X GET "https://api.notiflows.com/api/admin/v1/users?after=eyJpZCI6InVzZXItMjUifQ==" \
  -H "x-notiflows-api-key: your-api-key" \
  -H "x-notiflows-secret-key: your-secret-key"

Fetching the Previous Page

To go back to the previous page, use the before cursor:

curl -X GET "https://api.notiflows.com/api/admin/v1/users?before=eyJpZCI6InVzZXItMjUifQ==" \
  -H "x-notiflows-api-key: your-api-key" \
  -H "x-notiflows-secret-key: your-secret-key"

Customizing Page Size

You can specify a custom page size using the limit parameter:

curl -X GET "https://api.notiflows.com/api/admin/v1/users?limit=50" \
  -H "x-notiflows-api-key: your-api-key" \
  -H "x-notiflows-secret-key: your-secret-key"

Note: The maximum limit value is 1000. If you specify a value greater than 1000, it will be capped at 1000.

Best Practices

1. Use has_more_after and has_more_before to determine if there are more pages available, rather than checking if after or before are null.

2. Store cursors securely - Cursors are opaque strings and should be treated as sensitive data. They may contain encoded information about the position in your dataset.

3. Handle null cursors gracefully - When after or before are null, it means there are no more items in that direction.

4. Use appropriate page sizes - Smaller page sizes (25-50) are recommended for better performance and user experience. Only use larger page sizes when necessary.

5. Don't modify cursors - Cursors are generated by the API and should be used exactly as returned. Modifying them may result in unexpected behavior.

Pagination with Filters

Pagination works seamlessly with filtering parameters. When you apply filters, pagination will only apply to the filtered results:

curl -X GET "https://api.notiflows.com/api/admin/v1/deliveries?status=sent&limit=50&after=cursor_string" \
  -H "x-notiflows-api-key: your-api-key" \
  -H "x-notiflows-secret-key: your-secret-key"

The pagination cursors will maintain their position relative to the filtered dataset, so you can paginate through filtered results just like unfiltered results.

Error Handling

If you provide an invalid cursor (e.g., from a different query or an expired cursor), the API will return a 400 Bad Request error. In this case, you should start pagination from the beginning by making a request without cursor parameters.