Skip to main content
Tripwire 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_..."
  }
}
FieldTypeMeaning
dataarrayUp to limit items for this page.
pagination.limitnumberThe effective page size the server used.
pagination.has_morebooleantrue if more pages exist beyond this one.
pagination.next_cursorstring, optionalPresent when has_more is true. Pass it as cursor on the next request.
meta.request_idstringPer-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:
ParameterTypeDefaultMaxNotes
limitnumber20100Items per page. Smaller pages keep responses fast; larger pages reduce round trips for bulk iteration.
cursorstring——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 { Tripwire } = require("@abxy/tripwire-server");
const client = new Tripwire({ secretKey: process.env.TRIPWIRE_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);
}

​
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);
}
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

ParameterTypeNotes
verdict"bot" | "human" | "inconclusive"Filter to a single verdict category.
searchstringFuzzy match against session ID and request metadata.

​
Fingerprints

ParameterTypeNotes
searchstringFuzzy match against visitor ID, user agent, or IP.
sort"seen_count" | "first_seen"Orders results. Default is most-recently-seen.

​
API keys

ParameterTypeNotes
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. For sessions (15-minute durable window) and fingerprints (365-day sliding window), a cursor minted today is valid until the records it points into expire.
  • 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

Durable visitor fingerprint lookup.