Skip to content
LootLockerLootLocker

Pagination

List endpoints in the LootLocker APIs return a bounded number of items at a time. When a list is longer than that, the response includes pagination data telling you how to request the next batch. Pagination is how you read a complete list without pulling every item in a single response.

Every paginated response wraps its items in a pagination object alongside the list itself. The fields inside that object tell you whether more items exist and what to send to get them.

Pagination Styles

LootLocker uses three pagination styles. They solve different problems and are found in different places, so which one you use depends on the endpoint you are calling rather than on a preference you get to make.

StyleRequest parametersResponse fieldsUsed by
Cursorcursor, per_pagenext_cursor, previous_cursor, totalFollowers, Entitlements, Catalog Items, and more
Offsetpage, per_pagecurrent_page, last_page, next_page, prev_page, per_page, offset, totalInventory, Notifications, Friends, Metadata, and more
Simple Offsetcount, afternext_cursor, previous_cursor, totalLeaderboards, and more

The lists above are examples rather than an exhaustive inventory — many endpoints use each style. Check the endpoint you are calling to confirm which one it uses.

Cursor Pagination

Cursor pagination is the style used by newer list endpoints. You request a page by passing the cursor you received in the previous response, and the API returns the items that follow it.

  • cursor: an opaque identifier for the position in the list. Omit it, or pass an empty value, to request the first page.
  • per_page: how many items to return. Defaults to 10, and values above 100 fall back to the default.

The response returns next_cursor when more items exist, and previous_cursor when you are not on the first page. Both are empty when there is nothing further in that direction.

Because the cursor identifies a position in the list rather than a count of items, items added or removed while you are paging do not shift the pages underneath you. This makes cursor pagination the safest choice for lists that change often.

Example: Listing Followers

string cursor = null;


void LoadFollowers()
{
    LootLockerSDKManager.ListFollowersPaginated(cursor, 25, (response) =>
    {
        if (!response.success)
        {
            Debug.LogError("Failed to list followers: " + response.errorData.message);
            return;
        }


        foreach (var follower in response.followers)
        {
            Debug.Log("Follower: " + follower.player_id);
        }


        // Empty means there are no more pages
        cursor = response.pagination.next_cursor;
    });
}

Offset Pagination

Offset pagination addresses items by page number. You request a page by passing page, and the API returns the items at that position.

  • page: the page to return, starting at 1. Defaults to 1.
  • per_page: how many items to return per page. Defaults to 10.

The response describes where you are in the list: current_page and last_page tell you the page you received and the final page available, while next_page and prev_page give you the adjacent page numbers, or null at either end. total is the total number of items across all pages, and offset is the item index the page starts at.

Offset pagination lets you jump straight to a specific page, which cursor pagination cannot do. The trade-off is that if items are added or removed while you are paging, the same item can appear on two pages or be skipped entirely.

Example: Listing Friends

int page = 1;
const int perPage = 25;


void LoadFriends()
{
    LootLockerSDKManager.ListFriendsPaginated(perPage, page, (response) =>
    {
        if (!response.success)
        {
            Debug.LogError("Failed to list friends: " + response.errorData.message);
            return;
        }


        foreach (var friend in response.friends)
        {
            Debug.Log("Friend: " + friend.player_id);
        }


        // null means there is no next page
        if (response.pagination.next_page.HasValue)
        {
            page = response.pagination.next_page.Value;
        }
    });
}

Simple Offset Pagination

Simple offset pagination takes count — how many items to return — and after — the index to start from. It is the simplest of the three, and it is generally the style LootLocker has moved away from for new endpoints.

Example: Listing Leaderboard Scores

int after = 0;
const int count = 25;


void LoadScores()
{
    LootLockerSDKManager.GetScoreList("my_leaderboard_key", count, after, (response) =>
    {
        if (!response.success)
        {
            Debug.LogError("Failed to list scores: " + response.errorData.message);
            return;
        }


        foreach (var entry in response.items)
        {
            Debug.Log("Rank " + entry.rank + ": " + entry.score);
        }


        // 0 means there are no more entries
        after = response.pagination.next_cursor ?? 0;
    });
}

SDK Parameter Names

Some SDK methods name their pagination parameters count and after even when the endpoint underneath uses cursor pagination. The names are a leftover from the simple offset style; the values are still a page size and a cursor.

For example, the Unity ListEntitlements(count, after, ...) method sends per_page and cursor on the wire. Pass the next_cursor from the response as the after argument, and it is forwarded as the cursor.

Check the endpoint's own documentation if you are unsure which style you are talking to — the SDK signature alone does not tell you.

Reading a List to the End

The pattern is the same for every style: request a page, use the items, then check the pagination data for where to go next. Stop when the response tells you there is nothing further — an empty next_cursor, a null next_page, or a next_cursor of 0 for simple offset pagination.

Request pages sequentially rather than in parallel. Each page's position depends on the response to the previous one, so you cannot know where the next page starts until the current one has arrived.

The examples below read a whole list by requesting the next page from inside the response handler, until the pagination data says there is nothing left.

// Reads every page of a cursor-paginated list into one collection.
// Swap the request call and the "has more" check for the style you are using.
void LoadAllFollowers()
{
    var allFollowers = new List<LootLockerFollower>();
    string cursor = null;


    void RequestPage()
    {
        LootLockerSDKManager.ListFollowersPaginated(cursor, 25, (response) =>
        {
            if (!response.success)
            {
                Debug.LogError("Failed to list followers: " + response.errorData.message);
                return;
            }


            allFollowers.AddRange(response.followers);


            cursor = response.pagination.next_cursor;
            if (string.IsNullOrEmpty(cursor))
            {
                Debug.Log("Loaded " + allFollowers.Count + " followers");
                return;
            }


            RequestPage();
        });
    }


    RequestPage();
}

For offset pagination, the same loop advances page until next_page is null. For simple offset pagination, advance after by count until next_cursor is 0.

Where to Go Next

Pagination is a property of the endpoint you are calling, not a separate feature to configure. The how-to for each feature shows the pagination parameters in context: