Conventions

The generated endpoint pages describe each operation's own parameters. This page covers what they share, so it isn't repeated 599 times.

Dates and times

Every timestamp the API accepts or returns is UTC. There is no per-account time zone. If a value looks off by a few hours, the conversion is happening in your code, not here.

Two conventions appear side by side:

• since / until — ISO-8601 datetimes
• since_ts and other *_ts fields — Unix seconds

Fields ending in _ts are always integer Unix seconds; the same value without the suffix is the human-readable string form. Many records carry both, for example created_at and created_at_ts.

Pagination

Most list endpoints take limit with either skip or offset — which of the two depends on the endpoint, so check its parameters rather than assuming. Both mean the same thing.

Endpoints proxying RIPE's own API follow RIPE's pagination instead. The measurement and probe lookups are the main examples.

Common filters

Recurring parameters across the reference:

Parameter	Meaning
q	Free-text search
country	ISO two-letter country code
asn	Autonomous system number
af	Address family — 4 or 6
probe_id, anchor_id	Restrict to one probe or anchor
date	A single UTC calendar day, YYYY-MM-DD
since / until	Time window
status	Endpoint-specific; probe status and measurement status are different vocabularies
all	On owner-scoped endpoints, admin opt-in to the cross-user view
refresh	Bypass the local cache and re-read upstream

refresh

Several endpoints serve a cached copy and fall through to the upstream when it is stale. Passing refresh forces the upstream read.

Use it sparingly. It makes your request as slow as the upstream and, in bulk, puts load on RIPE. If you are polling, don't set it — the cache lifetimes are chosen to be shorter than the data's own update cadence. See Data delay and freshness.

Errors

422 — validation failure. A detail array naming the offending field and why it was rejected:

{
  "detail": [
    {
      "loc": ["query", "probe_id"],
      "msg": "Input should be a valid integer",
      "type": "int_parsing"
    }
  ]
}

401 / 403 — authentication and authorization. 401 means no usable credential; 403 means the credential is valid but the role or scope is insufficient. See Authentication.

404 — not found, with a detail string.

5xx. A 502 specifically indicates an upstream failure — RIPE or another data source — rather than a fault in Atlas. Retry rather than changing your request.

TIP

The specification currently declares only 200, 201 and 422 on most operations, so the generated pages will not list the codes above. They are real; the spec is simply incomplete on them. Handle them in client code regardless of what the schema shows.

Rate limits

Not currently documented. Treat the API as a shared resource: cache what you poll, avoid refresh in loops, and prefer one broad query over many narrow ones.