Pagination

Learn how pagination works in the Lia API - request parameters, response structure, Link headers, and best practices.

All list endpoints in the Lia API support pagination to help you efficiently retrieve large datasets. We use an enhanced hybrid pagination approach that combines pagination metadata in the response body with RFC 8288 Link headers for easy navigation.

Overview

Paginated endpoints return results in a consistent format with:

• Response Body: Contains data array and detailed pagination metadata

• Link Headers: Provides navigation URLs for first, previous, next, and last pages

Request Parameters

Use these query parameters to control pagination:

Parameter	Type	Default	Max	Description
page	integer	1	-	Page number to retrieve (1-indexed)
per_page	integer	50	100	Number of items per page

Response Structure

All paginated endpoints return responses in this format:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total_count": 150,
    "total_pages": 3,
    "has_next_page": true,
    "has_previous_page": false
  }
}

Pagination Metadata Fields

Field	Type	Description
page	integer	Current page number (1-indexed)
per_page	integer	Number of items per page
total_count	integer	Total number of items across all pages
total_pages	integer	Total number of pages available
has_next_page	boolean	Whether a next page is available
has_previous_page	boolean	Whether a previous page is available

Link Headers

In addition to the response body, paginated endpoints include RFC 8288 compliant Link headers for easy navigation:

Link: </translate/contexts?page=2&per_page=50>; rel="next",
      </translate/contexts?page=1&per_page=50>; rel="first",
      </translate/contexts?page=3&per_page=50>; rel="last",
      </translate/contexts?page=1&per_page=50>; rel="prev"

Link Relations

Relation	Description
first	URL to the first page
prev	URL to the previous page (omitted on first page)
next	URL to the next page (omitted on last page)
last	URL to the last page

Examples

Basic Pagination Request

Retrieve the first page with default settings (50 items):

curl -X GET "https://api.acolad.ai/translate/contexts" \
  -H "x-api-key: YOUR_API_KEY"

Custom Page Size

Retrieve 25 items per page:

curl -X GET "https://api.acolad.ai/translate/contexts?per_page=25" \
  -H "x-api-key: YOUR_API_KEY"

Specific Page

Retrieve page 3:

curl -X GET "https://api.acolad.ai/translate/contexts?page=3&per_page=50" \
  -H "x-api-key: YOUR_API_KEY"

Response Example

{
  "data": [
    {
      "id": "ctx_abc123",
      "name": "Marketing Glossary",
      "description": "Terms for marketing content",
      "assetType": "glossary",
      "isShared": true,
      "owner": {
        "id": "user_456",
        "name": "John Doe",
        "email": "[email protected]",
        "image": "https://..."
      },
      "createdAt": "2025-12-01T10:00:00Z",
      "updatedAt": "2025-12-03T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total_count": 150,
    "total_pages": 3,
    "has_next_page": true,
    "has_previous_page": false
  }
}

Code Examples

JavaScript

async function getAllContexts(apiKey: string) {
  const allContexts = [];
  let page = 1;
  let hasNextPage = true;

  while (hasNextPage) {
    const response = await fetch(
      `https://api.acolad.ai/translate/contexts?page=${page}&per_page=50`,
      {
        headers: {
          'x-api-key': apiKey
        }
      }
    );

    const result = await response.json();
    allContexts.push(...result.data);

    hasNextPage = result.pagination.has_next_page;
    page++;
  }

  return allContexts;
}

Python

Using Link Headers

async function getNextPage(apiKey: string, currentUrl: string) {
  const response = await fetch(currentUrl, {
    headers: {
      'x-api-key': apiKey
    }
  });

  // Parse Link header to get next page URL
  const linkHeader = response.headers.get('Link');
  const nextLink = linkHeader
    ?.split(',')
    .find(link => link.includes('rel="next"'));

  const nextUrl = nextLink
    ?.match(/<([^>]+)>/)?.[1];

  return {
    data: await response.json(),
    nextUrl
  };
}

Error Handling

Invalid Page Number

If you request a page number that exceeds the total pages (and results exist), you'll receive a 400 Bad Request error:

{
  "code": "BAD_REQUEST",
  "message": "Page number 5 exceeds total pages (3)",
  "status": 400
}

Invalid Parameters

Invalid pagination parameters return validation errors:

{
  "code": "BAD_REQUEST",
  "message": "Page must be at least 1",
  "status": 400
}

{
  "code": "BAD_REQUEST",
  "message": "Limit cannot exceed 100",
  "status": 400
}

Empty Results

When no results exist, you'll receive a successful response with empty data:

{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total_count": 0,
    "total_pages": 0,
    "has_next_page": false,
    "has_previous_page": false
  }
}