Monitoring API Beta
Manage your uptime monitors and read their results from your own code. These are the same monitors you see on the Uptime page in the app: anything you create or change here shows up there, and the other way round.
What you can do
| Task | Endpoint | Reference |
|---|---|---|
| List your monitors, with filters | GET /api/v1/monitors | List monitors |
| Create a monitor | POST /api/v1/monitors | Create a monitor |
| Read one monitor, with uptime and settings | GET /api/v1/monitors/{id} | Get a monitor |
| Change a monitor's settings | PATCH /api/v1/monitors/{id} | Update a monitor |
| Pause or resume a monitor | POST /api/v1/monitors/{id}/pause and /resume | Pause and resume |
| Delete a monitor | DELETE /api/v1/monitors/{id} | Delete a monitor |
| Pause, resume or re-time many monitors at once | PATCH /api/v1/monitors | Bulk update |
| Delete many monitors at once | DELETE /api/v1/monitors?ids=… | Bulk delete |
| Check a port, ping, DNS record or mail server | type on a monitor | Check types |
| Get the allowed value for every setting | GET /api/v1/monitors/options | Setting options |
| Read raw check results | GET /api/v1/monitors/{id}/results | Results |
| Uptime %, downtime and response times for a period | GET /api/v1/monitors/{id}/summary | Summary |
| List outages, with an up/down timeline | GET /api/v1/monitors/{id}/outages | Outages |
| Response times per hour, day or week | GET /api/v1/monitors/{id}/performance | Performance |
| Response time by hour of the day | GET /api/v1/monitors/{id}/hours-of-day | Hours of day |
| Checks per location | GET /api/v1/monitors/{id}/probes | Probes |
| Schedule maintenance, one-off or repeating | POST /api/v1/maintenance | Create a window |
| List, change or delete maintenance windows | GET, PATCH, DELETE /api/v1/maintenance/{id} | Maintenance windows |
| Move or cancel a single occurrence | PATCH, DELETE /api/v1/maintenance/occurrences/{id} | Occurrences |
| See why a monitor went down | GET /api/v1/monitors/{id}/analysis | Analysis list |
| Trace the path to a host | GET /api/v1/traceroute | Traceroute |
| Read the history of alerts sent | GET /api/v1/alerts | Alert history |
| Manage the people alerted without a login | GET, POST /api/v1/alerting/contacts | Alert contacts |
| Group people into a team to alert | GET, POST /api/v1/alerting/teams | Alert teams |
When a monitor goes down we work out why. A monitor can check a web page, a TCP or UDP port, ping, a DNS record or a mail server: see Check types. Alerts go to a monitor's members, contacts and teams. Individual check results are kept for 400 days; summaries, outages and daily performance cover longer periods.
Just want a one-off up/down check of a URL, without saving a monitor? Use the Uptime endpoint instead.
Authentication
Send your API key in the X-API-Key header on every request.
- X-API-Key: rnk_live_…
A key acts as the account that created it, inside that person's workspace and with their app permissions:
- Viewing monitors and their results needs access to uptime monitoring in the app.
- Creating, changing, pausing and deleting monitors needs permission to manage uptime monitors.
If the owner's permissions change in the app, the key follows straight away. Calls without the right permission get 403.
Creating a key. Sign in and go to Developer › API keys (/app/api/api-keys). The key is shown once, so copy it somewhere safe. An older key that isn't linked to an account gets 403 from every monitoring endpoint; create a new one from your account instead. See API keys for more.
Keep keys out of source control and browser code. Anyone holding the key can change your monitors.
Quotas
Every call counts once against your account's daily API quota. It's the same quota the rest of the RankNibbler API uses: shared across all of your keys, and reset at 00:00 UTC. The free plan includes 100 requests a day. See Rate limits for the allowance on each plan, Pricing to compare plans, and Usage to read where you stand.
Requests turned away before your key is accepted (a missing or invalid key, a key not linked to a workspace, or a burst limit) don't count. Everything after that does, including a 400 or 404.
The number of monitors you can have depends on your plan, not on the API quota. When you reach it, creating another monitor returns 409.
Rate limits
| Limit | Applies to | When exceeded |
|---|---|---|
| 30 requests per 10 seconds | Each API key | 429 with Retry-After: 10 |
| 60 requests per 10 seconds | Each IP address | 429 with Retry-After: 10 |
| 30 writes per minute | Each API key (every method except GET) | 429 with Retry-After: 60 |
| Daily quota | Your account | 429 with Retry-After set to the seconds until midnight UTC |
Retry-After is always in seconds. Wait at least that long before trying again.
Rate-limit headers
Every response to an accepted key carries these headers:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Your daily request allowance. |
X-RateLimit-Remaining | Requests left today, after this one. |
X-RateLimit-Reset | Seconds until the daily quota resets (00:00 UTC). |
On a plan with no daily limit, X-RateLimit-Limit and X-RateLimit-Remaining are left out. The headers are exposed to browsers through CORS.
The usage object
Successful responses also include a usage object. dailyLimit is null on a plan with no daily limit.
- "usage": { "used": 37, "dailyLimit": 100, "tier": "free" }
Errors
Errors come back as JSON with a readable message:
- { "error": "You’re already monitoring this exact URL. Add a different page or subdomain instead." }
| Status | When |
|---|---|
400 | A setting or parameter isn't valid, the body isn't valid JSON, or the body is too large. The URL is private, local or blocked, or its domain can't be reached. |
401 | The API key is missing or invalid. |
403 | The key's owner doesn't have permission for this action, or the key isn't linked to a workspace. |
404 | No monitor with that id in your workspace, or no such endpoint. |
405 | The endpoint doesn't accept that HTTP method. |
409 | The URL is already monitored in your workspace, or your plan's monitor limit is reached. |
429 | A rate limit or your daily quota was hit. Read Retry-After. The daily-quota response also includes used and limit. |
500 | Something went wrong on our side. Try again. |
503 | The API is temporarily unavailable. Try again shortly. |
Build your error handling on the status code. The message text is for people and may change.
Conventions
- Base URL:
https://www.ranknibbler.com/api/v1. Always use HTTPS. - Request bodies are JSON objects sent with
Content-Type: application/json, up to 64 KB. - Field names are camelCase. Times are ISO 8601 in UTC, for example
2026-09-17T09:30:00.000Z. fromandtoaccept ISO 8601 (2026-09-01T00:00:00Z) or UNIX seconds (1788220800).- Monitor ids look like
mon_79ce3cf9c4fa56e98af4. Treat them as opaque strings. - Paging uses
page(starting at 1) andper(items per page). List responses includetotal,pageandper. - CORS is open (
Access-Control-Allow-Origin: *) forGET,POST,PUT,PATCH,DELETEandOPTIONS. Even so, don't put a key in public browser code.
Quick start
Three calls with curl: list your monitors, add one, then read its results. Replace rnk_live_… with your key.
1. List your monitors
- {
- "total": 1, "page": 1, "per": 100,
- "monitors": [
- { "id": "mon_79ce3cf9c4fa56e98af4", "name": "Homepage", "url": "https://example.com/",
- "status": "up", "active": true, "responseMs": 142, "uptime24h": 100, … }
- ],
- "usage": { "used": 1, "dailyLimit": 100, "tier": "free" }
- }
2. Create a monitor
Only url is required. Everything else uses the defaults, and a first check runs straight away.
- {
- "monitor": {
- "id": "mon_4b1d0a7e2c9f83d56e10", "name": "Pricing page",
- "url": "https://example.com/pricing", "status": "up", "statusCode": 200,
- "responseMs": 188, "intervalMinutes": 5, …
- },
- "usage": { "used": 2, "dailyLimit": 100, "tier": "free" }
- }
3. Read its results
With no from or to, you get the last 24 hours, newest first.
- {
- "id": "mon_4b1d0a7e2c9f83d56e10",
- "from": "2026-09-16T09:31:00.000Z", "to": "2026-09-17T09:31:00.000Z",
- "total": 1, "page": 1, "per": 100,
- "results": [
- { "checkedAt": "2026-09-17T09:30:58.412Z", "status": "up", "statusCode": 200,
- "responseMs": 188, "error": null, "region": "default" }
- ],
- "usage": { "used": 3, "dailyLimit": 100, "tier": "free" }
- }
Next, read the full Monitors reference for every setting, Results for filtering and paging, or Reports for uptime summaries, outages and performance.
Planned additions
We're working on more of the monitoring product for the API. These are plans, not promises, and there are no dates yet. Everything above is available today.
- Transaction checks: scripted multi-step browser checks, such as logging in or checking out.
If one of these matters to you, let us know. It helps us decide what comes first.
Frequently asked questions
Are these the same monitors as the Uptime page in the app?
Yes. The Monitoring API reads and changes the monitors in your workspace, so a monitor created through the API shows up on the Uptime page straight away, and the other way round. The same validation, plan limits and alert settings apply to both.
Which API key should I use for the Monitoring API?
A key created from your account under Developer › API keys. The key acts as the person who created it, inside their workspace and with their app permissions. Viewing monitors needs access to monitoring in the app, and creating, changing, pausing or deleting them needs permission to manage uptime monitors. An older key that is not linked to an account gets a 403.
Do Monitoring API calls count against my daily API quota?
Yes. Every call counts once against your account's daily API quota, the same quota as the rest of the RankNibbler API. It is shared across all your keys and resets at 00:00 UTC. The free plan includes 100 requests a day.
What happens when I create a monitor through the API?
The monitor is saved with your settings, and defaults for anything you leave out, and a first check runs straight away so the response already has a status. If you do not send recipients, the key's owner gets the alerts.