API Monitoring Guide
Get alerted when the Notion API has issues before your database sync stalls, your published site goes stale, or your internal tools stop reading from Notion. Know the Notion API status in real time, not 15 minutes later.
Teams increasingly run dashboards, public sites, CRMs, and internal tools on top of Notion as a backend. When the REST API at api.notion.com/v1 slows down or returns errors, your sync jobs fall behind, page builds fail, and automations silently stop — often with no visible error until someone notices stale data.
This guide covers everything you need to monitor Notion API status: which endpoints to track, how the 3 requests/second limit and required Notion-Version header work, how to tell an outage from a sharing/permission problem, and what to do when the API goes down.
Notion maintains a status page at status.notion.so for platform-wide incidents. It's worth bookmarking, but relying on it as your only signal leaves real gaps.
External synthetic monitoring catches Notion API issues in 1-2 minutes, not 10-15. That head start lets you pause sync jobs, serve from cache, or flag stale data before your users hit it.
The Notion API is a single REST surface at api.notion.com/v1, but a few quirks shape how you monitor it.
Always send a specific Notion-Version like 2025-09-03. Omitting it returns an error, and a surprise version change can alter response shapes and break your body validation. Update the version deliberately, not implicitly.
Notion's access model is explicit: an integration only sees pages and databases that have been shared with it. That makes "is this page reachable?" a meaningful health signal — losing access is a common, silent failure that looks nothing like a platform outage.
Each endpoint below tests a different concern. Monitoring several lets you pinpoint whether a problem is the API, your token, or lost access to specific content.
GET https://api.notion.com/v1/users/me
Bot user. The lightest health check: confirms the API is up and your integration token is valid. Returns your integration's bot user object. Make this your primary Notion health monitor. Validate the body contains "bot".
POST https://api.notion.com/v1/databases/{id}/query
Database query. Confirms the read path your sync depends on works and that the database is still shared with the integration. Send {"page_size": 1} to keep it cheap. A 404 here means access was removed, not that Notion is down.
GET https://api.notion.com/v1/pages/{id}
Page retrieval. Monitor a critical page (e.g. one that feeds a public site or dashboard). Confirms the page is reachable and the API returns valid properties. Good for content-driven sites built on Notion.
GET https://api.notion.com/v1/blocks/{id}/children?page_size=1
Block children. If you render Notion page content (a wiki, docs, or blog), this confirms block retrieval works. Block reads are where many content integrations actually break.
GET https://your-app.example.com/health
Your sync worker's health endpoint. Catches failures on your side — a crashed sync job or a queue backup — that Notion's status page will never show. Pair it with the Notion checks to separate "Notion is down" from "my sync is stuck".
Rate limit note: Notion averages ~3 requests/second per integration. A monitor checking a few endpoints every 1-5 minutes is far under that. Avoid sub-minute intervals across many endpoints on the same token, and keep heavy sync jobs on a separate integration so they don't 429 your health checks.
Notion's rate limiting is strict compared to many APIs, and it can easily masquerade as an outage during bulk operations. Understanding it is essential for both reliable sync and accurate alerting.
The average rate limit is three requests per second per integration, with brief bursts tolerated. Exceed it and Notion returns a rate_limited error code with HTTP 429.
Respect Retry-After (seconds) before retrying.
There's also a workspace-level limit shared across all integrations in that workspace and scaled to the plan. The error's rate_limit_reason tells you which limit you hit — the integration's or the workspace's.
During heavy load, Notion may return HTTP 529 (a non-standard "overloaded" code). Treat it like a 429: back off and retry. Your monitor should alert on sustained 529s as a degradation signal.
A 429 means you're throttled — back off using Retry-After. A 503 or widespread timeouts point to an actual Notion incident, while a 404 usually means lost access to a specific object. UptimeSignal records status codes and response times so you can tell throttling, access loss, and real outages apart.
Your tools run on the Notion API. Monitor it yourself.
Get alerted when the Notion API, your token, or a shared database start failing — before your sync silently serves stale data. Free for 25 endpoints, checks every 5 minutes.
Monitor Notion API free →Knowing the common failure patterns helps you configure monitoring that catches real problems and avoids false alerts.
If a teammate removes the integration's access to a page or database, calls that worked yesterday return 404 or a restricted_resource error. Monitoring a specific object surfaces this immediately — the API itself is fine, but your sync is blind.
If the integration token is regenerated or revoked, every call returns 401 Unauthorized. Monitoring /v1/users/me catches this so you can redeploy with the new token before sync goes dark.
A deploy that drops or changes the Notion-Version header causes errors that look like an outage. Pin the version in your monitor and in your app, and validate response bodies to catch version-driven shape changes.
A full re-sync can blow past 3 req/s and trigger cascading 429s. Sustained 429s on your monitor signal that a job needs better backoff or pagination, not that Notion is down.
During incidents, Notion response times climb and 529 "overloaded" responses appear. Tracking response time lets you catch degradation before it becomes a full outage and your sync windows start overrunning.
At notion.so/my-integrations, create an internal integration and copy its token. Then, in Notion, share the specific pages/databases you want to monitor with that integration (the ••• menu → Connections).
Security tip: Use a read-only integration scoped to just the content you monitor. Don't reuse a token with write access to your whole workspace.
Sign up at app.uptimesignal.io and add a new HTTP monitor:
The Notion-Version header is required — without it the request fails.
Add a database-query monitor for the database your sync depends on and a page monitor for any page that feeds a public surface. These catch lost-access (404) issues that the auth check won't.
Route alerts where you'll act on them:
If Notion feeds a public site or live dashboard, use 1-minute checks (Pro plan) so stale data or lost access is caught within a minute instead of five.
Configure your monitors to alert on these conditions:
For /users/me, check for "bot"; for a database query, check for "results". Body validation confirms you got a real Notion object rather than an error envelope, and it catches response-shape changes when the Notion-Version moves underneath you.
When monitoring alerts you to a Notion problem, here's how to respond and limit the impact.
Check status.notion.so. Determine whether it's auth (401), lost access (404), rate limiting (429), or a real outage (500/503/529). Each needs a different response.
If a public site or dashboard reads from Notion, serve the last-good cached snapshot so visitors don't see errors or blanks. A read-through cache turns a Notion outage into a no-op for your users.
If your integration writes to Notion, pause those jobs and queue them with idempotency keys. Retrying into a rate limit or outage just compounds the problem.
If only specific objects are failing with 404, it's almost certainly an access change, not an outage. Re-share the page/database with your integration and the monitor should recover immediately.
Note any stale-data window for your team, and update your status page if a user-facing surface is affected. Link Notion's official status post when it's an upstream incident.
curl -H "Authorization: Bearer YOUR_TOKEN" -H "Notion-Version: 2025-09-03" https://api.notion.com/v1/users/me. For continuous monitoring, set up UptimeSignal to poll every 1-5 minutes and alert you instantly when the status changes.
GET /v1/users/me as a lightweight auth + health check, add a POST /v1/databases/{id}/query for the database your sync depends on, and a GET /v1/pages/{id} for a critical page. Always include the required Notion-Version header so requests aren't rejected.
rate_limited error with HTTP 429 and a Retry-After header. Notion may also return HTTP 529 when overloaded — back off in both cases.
Notion-Version header (e.g. 2025-09-03). Without it the API returns an error that looks like an outage. Pin a specific version in your monitor and update it deliberately when you migrate, since response shapes can change between versions and break body validation.
restricted_resource errors even though the API is healthy. Monitoring a specific page/database surfaces this access loss immediately, separate from a real outage.
POST /v1/databases/{id}/query for the database your sync depends on and validate that results come back. This confirms the API is up, your token is valid, and the database is still shared. Stay within the 3 req/s budget by checking every 1-5 minutes rather than continuously.
UptimeSignal checks your endpoints from outside your network and catches errors before users do.
25 monitors free, unlimited for $10/month.
No password needed. We'll send a magic link.