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.

​
Per-Minute Rate Limit

Each API key is limited to 100 requests per minute using a fixed-window counter. The window resets every 60 seconds.

​
Monthly Credits

Every API key has a monthly credit allowance that varies by plan. Use GET /v1/usage to check your current request counts and remaining budget. Some endpoints are available only on higher plans. In particular:
  • Core lookup and monitoring endpoints are available broadly
  • Brief endpoints require a higher plan
  • Bulk feed and webhook endpoints are limited to higher-tier plans

​
Response Headers

Every response includes rate limit and credit headers:
HeaderDescription
X-RateLimit-LimitMaximum requests per window (100)
X-RateLimit-RemainingRequests remaining in the current window
X-Monthly-LimitTotal credits for the billing month
X-Monthly-UsedCredits consumed so far this month
X-Monthly-RemainingCredits remaining this month
X-Credit-CostCredit cost for the current request
X-Plan-TierPlan tier attached to the API key
X-Api-SurfaceRoute packaging surface such as lookup, query, feed, timeline, replay, brief, or delivery
X-Access-LayerAccess layer such as evaluation, operational, or premium
X-Endpoint-PolicyStable internal policy label for the endpoint (for example search or radar.all)
X-Request-IdUnique identifier for the request (useful for support)

​
Access Layers

Shoal’s pricing and access model is intentionally tied to route type, not just raw request count:
  • evaluation routes are the safest entry points for new integrations
  • operational routes are higher-value workflow surfaces
  • premium routes expose bulk feed or delivery capabilities and are more tightly gated
Typical examples:
  • evaluation: /v1/search, /v1/entities/byName, /v1/signal/top
  • operational: /v1/brief, /v1/brief/batch, /v1/webhooks/*
  • premium: /v1/radar/all, /v1/signal/all, /v1/organizations/all, /v1/replay/global
Premium routes are not just higher-plan. They also carry tighter access constraints:
  • /v1/organizations/all is an export-style directory surface with smaller page sizes
  • /v1/radar/all and /v1/signal/all are recent-monitoring surfaces with a required since window and tighter pagination caps
  • /v1/replay/global is a merged premium replay surface with a 30-day recent-history window and smaller pages
Operational delivery routes are different:
  • /v1/webhooks/* is a scoped delivery primitive for radar and signal subscriptions
  • premium/global delivery should be treated as a separate product surface if added later

​
Exceeding Limits

​
Per-Minute Rate Limit

{
  "error": "Rate limit exceeded. Maximum 100 requests per 60 seconds."
}
  • Status: 429 Too Many Requests
  • Check X-RateLimit-Reset header for seconds until the window resets

​
Monthly Credit Limit

{
  "error": "API usage limit reached. Please upgrade your plan or contact support."
}
  • Status: 403 Forbidden
  • Check X-Monthly-Limit and X-Monthly-Used headers for your quota status
  • Credits reset on the 1st of each month (UTC)

​
Best Practices

  • Use the since parameter to poll incrementally instead of re-fetching everything
  • Prefer filtered endpoints over bulk feeds unless you explicitly need a full export workflow
  • Use X-Api-Surface and X-Access-Layer to verify you are hitting the route class you intended
  • Check X-RateLimit-Remaining before sending bursts
  • Monitor X-Monthly-Remaining to avoid hitting your credit cap
  • Use the /v1/usage endpoint to track both request volume and monthly budget
  • On 429, wait for the X-RateLimit-Reset duration before retrying
  • Implement exponential backoff on non-2xx responses