Time windows

A list of Calls or Data Sessions reads one window of time.

• from and to are required. Both are ISO 8601 date-times with a zone, such as 2026-10-01T00:00:00Z.
• from is in the window. to is not. to must be after from.
• A window is 31 days at most.
• An answer holds 1,000 results at most, newest first.

curl "https://api.customer.onsim.uk/v1/calls?from=2026-10-01T00:00:00Z&to=2026-10-08T00:00:00Z" \
  -H "x-api-key: $ONSIM_API_KEY"

When a window has more than 1,000 results

The answer is still a list, with the newest 1,000. It also has a Link header with the request for the next ones.

Link: <?from=2026-10-01T00%3A00%3A00Z&to=2026-10-06T14%3A21%3A07.412Z>; rel="next"

The link has no path. It is the query of your own request, with to moved back to the time of the oldest result that you have. Send it to the same path, and go on until an answer has no Link header.

let url = "https://api.customer.onsim.uk/v1/data-sessions?from=2026-09-01T00:00:00Z&to=2026-10-01T00:00:00Z"
const all = []

while (url) {
  const res = await fetch(url, { headers: { "x-api-key": process.env.ONSIM_API_KEY } })
  all.push(...await res.json())
  const next = res.headers.get("Link")?.match(/<([^>]+)>;\s*rel="next"/)?.[1]
  // The link has no path, so read it against the request.
  url = next ? new URL(next, url).href : null
}

A page can hold a few less than 1,000. The API does not cut between two results of the same second, so the next page gives that whole second.

A filter applies before the count. So a window with 3,000 Calls, of which 40 pass the filter, gives all 40 and no Link header.

A Call belongs to the window in which it starts

A Call that starts in the window is in the result, also when it ends after to. A Call that starts before from is not in the result, also when it ends in the window.

Calls and Data Sessions are kept for about 90 days

A window that is older than that gives an empty list. The API does not tell an empty window from a window that is too old.

A Recording is kept longer than its Call. You can still get it by the ID of the Call.