Skip to main content

​
Overview

List endpoints support cursor-based pagination to efficiently retrieve large datasets.

​
How It Works

Cursor-based pagination uses a cursor token to mark your position in the dataset. This allows you to fetch the next page of results without missing or duplicating items.

​
Using Pagination

​
First Page

Make a request without a cursor to get the first page: 
curl -X GET "https://api.precital.com/v1/audio-analyses?limit=20" \
  -H "X-API-Key: your-api-key-here"

​
Next Page

Use the next_cursor from the previous response to fetch the next page: 
curl -X GET "https://api.precital.com/v1/audio-analyses?limit=20&cursor=eyJpZCI6ImFuYV9hYmMxMjNkZWY0NTYiLCJjcmVhdGVkX2F0IjoiMjAyNS0wMS0xNSAxMDozMDowMFoifQ==" \
  -H "X-API-Key: your-api-key-here"

​
Response Format

Paginated responses include a meta object with pagination information: 
{
  "data": [
    {
      "id": "ana_abc123def456",
      "status": "completed",
      ...
    }
  ],
  "meta": {
    "next_cursor": "eyJpZCI6ImFuYV9hYmMxMjNkZWY0NTYiLCJjcmVhdGVkX2F0IjoiMjAyNS0wMS0xNSAxMDozMDowMFoifQ=="
  }
}
When next_cursor is null, you’ve reached the last page.

​
Parameters

ParameterTypeDefaultMaxDescription
cursorstringnull-Cursor token from previous response
limitinteger20100Number of items per page

​
Example Implementation

async function fetchAllAnalyses(apiKey) {
  const allAnalyses = [];
  let cursor = null;
  
  do {
    const url = cursor 
      ? `https://api.precital.com/v1/audio-analyses?limit=100&cursor=${cursor}`
      : 'https://api.precital.com/v1/audio-analyses?limit=100';
    
    const response = await fetch(url, {
      headers: {
        'X-API-Key': apiKey
      }
    });
    
    const data = await response.json();
    allAnalyses.push(...data.data);
    cursor = data.meta.next_cursor;
  } while (cursor !== null);
  
  return allAnalyses;
}

​
Best Practices

  • Use appropriate page sizes: Choose a limit that balances performance and number of requests
  • Handle null cursors: Check if next_cursor is null to know when to stop
  • Store cursors: If you need to resume pagination, store the cursor token
  • Respect rate limits: Don’t paginate too aggressively to avoid hitting rate limits