Skip to main content

​
GET /api/devices

Returns a count of events grouped by device category for the given domain and optional date range. Device type is inferred from the screen_width recorded in each event — no User-Agent parsing is performed.
Device categories are determined by the visitor’s window.innerWidth (viewport width) at the time the event fires:
Screen widthDevice category
< 768 pxMobile
768 – 1023 pxTablet
≥ 1024 pxDesktop
Unlike other analytics endpoints, /api/devices counts all event types — not just $pageview. If you want device breakdown by pageview only, filter client-side from the raw counts or raise a feature request.

​
Query parameters

​
domain
string
required
The domain to query (e.g. example.com). Must match the d field sent in event payloads exactly.
​
from
string
Start of the date range, inclusive. ISO 8601 date string (YYYY-MM-DD). If omitted, results cover all time up to to.
​
to
string
End of the date range, inclusive. ISO 8601 date string (YYYY-MM-DD). If omitted, results cover all time from from.

​
Response

Returns a JSON array of device stat objects, ordered by count descending.
​
device
string
Device category: Mobile, Tablet, or Desktop.
​
count
number
Total number of events (all types) from that device category in the requested window.
Response shape
[
  { "device": "Desktop", "count": 9410 },
  { "device": "Mobile",  "count": 4320 },
  { "device": "Tablet",  "count": 1093 }
]
StatusMeaning
200 OKQuery succeeded (empty array if no data)
400 Bad Requestdomain query parameter is missing
500 Internal Server ErrorDatabase query failed

​
Examples

curl "https://your-iris-host/api/devices?domain=example.com&from=2025-01-01&to=2025-01-31"

Build docs developers (and LLMs) love

Get started for freeTalk to us