Pagination

The IPO API supports pagination to help you efficiently retrieve large datasets. All list endpoints return paginated results with metadata to help you navigate through the data.

How Pagination Works

The API follows standard pagination conventions using page and limit query parameters:

page: The page number to retrieve (starts from 1)
limit: The number of results per page (default: 3, max varies by plan)

Basic Usage

Get First Page

curl -H "x-api-key: YOUR_API_KEY" \
     "https://api.ipoalerts.in/ipos?status=open&limit=3&page=1"

Get Subsequent Pages

# Get the next 3 IPOs
curl -H "x-api-key: YOUR_API_KEY" \
     "https://api.ipoalerts.in/ipos?status=open&limit=3&page=2"

# Get the next 3 IPOs after that
curl -H "x-api-key: YOUR_API_KEY" \
     "https://api.ipoalerts.in/ipos?status=open&limit=3&page=3"

Response Structure

Every paginated response includes a meta object with pagination information:

{
  "meta": {
    "count": 10,
    "countOnPage": 3,
    "totalPages": 4,
    "page": 1,
    "limit": 3
  },
  "ipos": [
    // ... IPO objects
  ]
}

Meta Fields Explained

Field	Type	Description
`count`	number	Total number of IPOs matching your query
`countOnPage`	number	Number of IPOs returned in current page
`totalPages`	number	Total number of pages available
`page`	number	Current page number
`limit`	number	Number of results per page requested

Pagination Examples

Example 1: 3 IPOs per page

If there are 10 open IPOs and you set limit=3:

page=1: Returns IPOs 1-3, totalPages=4
page=2: Returns IPOs 4-6
page=3: Returns IPOs 7-9
page=4: Returns IPO 10

Example 2: 1 IPO per page

If there are 10 open IPOs and you set limit=1:

page=1: Returns IPO 1, totalPages=10
page=2: Returns IPO 2
page=3: Returns IPO 3
...and so on until page=10

Limitations

Free Plan

Maximum limit: 1 IPO per request
Workaround: You can still get all IPOs by iterating through pages, but it will consume more requests

Paid Plans

Higher limits: Can request more IPOs per page
Efficiency: Fewer requests needed to get all data

Best Practices

1. Always Check Total Pages

const response = await fetch('https://api.ipoalerts.in/ipos?status=open&limit=10&page=1', {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});
const data = await response.json();

console.log(`Total pages: ${data.meta.totalPages}`);
console.log(`Total IPOs: ${data.meta.count}`);

2. Iterate Through All Pages

async function getAllIPOs(status = 'open', limit = 10) {
  const allIPOs = [];
  let currentPage = 1;
  let totalPages = 1;

  do {
    const response = await fetch(
      `https://api.ipoalerts.in/ipos?status=${status}&limit=${limit}&page=${currentPage}`,
      { headers: { 'x-api-key': 'YOUR_API_KEY' } }
    );
    
    const data = await response.json();
    allIPOs.push(...data.ipos);
    
    totalPages = data.meta.totalPages;
    currentPage++;
  } while (currentPage <= totalPages);

  return allIPOs;
}

3. Handle Edge Cases

// Check if there are more pages
if (data.meta.page < data.meta.totalPages) {
  console.log('More pages available');
}

// Check if current page is empty
if (data.meta.countOnPage === 0) {
  console.log('No IPOs found on this page');
}

Pagination

On this page