Copy page

Guides

Pages, dates and errors

Lists and pages

A list returns items, next_cursor and, on Stats lists, total. Pass next_cursor back as cursor for the next page; it is null on the last. A cursor belongs to the query it came from: change a filter or a sort and start again without it. On the Stats API limit is 1 to 1000 and defaults to 100. On the Appraisal API it is 1 to 100 and defaults to 20.

The Stats API echoes the parameters it used in query, defaults included. A request with an unknown parameter is redirected to the same query without it; follow the redirect.

Months and dates

Months are YYYY-MM, dates YYYY-MM-DD, timestamps ISO 8601 in UTC. A series takes from and to, or range: 1y, 3y, 5y, 10y or all for months; 30d, 90d, 1y or all for zone nights. Series run oldest first and carry bounds, the first and last point that exist.

Fields

Apart from next_cursor, a field that is unknown is left out rather than sent as null. Fields are added without a version change, so ignore fields you do not recognise. Removing or renaming a field means a new version, /v2/, announced in advance.

Errors

Errors are JSON with a stable error code, a message you can show, and request_id, also in the X-Request-Id header. Quote the request id when asking for help.

Code
{
  "error": "invalid_parameter",
  "message": "kind must be one or more of: cctld, idn-cctld, legacy-gtld, new-gtld, sponsored, infra, unknown, joined with commas.",
  "details": { "parameter": "kind", "value": "geo",
               "accepted": ["cctld", "idn-cctld", "legacy-gtld", "new-gtld", "sponsored", "infra", "unknown"] },
  "request_id": "d85c68ea-0985-4dfc-9f16-76f8616cb5f8"
}

Status	Code	When
400	invalid_parameter	A parameter has a value it does not accept; details.accepted lists what it does
400	invalid_cursor	The cursor came from a different query
401	unauthorized	The key is missing or not valid. The Stats API also works with no key
402	insufficient_credits	The wallet cannot cover the request
404	not_found, job_not_found, tld_not_found, registry_not_found, registrar_not_found, group_not_found	No such endpoint or entity
409	already_terminal, idempotency_key_reused, idempotency_request_in_progress	The job has already finished, or the Idempotency-Key was sent with a different body or is still running
429	rate_limited	Too many requests from this address in a minute; wait Retry-After seconds

The full list of codes is in the API reference.