Pagination, limits and versioning
How list endpoints page, how fast you may call, and how the v1 API is allowed to change.
Pagination
Every list answers in the same shape:
{ "data": [ ... ], "nextCursor": "run_01JCA40000000000000000000" }
limit: how many items per page, 1 to 100, default 25.cursor: send the previous page’snextCursorto get the next page.- When
nextCursorisnull, there are no more pages.
cursor=""
while :; do
page=$(curl -fsS "$METRICEVO_API/audit-runs?limit=100${cursor:+&cursor=$cursor}" \
-H "Authorization: Bearer $METRICEVO_API_KEY")
echo "$page" | jq -c '.data[]'
cursor=$(echo "$page" | jq -r '.nextCursor // empty')
[ -z "$cursor" ] && break
done
Treat a cursor as an opaque string: do not build one yourself. Always follow nextCursor rather than assuming a list fits on one page, even where it does today (sites are at most 10, and a run’s observations come in one page).
Rate limits
| Limit | Value | Answer when reached |
|---|---|---|
| Requests | 120 per minute per account (Free: 30) | 429 rate_limited, Retry-After: 60 |
| Audits started | 20 per hour per account, and the audit credits of your plan | 429 quota_exceeded (Retry-After), 429 credit_limit_reached or 429 spend_cap_reached |
All keys of an account share these limits, and so does the app. When polling a run, honour its Retry-After and you stay well inside them. All other limits: Limits.
Versioning
The version is in the path: /api/v1. Within v1:
- Additive changes only. New endpoints, new optional fields, new values in a list of codes may appear at any time.
- Ignore what you do not know. A client must not fail on an unknown field.
- Nothing is removed or renamed within v1. A breaking change needs a new version in the path.
The contract (GET /openapi.json) lists only operations that work today. Its info.version tells you which contract you are reading.
Statuses mean the same everywhere
no_data and not_tested are never failures, in any output, today or later. A client can rely on that when it counts failures or gates a build.