Docs API ReferencePagination and Filtering

Pagination and Filtering

Navigate large result sets using cursor-based pagination and filter API responses.

beginner

5 min read

LightYear Docs Team

Updated April 24, 2026

apipaginationfilteringcursor

The LightYear API uses cursor-based pagination for list endpoints. This guide explains how to navigate large result sets efficiently.

Default Pagination

List endpoints return up to 100 items per page by default. The response includes a meta object with pagination links:

>_BASH

$curl "https://api.lightyear.host/v1/servers?per_page=25" \
$  -H "Authorization: Bearer YOUR_API_KEY"

OUTPUT

{
  "servers": [...],
  "meta": {
    "total": 87,
    "links": {
      "next": "https://api.lightyear.host/v1/servers?cursor=eyJpZCI6MTAwfQ",
      "prev": null
    }
  }
}

Navigate Pages

Use the cursor parameter from the next link to get the next page:

>_BASH

$curl "https://api.lightyear.host/v1/servers?cursor=eyJpZCI6MTAwfQ&per_page=25" \
$  -H "Authorization: Bearer YOUR_API_KEY"

Iterate All Pages (Python)

PYTHON

import requests

def get_all_servers(api_key):
    servers = []
    url = "https://api.lightyear.host/v1/servers"
    headers = {"Authorization": f"Bearer {api_key}"}
    params = {"per_page": 100}
    
    while url:
        response = requests.get(url, headers=headers, params=params)
        data = response.json()
        servers.extend(data["servers"])
        
        next_link = data["meta"]["links"].get("next")
        url = next_link
        params = {}  # cursor is already in the next URL
    
    return servers

Filter Results

Many list endpoints support filtering:

>_BASH

$# Filter servers by label
$curl "https://api.lightyear.host/v1/servers?label=web" \
$  -H "Authorization: Bearer YOUR_API_KEY"
$
$# Filter by region
$curl "https://api.lightyear.host/v1/servers?region=sgp-01" \
$  -H "Authorization: Bearer YOUR_API_KEY"
$
$# Filter by tag
$curl "https://api.lightyear.host/v1/servers?tag=production" \
$  -H "Authorization: Bearer YOUR_API_KEY"

Sort Results

>_BASH

$# Sort by creation date (newest first)
$curl "https://api.lightyear.host/v1/servers?sort=date_created&order=desc" \
$  -H "Authorization: Bearer YOUR_API_KEY"

[!NOTE] The maximum per_page value is 500. Requesting more than 500 items per page returns an error.

Was this article helpful?