Sorting and Pagination: Navigating Large Datasets

Sorting basics

Use the sort query parameter to order your results by any column. By default, sorting is ascending (A→Z, 0→9, oldest→newest).

Sort products by name (A to Z):

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://csv-api.com/api/v1/datasets/YOUR_ID/records?sort=name"

Descending order

Prefix the column name with a minus sign (-) to sort in descending order (Z→A, 9→0, newest→oldest).

Sort by price, highest first:

?sort=-price

Sort by date, most recent first:

?sort=-created_date

Multi-column sorting

Separate multiple sort columns with commas. The first column is the primary sort; subsequent columns break ties.

Sort by category (A-Z), then by price (highest first) within each category:

?sort=category,-price

This would return all Electronics sorted by price descending, then all Furniture sorted by price descending, and so on.

Pagination

Results are automatically paginated. The default page size is 25, and the maximum is 100. Use the page and per_page parameters to control pagination.

Get the second page with 50 records per page:

?page=2&per_page=50

Reading pagination metadata

Every response includes a meta object with pagination details:

{
  "data": [...],
  "meta": {
    "total": 1247,
    "page": 3,
    "per_page": 50,
    "total_pages": 25
  }
}

Iterating through all pages

To fetch all records from a large dataset, loop through pages until you've reached the last one. Here's a pattern in JavaScript:

async function fetchAllRecords(baseUrl, apiKey) {
  let allRecords = [];
  let page = 1;
  let totalPages = 1;

  while (page <= totalPages) {
    const response = await fetch(
      `${baseUrl}?page=${page}&per_page=100`,
      { headers: { "Authorization": `Bearer ${apiKey}` } }
    );
    const json = await response.json();

    allRecords = allRecords.concat(json.data);
    totalPages = json.meta.total_pages;
    page++;
  }

  return allRecords;
}

Combining sorting, filtering, and pagination

All query features work together seamlessly. Here's an example that filters, sorts, and paginates in a single request:

Get page 2 of in-stock electronics, sorted by price (lowest first), 10 per page:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://csv-api.com/api/v1/datasets/YOUR_ID/records?\
filter[category]=Electronics&\
filter[in_stock]=true&\
sort=price&\
page=2&\
per_page=10"