Pagination: Iterating API Lists

Most Frisbii Media list endpoints return paginated results. By default each response contains up to 5 items. Use the size parameter and the startingAfter cursor to iterate through the full dataset.

How pagination works

Every list response contains:

• items — the array of results for the current page

• startingAfterId — the ID of the last item returned; pass this as startingAfter in the next request to get the next page

When items is empty, you have reached the end of the list.

Parameters

Reusable getList() function

The following function handles all pagination automatically and returns all items across all pages as a flat array:

/**
 * Fetches all items from a paginated Frisbii Media API list endpoint.
 *
 * @param string        $url   API path relative to /api/v3.0, e.g. "/customers"
 * @param \DateTime|null $start Optional start of time frame
 * @param \DateTime|null $end   Optional end of time frame
 * @return array
 */
function getList(string $url, ?\DateTime $start = null, ?\DateTime $end = null): array
{
    $allEntities = [];
    $id = null;
    $client = new GuzzleHttp\Client([
        'base_uri' => 'https://api.frisbii-media-stage.com',
        'headers'  => ['X-plenigo-token' => eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9],
    ]);
    // Request up to 100 items per page to minimise HTTP calls
    $url = "/api/v3.0{$url}?size=100";
    if (!empty($start) && $start instanceof \DateTime) {
        $url .= '&startTime=' . $start->format('Y-m-d\TH:i:s.v\Z');
    }
    if (!empty($end) && $end instanceof \DateTime) {
        $url .= '&endTime=' . $end->format('Y-m-d\TH:i:s.v\Z');
    }
    do {
        $myUrl   = $id ? $url . "&startingAfter={$id}" : $url;
        $entities = [];
        try {
            $response = json_decode($client->get($myUrl)->getBody()->getContents(), true);
            $id       = $response['startingAfterId'];
            $entities = $response['items'] ?: [];
        } catch (\Exception $exception) {
            echo $exception->getMessage();
            break;
        }
        foreach ($entities as $entity) {
            $allEntities[] = $entity;
        }
    } while (!empty($entities));
    return $allEntities;
}

Usage examples

// Get all customers
$customers = getList('/customers');
// Get all subscriptions
$subscriptions = getList('/subscriptions');
// Get all orders within a date range
$start = new DateTime('2024-01-01');
$end   = new DateTime('2024-12-31');
$orders = getList('/orders', $start, $end);
// Get all price issues (used in price configuration)
$priceIssues = getList('/products/priceIssues');

Notes

• The startingAfterId from one response must be passed as startingAfter in the next request — not the page number or offset

• If startingAfterId is null in the response, you are on the last page

• Setting size=100 reduces the total number of HTTP round-trips; use a lower value if memory is a concern