Pagination

Navigate large result sets with offset-based pagination

The PartsSource APIs use offset-based pagination for list and search endpoints. This provides predictable result ordering and consistent navigation through large datasets.

---

Request Format

Include pagination parameters in the request body for POST search endpoints:

{
  "filters": {
    "email": "[email protected]"
  },
  "pagination": {
    "limit": 50,
    "offset": 0
  }
}

---

GET Search Endpoints

GET search endpoints (e.g., /manufacturers/search, /users/search) use query parameter pagination instead of a request body. Pagination parameters are passed as URL query parameters alongside the q search query:

GET /orders/search?q=status:"Pending"&limit=25&offset=0

Parameter	Default	Constraints
limit	50	1–100
offset	0	>= 0

GET search endpoints have a lower maximum limit of 100 compared to POST search endpoints (up to 10,000). Use filters in the q parameter to narrow results.

The response shape is the same — results in data.items with a data.pagination object:

{
  "data": {
    "items": [ ... ],
    "pagination": {
      "total": 142,
      "limit": 25,
      "offset": 0,
      "hasMore": true
    }
  }
}

For the full query syntax, operators, and field references, see Search Query Language.

---

Pagination Parameters

Parameter	Type	Default	Range	Description
limit	integer	50	1-10,000	Maximum records to return
offset	integer	0	0+	Number of records to skip

The maximum limit per page is 500 records.

---

Response Format

Paginated responses include metadata alongside the results:

{
  "success": true,
  "data": {
    "customers": [
      {"contactId": 1, "firstName": "John", "lastName": "Doe"},
      {"contactId": 2, "firstName": "Jane", "lastName": "Smith"}
    ],
    "pagination": {
      "total": 150,
      "limit": 50,
      "offset": 0,
      "hasMore": true
    }
  },
  "correlationId": "0HN7QJKV3QJ8K:00000001",
  "timestamp": "2025-10-21T14:30:00.000Z"
}

Response Metadata

Field	Type	Description
total	integer	Total records matching the query
limit	integer	Page size used
offset	integer	Records skipped
hasMore	boolean	true if more pages exist

---

Navigating Pages

Example: Fetching All Pages

# First page (records 0-49)
{"pagination": {"limit": 50, "offset": 0}}
# Response: total=150, hasMore=true

# Second page (records 50-99)
{"pagination": {"limit": 50, "offset": 50}}
# Response: total=150, hasMore=true

# Third page (records 100-149)
{"pagination": {"limit": 50, "offset": 100}}
# Response: total=150, hasMore=false

Code Example

public async IAsyncEnumerable<Customer> GetAllCustomers(CustomerSearchFilters filters)
{
    int offset = 0;
    const int pageSize = 100;
    bool hasMore = true;

    while (hasMore)
    {
        var request = new CustomerSearchRequest
        {
            Filters = filters,
            Pagination = new PaginationRequest
            {
                Limit = pageSize,
                Offset = offset
            }
        };

        var response = await _apiClient.SearchCustomers(request);

        foreach (var customer in response.Data.Customers)
        {
            yield return customer;
        }

        hasMore = response.Data.Pagination.HasMore;
        offset += pageSize;
    }
}

---

Validation & Normalization

Invalid pagination values are automatically corrected:

Input	Normalized To	Reason
limit: 50000	limit: 10000	Exceeds maximum
limit: -5	limit: 50	Below minimum (uses default)
offset: -10	offset: 0	Cannot be negative

The API silently normalizes values rather than returning an error. Always check the pagination object in the response to see what values were actually used.

---

Performance Considerations

Large Offsets

For very large result sets, performance may degrade with high offset values:

Offset Range	Performance
0 - 10,000	Excellent
10,000 - 100,000	Good
100,000+	May be slower

Recommendations for large datasets:

1. Use filters to reduce the result set size

2. Use keyset pagination for sequential processing (if supported)

3. Cache results when possible

4. Process incrementally rather than loading all data at once

Efficient Pagination Patterns

// Good: Use filters to reduce result set
var request = new CustomerSearchRequest
{
    Filters = new { status = "active", createdAfter = "2024-01-01" },
    Pagination = new { limit = 100 }
};

// Avoid: Fetching all records with no filters
var request = new CustomerSearchRequest
{
    Pagination = new { limit = 10000 }  // May be slow
};

---

Complete Request Example

cURL

curl -X POST https://api.partssource.com/customer/api/users/search \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "emailContains": "@hospital.org",
      "lastName": "Smith"
    },
    "pagination": {
      "limit": 25,
      "offset": 0
    }
  }'

Response

{
  "success": true,
  "data": {
    "users": [
      {
        "id": 12345,
        "userName": "asmith",
        "email": "[email protected]",
        "firstName": "Alice",
        "lastName": "Smith",
        "companies": [...]
      },
      {
        "id": 12346,
        "userName": "bsmith",
        "email": "[email protected]",
        "firstName": "Bob",
        "lastName": "Smith",
        "companies": [...]
      }
    ],
    "pagination": {
      "total": 47,
      "limit": 25,
      "offset": 0,
      "hasMore": true
    }
  },
  "correlationId": "0HN7QJKV3QJ8K:00000002",
  "timestamp": "2025-10-21T14:35:00.000Z"
}

---

TypeScript Helper

interface PaginatedResponse<T> {
  data: T[];
  pagination: {
    total: number;
    limit: number;
    offset: number;
    hasMore: boolean;
  };
}

async function* fetchAllPages<T>(
  fetchPage: (offset: number, limit: number) => Promise<PaginatedResponse<T>>,
  pageSize = 100
): AsyncGenerator<T> {
  let offset = 0;
  let hasMore = true;

  while (hasMore) {
    const response = await fetchPage(offset, pageSize);

    for (const item of response.data) {
      yield item;
    }

    hasMore = response.pagination.hasMore;
    offset += pageSize;
  }
}

// Usage
for await (const customer of fetchAllPages(
  (offset, limit) => api.searchCustomers({ pagination: { offset, limit } })
)) {
  console.log(customer.firstName);
}