Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shoal.xyz/llms.txt

Use this file to discover all available pages before exploring further.

Shoal API uses simple limit and offset query parameters on list endpoints, but bulk and export-style routes have tighter caps than scoped evaluation routes.

​
Parameters

  • limit: number of items to return
  • offset: number of items to skip
Values above the maximum are silently capped. Negative values are clamped to the minimum (1 for limit, 0 for offset).

​
Example

curl "https://api.shoal.xyz/v1/radar/all?since=2026-04-04T00:00:00Z&limit=25&offset=100" \
  -H "Authorization: Bearer YOUR_API_KEY"
To fetch the next page, increase offset by limit.

​
Caps

Common caps:
Endpoint classDefault limitMax limitMax offset
Scoped list routes5050500
/v1/radar/all and /v1/signal/all2525250
/v1/organizations/all2525100
Use the since parameter to filter by time instead of paginating deeply. Bulk /all routes are intentionally constrained to protect the higher-value historical and export surfaces.

​
Cursor-Based Pagination

For large result sets that exceed offset limits, radar and signal endpoints support cursor-based pagination via the cursor and next_cursor fields.

​
How It Works

  1. Make a normal request with since (and optionally limit).
  2. If the response includes a non-null next_cursor, more results are available.
  3. Pass next_cursor as the cursor query parameter on your next request, along with the same since value.
  4. Repeat until next_cursor is null.
When cursor is provided, offset is ignored.

​
Example

# First page
curl "https://api.shoal.xyz/v1/radar/all?since=2026-04-04T00:00:00Z&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"
# Response includes: "next_cursor": "eyJ0cyI6Ii4uLiIsImlkIjo2NTB9"

# Next page — pass cursor, keep the same since value
curl "https://api.shoal.xyz/v1/radar/all?since=2026-04-04T00:00:00Z&limit=25&cursor=eyJ0cyI6Ii4uLiIsImlkIjo2NTB9" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Details

  • The cursor is a base64url-encoded JSON token. Treat it as opaque — do not decode or modify it.
  • The since parameter is required when using cursor. The cursor is bound to the original query context; changing since between pages will return an error.
  • On /v1/radar/all and /v1/signal/all, since must also remain within the allowed recent lookback window.
  • offset is ignored when cursor is present.
  • When next_cursor is null, you have reached the end of the result set.