Reports Beta
Uptime and performance reports for one monitor: how much of a period it was up, when it went down, how fast it responded, and where it was checked from.
Every report needs an X-API-Key header whose owner has access to uptime monitoring in the app, and each call counts once against your daily quota. See Monitoring API: getting started for authentication, rate limits and errors. For individual checks, use Results.
Reports
| Report | Answers | Default window | Longest window |
|---|---|---|---|
| Summary | Uptime %, downtime, outages and response times for a period | 7 days | 1830 days |
| Outages | Each outage, and an up, down, maintenance and unknown timeline | 7 days | 1830 days |
| Performance | Checks and response times per hour, day or week | 1 day (hour), 30 days (day, week) | 31 days (hour), 400 (day), 800 (week) |
| Hours of day | Average response time at each hour of the day | 7 days | 92 days |
| Probes | Checks and response times per location | 7 days | 1830 days |
All five are GET requests under /api/v1/monitors/{id}/.
How the reports count time
- Windows.
fromandtotake ISO 8601 or UNIX seconds.todefaults to now, andfromto the default window beforeto.frommust be beforeto. - Unknown time. Any part of the window before the monitor was created, and any time it was paused, counts as unknown. Unknown time never counts as up, and it's left out of the uptime percentage.
- Maintenance. Time inside a maintenance window that covers the monitor counts as maintenance, not downtime, and is also left out of the uptime percentage. Unknown time takes priority over maintenance.
- Downtime runs from the first failed check to the next successful one. Checks are retry-confirmed, so a single blip doesn't start an outage.
- Response times (
avgResponseMs,minResponseMs,maxResponseMs) only use successful checks. They'renullwhen there are none. - Every response includes
id,fromandto, withtobrought back to now if you asked for a time in the future, plus theusageobject. - All times are UTC. Hours, days and weeks are UTC hours, days and weeks, and weeks start on Monday.
- History. Individual check results are kept for 400 days. Summaries, outages, probes and daily or weekly performance cover longer periods from daily totals.
Example: last month's uptime for every monitor
List your monitors, then ask for each one's summary. This uses one request for the list plus one per monitor.
monthly-uptime.sh
- #!/usr/bin/env bash
- set -euo pipefail
- API="https://www.ranknibbler.com/api/v1"
- FROM="2026-08-01T00:00:00Z"; TO="2026-09-01T00:00:00Z"
- curl -fsS -H "X-API-Key: $RANKNIBBLER_API_KEY" "$API/monitors?per=1000" \
- | jq -r '.monitors[] | .id' \
- | while read -r id; do
- curl -fsS -H "X-API-Key: $RANKNIBBLER_API_KEY" "$API/monitors/$id/summary?from=$FROM&to=$TO" \
- | jq -r '[.id, (.uptimePct // "n/a"), .outages, .downSeconds] | @tsv'
- sleep 1
- done