Pagination

In this guide, we'll look at how to work with paginated responses when querying the IMMUNE API. By default, all responses limit results to 100 records. You can adjust this using the limit parameter, up to a maximum of 1000 records per request. If you're using one of our official SDKs, pagination is handled automatically.

How pagination works

When an API response returns a list of objects (like sensors or predictions), pagination is supported. In paginated responses:

Objects are nested in a data attribute
The response includes a has_more flag indicating if there are more records
Use starting_after and ending_before parameters for cursor-based navigation
The total_count field shows the total number of available records

Example using cursors

Here's how to paginate through sensor readings:

# First page of results
curl https://api.immune.dev/v1/sensors/readings \
  -H "Authorization: Bearer {token}" \
  -d limit=100

# Get next page using the last record's ID
curl https://api.immune.dev/v1/sensors/readings \
  -H "Authorization: Bearer {token}" \
  -d limit=100 \
  -d starting_after="reading_xyz789"

The response will look like this:

{
  "data": [
    {
      "id": "reading_abc123",
      "sensor_id": "pump_001",
      "value": 23.4,
      "timestamp": "2024-01-20T15:30:00Z"
    },
    // ... more readings
  ],
  "has_more": true,
  "total_count": 1850
}

Using the SDKs

Our SDKs provide convenient methods for handling pagination:

import { ImmuneClient } from '@immune/api'

const client = new ImmuneClient('your-api-key')

// Automatic pagination
const allReadings = await client.sensors.readings.list({
  limit: 100,
  sensor_id: 'pump_001',
  auto_paginate: true
})

// Manual pagination
let lastId = null
while (true) {
  const page = await client.sensors.readings.list({
    limit: 100,
    starting_after: lastId
  })
  
  // Process the current page
  processReadings(page.data)
  
  if (!page.has_more) break
  lastId = page.data[page.data.length - 1].id
}

Time-based filtering

When working with sensor data, you can combine pagination with time-based filters:

curl https://api.immune.dev/v1/sensors/readings \
  -H "Authorization: Bearer {token}" \
  -d limit=100 \
  -d start_time="2024-01-01T00:00:00Z" \
  -d end_time="2024-01-31T23:59:59Z"

This helps you efficiently retrieve historical data while maintaining manageable response sizes.