Pagination

Navigate through large result sets efficiently with cursor-based pagination.

Query Parameters

All list endpoints accept the following pagination parameters:

Parameter	Type	Default	Description
page	integer	1	Page number (1-indexed)
limit	integer	20	Results per page (1-100)
sort	string	created_at	Field to sort by (varies by endpoint)
order	string	desc	Sort direction: `asc` or `desc`

Response Format

Every paginated response includes a pagination object alongside the data array, providing all the information you need to navigate through result pages.

200Paginated response

{
  "success": true,
  "data": [
    "..."
  ],
  "pagination": {
    "total": 142,
    "page": 2,
    "limit": 20,
    "total_pages": 8,
    "has_more": true
  }
}

Pagination Fields

Field	Type	Description
total	integer	Total number of matching records
page	integer	Current page number
limit	integer	Results per page
total_pages	integer	Total number of pages
has_more	boolean	Whether more pages exist after the current one

Iterating All Pages

To fetch all records, loop through pages until has_more is false:

async function fetchAllArticles(apiKey) {
  const articles = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const res = await fetch(
      `https://brainpercent.app/api/v1/articles?page=${page}&limit=100`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );
    const { data, pagination } = await res.json();
    articles.push(...data);
    hasMore = pagination.has_more;
    page++;
  }

  return articles; // All articles
}

Sorting

Each endpoint supports a set of sortable fields. Use the sort and order parameters to control result ordering.

Endpoint	Sort Fields
/api/v1/articles	created_at, updated_at, title
/api/v1/social/content	created_at, updated_at, platform
/api/v1/projects	created_at, updated_at, name

// Get newest articles first (default)
const res = await fetch(
  'https://brainpercent.app/api/v1/articles?sort=created_at&order=desc',
  { headers: { 'Authorization': 'Bearer bp_your_key' } }
);

// Get articles alphabetically
const res2 = await fetch(
  'https://brainpercent.app/api/v1/articles?sort=title&order=asc',
  { headers: { 'Authorization': 'Bearer bp_your_key' } }
);

Combining Filters with Pagination

Filter parameters can be combined with pagination and sorting to narrow down results efficiently:

// Get published articles from a specific project, page 2
const res = await fetch(
  'https://brainpercent.app/api/v1/articles?status=published&project_id=d290f1ee-6c54-4b01-90e6-d701748f0851&page=2&limit=25&sort=updated_at&order=desc',
  { headers: { 'Authorization': 'Bearer bp_your_key' } }
);

Best Practices

Use limit=100 (maximum) when fetching all records to minimize requests
Always check has_more rather than comparing page to total_pages
Add a small delay between page requests to respect rate limits
Cache total counts if you only need them for display purposes
Use filters to reduce result sets before paginating