Home / Pagination and Filtering

Pagination and Filtering

All list endpoints use cursor-based pagination and support resource-specific filters.

Cursor-based pagination

Every list endpoint accepts two parameters:

Parameter Type Default Description
limit integer 20 Number of results per page. Range: 1-100.
cursor string (none) Opaque cursor from a previous response. Omit for the first page.

The response includes a nextCursor field. When nextCursor is null, you have reached the last page.

Example: iterating all pages

# First page
curl "https://api.fractalpack.com/api/v1/items?limit=50" \
  -H "X-Api-Key: fpk_test_..."

# Response includes: { "items": [...], "nextCursor": "eyJpZCI6Iml0bV8..." }

# Next page
curl "https://api.fractalpack.com/api/v1/items?limit=50&cursor=eyJpZCI6Iml0bV8..." \
  -H "X-Api-Key: fpk_test_..."

# Last page: { "items": [...], "nextCursor": null }

Python example

import requests

api_key = "fpk_test_..."
base_url = "https://api.fractalpack.com/api/v1/items"
all_items = []
cursor = None

while True:
    params = {"limit": 100}
    if cursor:
        params["cursor"] = cursor

    resp = requests.get(base_url, headers={"X-Api-Key": api_key}, params=params)
    data = resp.json()
    all_items.extend(data["items"])

    cursor = data.get("nextCursor")
    if cursor is None:
        break

print(f"Total items: {len(all_items)}")

Filtering by endpoint

Items (GET /api/v1/items)

Parameter Type Description
search string Full-text search across item ID and name
category string Filter by item category (exact match)
tags string Comma-separated tag filter. Items must have all specified tags. 
# Search for items with "widget" in their name or ID
curl "https://api.fractalpack.com/api/v1/items?search=widget" \
  -H "X-Api-Key: fpk_test_..."

# Filter by category and tags
curl "https://api.fractalpack.com/api/v1/items?category=electronics&tags=fragile,battery" \
  -H "X-Api-Key: fpk_test_..."

Containers (GET /api/v1/containers)

Parameter Type Description
containerType string Filter by type: Box, Pallet, Equipment
search string Full-text search across container ID and name
tags string Comma-separated tag filter
isActive boolean Filter by active status (true or false) 
# List only active boxes
curl "https://api.fractalpack.com/api/v1/containers?containerType=Box&isActive=true" \
  -H "X-Api-Key: fpk_test_..."

Orders (GET /api/v1/orders)

Parameter Type Description
status string Filter by order status: Draft, Received, Planned, Cancelled 
# List received orders
curl "https://api.fractalpack.com/api/v1/orders?status=Received&limit=25" \
  -H "X-Api-Key: fpk_test_..."

Shipments (GET /api/v1/shipments)

Parameter Type Description
status string Filter by shipment status (e.g., created, optimized, ready)
orderId string Filter shipments belonging to a specific order 
# List shipments for a specific order
curl "https://api.fractalpack.com/api/v1/shipments?orderId=ORD-2026-1234" \
  -H "X-Api-Key: fpk_test_..."

Consolidation groups (GET /api/v1/consolidation/groups)

Parameter Type Description
status string Filter by group status (e.g., pending, packed, dissolved) 
# List active consolidation groups
curl "https://api.fractalpack.com/api/v1/consolidation/groups?status=pending" \
  -H "X-Api-Key: fpk_test_..."

Fulfillment plans (GET /api/v1/fulfillment-plans)

Parameter Type Description
status string Filter by plan status 
curl "https://api.fractalpack.com/api/v1/fulfillment-plans?status=ready&limit=10" \
  -H "X-Api-Key: fpk_test_..."

Pagination tips