Bridge API Pagination Guide

​

Endpoint shape

• Base URL: https://api.bridge.xyz
• Typical list endpoint pattern: GET /v0/
• Default order: newest → oldest (unless an endpoint specifies otherwise)
• Page size: controlled by limit (maximum 100)
• Pagination: cursor-based using item id values

​

Query parameters

• limit
  • Description: number of items to return
  • Range: 1–100
  • Tip: set explicitly (e.g., limit=50) for predictable pagination
• starting_after
  • Description: fetches items that come after the given id in the default ordering, i.e., older items
  • How to use: pass the last item’s id from your current page to get the next page of older results
• ending_before
  • Description: fetches items that come before the given id in the default ordering, i.e., newer items
  • How to use: pass the first item’s id from a known page to retrieve any items that are newer than it

​

Response shape

• data: array of resource objects (0 to limit items)
• count: number of items in this page (if provided by the endpoint)
• Stop condition: when data is empty, there are no more items in that direction

​

cURL examples

• macOS/Linux: export BRIDGE_API_KEY=“sk_live_…”
• Windows PowerShell: $env:BRIDGE_API_KEY = “sk_live_…”

​

1) Fetch the first page (newest first)

curl --location 'https://api.bridge.xyz/v0/{resource}?limit=3' \
  --header 'Accept: application/json' \
  --header "Api-Key: $BRIDGE_API_KEY"

• First item’s id: newest on this page
• Last item’s id: oldest on this page

​

2) Get the next page of older items

curl --location 'https://api.bridge.xyz/v0/{resource}?limit=3&starting_after={LAST_ID_FROM_PREVIOUS_PAGE}' \
  --header 'Accept: application/json' \
  --header "Api-Key: $BRIDGE_API_KEY"

​

3) Fetch newer items since a known id

curl --location 'https://api.bridge.xyz/v0/{resource}?ending_before={FIRST_ID_YOU_SAW}' \
  --header 'Accept: application/json' \
  --header "Api-Key: $BRIDGE_API_KEY"

​

Practical patterns

​

Backfill all historical items (older direction)

1. Request with your chosen limit (e.g., 100).
2. Process the page.
3. Save the last id from the page (the oldest in this batch).
4. Repeat with starting_after=<last_id> until data is empty.

​

Periodically check for new items (newer direction)

1. Save the first id from your last successful fetch (the newest you’ve seen).
2. Request with ending_before=<that_first_id>.
3. If data is non-empty, process the new items and update your saved first id to the newest id returned.
4. If empty, nothing new is available.

​

Boundary behavior

• Reached oldest items: using starting_after eventually returns data: [].
• No newer items: using ending_before may return data: [].

​

Tips and best practices

• Treat item ids as stable cursors; always use the first and last ids from each page for the next request.
• Don’t combine starting_after and ending_before in the same call.
• Stick to a consistent limit for predictable throughput; max is 100.
• Expect partial pages near the ends (fewer than limit items).
• If you need to process items oldest-to-newest, reverse the page locally after fetching.
• When running concurrent pagination and ingestion, de-duplicate by id in your datastore.

​

Minimal JavaScript examples

​

Backfill older pages

// Fetch older pages until no more items are returned.
const backfillAll = async (fetchFn) => {
  let startingAfter = null;
  const pageSize = 100;

  while (true) {
    const qs = new URLSearchParams({ limit: String(pageSize) });
    if (startingAfter) qs.set("starting_after", startingAfter);

    const res = await fetchFn(`/v0/{resource}?${qs.toString()}`);
    const { data = [] } = await res.json();

    if (data.length === 0) break;

    // Process items (newest → oldest on this page)
    // ...

    // Next cursor: last id (oldest on this page)
    startingAfter = data[data.length - 1].id;
  }
};

​

Poll for newer items since a known id

// Fetch any items newer than `firstSeenId`.
// Returns the updated newest id to store for next poll.
const fetchNewerSince = async (fetchFn, firstSeenId) => {
  const qs = new URLSearchParams({ ending_before: firstSeenId });
  const res = await fetchFn(`/v0/{resource}?${qs.toString()}`);
  const { data = [] } = await res.json();

  if (data.length > 0) {
    // Items returned are newest → oldest within the page.
    // Update the cursor to the newest id we now know about.
    return data[0].id;
  }
  return firstSeenId;
};

​

Summary

• Results are newest → oldest by default.
• Use starting_after=<last_id> to go older.
• Use ending_before=<first_id> to fetch items newer than a known id.
• Control page size with limit (max 100).
• Stop when data is empty in the direction you’re traversing.