Pagination

Foil uses cursor-based pagination on every list endpoint. Cursors are opaque - don’t parse them, construct them, or rely on their format. They’re stable across process restarts and safe to persist in your own database if you want to resume a long iteration.

Response envelope

Every list response has the same shape:

{
  "data": [
    { "object": "session", "id": "sid_...", "...": "..." },
    { "object": "session", "id": "sid_...", "...": "..." }
  ],
  "pagination": {
    "limit": 20,
    "has_more": true,
    "next_cursor": "cur_AbC1234..."
  },
  "meta": {
    "request_id": "req_..."
  }
}

Field	Type	Meaning
`data`	array	Up to `limit` items for this page.
`pagination.limit`	number	The effective page size the server used.
`pagination.has_more`	boolean	`true` if more pages exist beyond this one.
`pagination.next_cursor`	string, optional	Present when `has_more` is `true`. Pass it as `cursor` on the next request.
`meta.request_id`	string	Per-request ID - see Errors → Using `request_id`.

Individual resources aren’t returned inside an extra envelope - they unwrap to the resource object itself - but list responses always use the shape above.

Request parameters

Every list endpoint accepts these two query parameters:

Parameter	Type	Default	Max	Notes
`limit`	number	`20`	`100`	Items per page. Smaller pages keep responses fast; larger pages reduce round trips for bulk iteration.
`cursor`	string	-	-	The `pagination.next_cursor` from a prior page. Omit on the first request.

Individual endpoints may expose additional filter parameters (e.g. verdict, search, sort) on top of these. See the per-resource filter sections below.

Iterating

The canonical pattern: call the endpoint, process data, and loop while has_more is true, passing next_cursor forward.

const { Foil } = require("@abxy/foil-server");
const client = new Foil({ secretKey: process.env.FOIL_SECRET_KEY });

async function iterateSessions() {
  let cursor = undefined;
  do {
    const page = await client.sessions.list({ limit: 100, cursor });
    for (const session of page.items) {
      await processSession(session);
    }
    cursor = page.has_more ? page.next_cursor : undefined;
  } while (cursor);
}

from foil_server import Foil
import os

client = Foil(secret_key=os.environ["FOIL_SECRET_KEY"])

def iterate_sessions():
    cursor = None
    while True:
        page = client.sessions.list(limit=100, cursor=cursor)
        for session in page.items:
            process_session(session)
        if not page.has_more:
            break
        cursor = page.next_cursor

import foil "github.com/abxy-labs/foil-server-go"

func iterateSessions(ctx context.Context, client *foil.Client) error {
    var cursor string
    for {
        page, err := client.Sessions.List(ctx, foil.SessionListParams{
            Limit:  100,
            Cursor: cursor,
        })
        if err != nil {
            return err
        }
        for _, s := range page.Items {
            processSession(s)
        }
        if !page.HasMore {
            return nil
        }
        cursor = page.NextCursor
    }
}

require "foil/server"

client = Foil::Server::Client.new(secret_key: ENV["FOIL_SECRET_KEY"])

cursor = nil
loop do
  page = client.sessions.list(limit: 100, cursor: cursor)
  page.items.each { |s| process_session(s) }
  break unless page.has_more
  cursor = page.next_cursor
end

$client = new \Foil\Server\Client([
    "secret_key" => getenv("FOIL_SECRET_KEY"),
]);

$cursor = null;
do {
    $page = $client->sessions()->list([
        "limit" => 100,
        "cursor" => $cursor,
    ]);
    foreach ($page->items as $session) {
        processSession($session);
    }
    $cursor = $page->has_more ? $page->next_cursor : null;
} while ($cursor !== null);

# First page
curl "https://api.usefoil.com/v1/sessions?limit=100" \
  -H "Authorization: Bearer sk_live_..."

# Subsequent page - pass the next_cursor from the previous response
curl "https://api.usefoil.com/v1/sessions?limit=100&cursor=cur_AbC1234..." \
  -H "Authorization: Bearer sk_live_..."

Auto-pagination in the SDKs

The server SDKs ship with an auto-pagination helper that abstracts the cursor loop. Use it when you want to iterate the entire result set without managing state.

for await (const session of client.sessions.listAll({ limit: 100 })) {
  await processSession(session);
}

for session in client.sessions.list_all(limit=100):
    process_session(session)

iter := client.Sessions.ListAll(ctx, foil.SessionListParams{Limit: 100})
for iter.Next() {
    processSession(iter.Value())
}
if err := iter.Err(); err != nil {
    return err
}

Auto-pagination makes one API call per page and yields items as it goes - safe to use on result sets that wouldn’t fit in memory, and it respects the same rate limits as manual iteration.

Filters and sorting

Filter parameters layer on top of the standard pagination params. They narrow the result set but don’t change the envelope shape.

Sessions

Parameter	Type	Notes
`verdict`	`"bot" \| "human" \| "inconclusive"`	Filter to a single verdict category.
`search`	string	Fuzzy match against session ID and request metadata.

Fingerprints

Parameter	Type	Notes
`search`	string	Fuzzy match against visitor ID, user agent, or IP.
`sort`	`"seen_count" \| "first_seen"`	Orders results. Default is most-recently-seen.

API keys

Parameter	Type	Notes
`limit`, `cursor`	-	Pagination only. No additional filters today.

Combining filters and pagination is supported: pass the filters once, and carry the cursor forward as normal. The server applies filters before paginating, so limit controls page size of the filtered result set.

Caveats

Don’t construct cursors. They’re opaque tokens - the server may change their encoding. If you need to page from a specific timestamp or ID, use a filter parameter instead.
Cursor lifetimes. Cursors remain valid as long as the underlying result set does - a cursor minted today is valid until the records it points into expire. Stored sessions and visitor fingerprints are not currently expired on a fixed window.
Result stability under concurrent writes. New records created during a long iteration may or may not appear in later pages - cursors provide “snapshot-like” stability without strong isolation guarantees. For auditing across a fixed window, pass a time filter when one is available for that resource.
Ordering. Each list endpoint documents its default sort. Don’t assume an order that isn’t explicitly documented.

What’s next

Authentication

Key types and scopes.

Errors

Envelope shape, status codes, retry semantics.

Sessions

The most common list endpoint.

Fingerprints

Visitor fingerprint lookup.

Get started

Detection

Gate

Webhooks

Management

Response envelope

Request parameters

Iterating

Filters and sorting

Sessions

Fingerprints

API keys

Caveats

What’s next

Authentication

Errors

Sessions

Fingerprints

​Response envelope

​Request parameters

​Iterating

​Auto-pagination in the SDKs

​Filters and sorting

​Sessions

​Fingerprints

​API keys

​Caveats

​What’s next

Authentication

Errors

Sessions

Fingerprints

Response envelope

Request parameters

Iterating

Auto-pagination in the SDKs

Filters and sorting

Sessions

Fingerprints

API keys

Caveats

What’s next