Skip to main content

​
Overview

List endpoints return paginated results to improve performance and reduce payload sizes. The API uses offset-based pagination with page numbers.

​
Pagination Parameters

ParameterTypeDefaultMaxDescription
pageinteger1-Page number to retrieve
limitinteger50100Items per page

​
Response Format

Paginated responses include metadata about the current page and total results: 
{
  "data": [...],
  "meta": {
    "version": "v1",
    "pagination": {
      "currentPage": 1,
      "totalPages": 5,
      "totalCount": 237,
      "hasNextPage": true,
      "hasPreviousPage": false
    }
  }
}
​
currentPage
integer
The current page number
​
totalPages
integer
Total number of pages available
​
totalCount
integer
Total number of items across all pages
​
hasNextPage
boolean
Whether there are more pages after this one
​
hasPreviousPage
boolean
Whether there are pages before this one

​
Making Paginated Requests

# First page
curl "https://api.inspecto.com/api/third-party/v1/vehicles?page=1&limit=50" \
  -H "Authorization: Bearer $API_KEY"

# Second page
curl "https://api.inspecto.com/api/third-party/v1/vehicles?page=2&limit=50" \
  -H "Authorization: Bearer $API_KEY"

​
Iterating Through All Pages

async function fetchAllVehicles() {
  const allVehicles = [];
  let page = 1;
  let hasMore = true;
  
  while (hasMore) {
    const response = await client.get('/vehicles', {
      params: { page, limit: 100 }
    });
    
    allVehicles.push(...response.data.data);
    hasMore = response.data.meta.pagination.hasNextPage;
    page++;
    
  }
  
  return allVehicles;
}

​
Best Practices

Request the maximum number of items (100) per page to minimize API calls.
// Good: Fewer requests
const response = await client.get('/vehicles', {
  params: { limit: 100 }
});

// Bad: More requests needed
const response = await client.get('/vehicles', {
  params: { limit: 10 }
});
Use filters to reduce the total number of items before paginating.
const response = await client.get('/vehicles', {
  params: {
    status: 'OK',
    type: 'TRACTOR_UNIT',
    limit: 100
  }
});
Data may change between page requests. Handle potential inconsistencies.
async function fetchPageSafely(page) {
  try {
    return await client.get('/vehicles', {
      params: { page, limit: 100 }
    });
  } catch (error) {
    if (error.response?.status === 404) {
      // Page no longer exists, data changed
      return null;
    }
    throw error;
  }
}
For very large datasets, process pages as they arrive instead of loading all into memory.
async function* streamVehicles() {
  let page = 1;
  let hasMore = true;
  
  while (hasMore) {
    const response = await client.get('/vehicles', {
      params: { page, limit: 100 }
    });
    
    yield* response.data.data;
    hasMore = response.data.meta.pagination.hasNextPage;
    page++;
  }
}

// Usage
for await (const vehicle of streamVehicles()) {
  await processVehicle(vehicle);
}

​
Pagination with Filters

Filters are preserved across pages: 
// All pages will include the same filters
const params = {
  status: 'OK',
  type: 'TRACTOR_UNIT',
  limit: 100
};

// Page 1
const page1 = await client.get('/vehicles', { params: { ...params, page: 1 } });

// Page 2 with same filters
const page2 = await client.get('/vehicles', { params: { ...params, page: 2 } });

​
Performance Tips

Parallel Requests

Fetch multiple pages in parallel if order doesn’t matter

Cache Results

Cache paginated results to avoid redundant requests

Monitor Total Count

Track totalCount to detect when data changes

Optimize Page Size

Use appropriate page sizes for your use case

​
Example: Parallel Page Fetching

async function fetchPagesInParallel(totalPages) {
  const pageNumbers = Array.from({ length: totalPages }, (_, i) => i + 1);
  
  const results = await Promise.all(
    pageNumbers.map(page =>
      client.get('/vehicles', {
        params: { page, limit: 100 }
      })
    )
  );
  
  return results.flatMap(r => r.data.data);
}

// Usage
const firstPage = await client.get('/vehicles', { params: { limit: 100 } });
const totalPages = firstPage.data.meta.pagination.totalPages;

if (totalPages > 1) {
  const allVehicles = await fetchPagesInParallel(totalPages);
}