Pagination

Navigate through large result sets

When an API response contains more results than can be returned at once, use pagination to retrieve all pages of data.

---

How pagination works

1. Make your initial request with max_results
2. Check the response for a next_token in the meta object
3. If present, make another request with that token as pagination_token
4. Repeat until no next_token is returned

# Initial request
curl "https://api.x.com/2/users/12345/tweets?max_results=100" \
  -H "Authorization: Bearer $TOKEN"

# Response includes next_token
# {"data": [...], "meta": {"next_token": "abc123", ...}}

# Next page
curl "https://api.x.com/2/users/12345/tweets?max_results=100&pagination_token=abc123" \
  -H "Authorization: Bearer $TOKEN"

---

Pagination tokens

Token	Description
next_token	In response meta. Use to get the next page.
previous_token	In response meta. Use to go back a page.
pagination_token	Request parameter. Set to next_token or previous_token value.

---

Response structure

{
  "data": [
    {"id": "1234", "text": "..."},
    {"id": "1235", "text": "..."}
  ],
  "meta": {
    "result_count": 100,
    "next_token": "7140w9gefhslx3",
    "previous_token": "77qp89slxjd"
  }
}

When there are no more results, next_token is omitted:

{
  "data": [...],
  "meta": {
    "result_count": 42,
    "previous_token": "77qp89abc"
  }
}

---

Pagination parameters

Parameter	Description	Default
max_results	Results per page	Endpoint-specific
pagination_token	Token from previous response	None

Check each endpoint’s API reference for specific max_results limits.

---

Example: Paginating through all results

Python

import requests

def get_all_tweets(user_id, bearer_token):
    url = f"https://api.x.com/2/users/{user_id}/tweets"
    headers = {"Authorization": f"Bearer {bearer_token}"}
    params = {"max_results": 100}
    
    all_tweets = []
    
    while True:
        response = requests.get(url, headers=headers, params=params)
        data = response.json()
        
        if "data" in data:
            all_tweets.extend(data["data"])
        
        # Check for next page
        next_token = data.get("meta", {}).get("next_token")
        if not next_token:
            break
            
        params["pagination_token"] = next_token
    
    return all_tweets

JavaScript

async function getAllTweets(userId, bearerToken) {
  const url = `https://api.x.com/2/users/${userId}/tweets`;
  const headers = { Authorization: `Bearer ${bearerToken}` };
  
  let allTweets = [];
  let paginationToken = null;
  
  do {
    const params = new URLSearchParams({ max_results: 100 });
    if (paginationToken) {
      params.set("pagination_token", paginationToken);
    }
    
    const response = await fetch(`${url}?${params}`, { headers });
    const data = await response.json();
    
    if (data.data) {
      allTweets.push(...data.data);
    }
    
    paginationToken = data.meta?.next_token;
  } while (paginationToken);
  
  return allTweets;
}

---

Best practices

Use max results

Request the maximum allowed max_results to minimize API calls.

Handle partial pages

The last page may have fewer results than max_results.

Store tokens

Save next_token if you need to resume pagination later.

Don't poll with pagination

For new data, use since_id instead of paginating repeatedly.

---

Result ordering

Results are returned in reverse chronological order:

• First result on first page = most recent
• Last result on last page = oldest

This applies within and across pages.

---

Notes

• Pagination tokens are opaque strings—don’t parse or modify them
• Tokens may expire after some time
• If you get fewer results than max_results, more may still exist (continue until no next_token)
• Use SDKs for automatic pagination handling

---

Next steps

Rate limits

Understand request limits when paginating.

SDKs

Libraries with built-in pagination.