Data Navigation

Pagination

Navigate large datasets efficiently. Use cursor-based pagination for real-time data or offset pagination for jumping to specific pages.

Cursor-Based

Recommended

Consistent with real-time data changes
O(1) performance regardless of offset
No duplicate/missing items on page change

Offset-Based

Jump to any page directly
Simple page number display
Performance degrades at high offsets

Interactive Demo

Valuation History

ID	Item	Valuation	Date
val_K7j9	Louis Vuitton Neverfull MM	$1,450-$1,850	2024-01-15
val_L8k0	Chanel Classic Flap Medium	$5,200-$6,100	2024-01-15
val_M9l1	Hermès Birkin 30	$12,500-$15,000	2024-01-14
val_N0m2	Rolex Submariner Date	$9,800-$11,200	2024-01-14
val_O1n3	Gucci Dionysus Small	$1,100-$1,350	2024-01-13

Showing 1-5 of 1,523 results

Code Examples

Cursor-BasedRecommended

# Cursor-based pagination (recommended)
curl "https://api.justkalm.com/v2/valuations?limit=25" \
  -H "Authorization: Bearer jk_live_xxx"

# Response includes cursor for next page
{
  "data": [...],
  "has_more": true,
  "next_cursor": "eyJpZCI6InZhbF9LN2o5In0=",
  "prev_cursor": null
}

# Get next page using cursor
curl "https://api.justkalm.com/v2/valuations?limit=25&cursor=eyJpZCI6InZhbF9LN2o5In0=" \
  -H "Authorization: Bearer jk_live_xxx"

Offset-Based

# Offset-based pagination
curl "https://api.justkalm.com/v2/valuations?limit=25&offset=50" \
  -H "Authorization: Bearer jk_live_xxx"

# Response includes pagination metadata
{
  "data": [...],
  "pagination": {
    "total": 1523,
    "limit": 25,
    "offset": 50,
    "has_more": true
  }
}

SDK Auto-Pagination

import { JustKalm } from '@justkalm/sdk';

const client = new JustKalm({ apiKey: 'jk_live_xxx' });

// Auto-paginate through all results
for await (const valuation of client.valuations.list()) {
  console.log(valuation.id, valuation.price_min);
}

// Or get a single page
const page = await client.valuations.list({ limit: 25 });
console.log(`Got ${page.data.length} of ${page.total}`);

// Get next page
if (page.hasMore) {
  const nextPage = await page.nextPage();
}

Sorting

# Sort by multiple fields
curl "https://api.justkalm.com/v2/valuations?\
sort=-created_at,+price_min&\
limit=25" \
  -H "Authorization: Bearer jk_live_xxx"

# Sort direction prefixes:
# + ascending (default if omitted)
# - descending

# Available sort fields:
# created_at, updated_at, price_min, price_max, brand, category

Query Parameters

Parameter	Type	Default	Description
limit	integer	25	Number of results per page (1-100)
cursor	string	null	Opaque cursor for next/prev page
offset	integer	0	Number of results to skip (offset mode)
sort	string	-created_at	Sort field(s) with +/- prefix
order	string	desc	Default sort order: asc or desc

Best Practices

Use Cursors for Feeds

For real-time feeds where new items are added frequently, cursor pagination prevents duplicates and missed items.

Limit Page Size

Smaller page sizes (25-50) provide faster responses. Only request 100 if displaying all at once.

Avoid Deep Offsets

Offset pagination slows down beyond page 100. Use cursor pagination or narrow with filters.

Cache Cursor Tokens

Store cursor tokens client-side for back navigation. They're valid for 24 hours.

Ready to Paginate?

All list endpoints support both pagination modes. Try it in the playground.

API Playground API Reference