Skip to main content
When you request a list of items (like followers, search results, or comments), the API returns data in pages. To retrieve the next set of results, you must use Cursors.

​
🔄 How it works

Unlike traditional “page-based” pagination (page 1, page 2), Sorsa uses a cursor-based system. This is much more stable for social media data where new content is added every second.
💡 Not all endpoints support pagination. For example, /info (single user profile) or /tweet-info return a single object and do not require a cursor. Pagination is only present in endpoints that return lists of items.

​
📥 The cursor Parameter

In your API response, look for the next_cursor field.
  • If next_cursor is a string: There is more data available.
  • If next_cursor is null or missing: You have reached the end of the list.
To get the next page, take the value from next_cursor and pass it in your next request as the cursor query parameter.

​
⚠️ Important: Result Count

Due to the nature of X (Twitter) data sourcing, the number of items returned per page is not fixed.
  • “Up to X items”: If an endpoint says it returns 20 items, it might return 18, 15, or even 5 in some cases, even if there is more data on the next page.
  • Don’t use count as a stop-sign: Never assume you’ve reached the end just because a page has fewer items than expected. Always rely on the next_cursor field to determine if there is a next page.

​
🛠 Example Workflow

Step 1: Initial request GET https://api.sorsa.io/v3/search-tweets?query=bitcoin Response: JSON 
{
  "items": [...], // might contain 14 items
  "next_cursor": "DAABCgABF7Y..." 
}
Step 2: Follow-up request GET https://api.sorsa.io/v3/search-tweets?query=bitcoin&cursor=DAABCgABF7Y...

​
🐍 Python Example: Robust Pagination

This script handles variable page sizes and stops only when the cursor is gone. Python 
import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.sorsa.io/v3/search-tweets"

def fetch_all_data(query):
    all_items = []
    cursor = None
    
    while True:
        params = {"query": query}
        if cursor:
            params["cursor"] = cursor
            
        response = requests.get(BASE_URL, headers={"ApiKey": API_KEY}, params=params)
        data = response.json()
        
        items = data.get("items", [])
        all_items.extend(items)
        
        print(f"Fetched {len(items)} items. Total: {len(all_items)}")
        
        # The ONLY way to know if there's a next page:
        cursor = data.get("next_cursor")
        
        if not cursor:
            print("Reached the end of the data.")
            break
            
        # Respect the 20 req/s limit
        time.sleep(0.05) 
        
    return all_items

​
⏭ Next Steps

  • Error Codes — Learn how to handle 404 or 429 errors during pagination.
  • Search Guide — See pagination in action with advanced search operators.