Pagination, errors and limits
Walk through a long list, read an error code, stay under the rate limit.
Response format
All responses are JSON. A success looks like this:
{ "data": [ … ], "meta": { "limit": 100, "next_cursor": "eyJpZCI6MTIzNH0" } }and an error like this (the message text is currently in French):
{ "error": "forbidden", "message": "Portée requise : read:flows", "scope": "read:flows" }Dates are in UTC, in ISO 8601 format (2026-10-07T08:12:40Z), in parameters as well as in responses.
Cursor pagination
Long lists (computers, flows, events…) come back in pages. Call the route with limit; each route's default and maximum are in the reference. As long as meta.next_cursor is not null, call the same route again, with the same filters, adding cursor=<value>. When meta.next_cursor is null, you have everything.
curl -s "https://console.example.com/api/v1/flows?machine=pc-009&period=24h&limit=500&cursor=eyJpZCI6MTIzNH0" \
-H "Authorization: Bearer $FIRSTSI_TOKEN"The cursor is opaque: don't try to build one yourself, and don't change the filters between pages.
Periods
Routes that read history accept either period, a window that ends now (1h, 3h, 6h, 12h, 24h, 3d, 7d, 30d), or from and to in ISO 8601. If from and to are given, period is ignored.
Detailed flows (/flows) are limited to 7 days. Beyond that, the response is cut back to the last 7 days and meta.window_capped is true. For a whole month, use /flows/destinations, /flows/summary or /flows/talkers, which read hourly totals.
Response codes
| Code | Meaning | What to do |
|---|---|---|
200 | Normal response | |
202 | Action accepted (NetDiag diagnostic) | The result will show up in the computer's events |
400 | Invalid parameter | Read message and fix the request |
401 | Missing, unknown, expired or revoked token | Check the Authorization header, create a new token if needed |
403 | Scope missing from the token | Create a token with that scope; see Scopes |
404 | Item unknown in your customer account | Check the identifier or the exact host name |
429 | Rate limit exceeded | Wait the number of seconds given in Retry-After |
5xx | Server error | Try again later; if it persists, contact support |
Rate limit
Each token is allowed 600 calls per minute. Every response carries the X-RateLimit-Limit and X-RateLimit-Remaining headers. Past the limit, the server answers 429 with Retry-After, in seconds.
An integration that polls often should prefer aggregated routes (/flows/summary, /netdiag/machines) to detailed lists, and cache whatever changes little, such as the inventory or the list of computers. After a 429, space out your retries instead of looping.
Source: · FirstSI Docs · updated 2026-10-10