How to Profile Notion API Request Latency for Custom Integration

When you build a custom integration with the Notion API, slow response times can break your workflow. You might notice that database queries take several seconds or that page updates hang before completing. This latency often comes from inefficient API calls, rate limiting, or network delays between your server and Notion servers. This article explains how to measure and profile each API request so you can identify the exact bottleneck and optimize your integration.

Why Notion API Latency Varies Between Requests

Notion API latency is the total time between sending a request and receiving the full response. This delay consists of three main components: network round-trip time, Notion server processing time, and response transfer time. Network round-trip time depends on your geographic distance to Notion servers, your internet connection quality, and DNS resolution speed. Notion server processing time varies by endpoint — querying a database with 5000 rows takes longer than fetching a single page. Rate limiting can also add artificial delays when you exceed 3 requests per second for a single integration.

The Notion API returns a special response header called x-notion-request-timing. This header contains a single floating-point number representing the number of milliseconds that Notion servers spent processing your request. By comparing this server time with your total measured time, you can separate network delays from server-side delays. If total time is 1200 ms and server time is 200 ms, the network accounts for 1000 ms of the latency.

Common Causes of High Latency

Three patterns cause most latency issues. First, fetching too many properties or rows in a single database query forces Notion to serialize large JSON payloads. Second, making many sequential requests instead of parallel ones compounds network overhead. Third, running your integration from a region far from Notion servers, such as Australia when the nearest endpoint is in the United States, adds 200 to 400 ms per request.

Steps to Measure Notion API Request Latency

You can profile latency using three methods: client-side timing in your code, inspecting response headers, and using browser Developer Tools when testing via the Notion API playground. The following steps assume you are using Node.js with the official Notion SDK or raw fetch calls.

1. Add console.time and console.timeEnd around each API call
   In your Node.js script, wrap every Notion API request with console.time('query-database') before the call and console.timeEnd('query-database') after the response is received. The console logs the elapsed time in milliseconds. Use a unique label for each endpoint so you can identify slow calls.
2. Read the x-notion-request-timing response header
   When using fetch, access response.headers.get('x-notion-request-timing') after the request completes. This value is the server processing time in milliseconds. For the Notion SDK, inspect the raw response object by setting logLevel: 'info' in the client configuration.
3. Calculate network latency by subtracting server time from total time
   Subtract the value from x-notion-request-timing from your console.timeEnd measurement. If the difference is greater than 300 ms, network delays are the dominant factor. If the server time is above 1000 ms, the bottleneck is on the Notion side.
4. Use the Notion API Playground in your browser
   Open the Notion API reference page at developers.notion.com, authenticate with your integration, and send a test request. Open your browser Developer Tools, go to the Network tab, and find the request to api.notion.com. The Timing tab shows a waterfall with DNS lookup, TCP connect, TLS handshake, request sent, waiting (server processing), and content download.
5. Run multiple requests and calculate average latency
   Create a script that sends the same request 10 times with a 1-second pause between each. Log every total time and server time, then compute the average. This smooths out transient network spikes and gives you a reliable baseline.

Using the Notion SDK for Automatic Timing

The official Notion JavaScript SDK does not expose latency by default, but you can create a wrapper function that intercepts every request. Define a function called timedRequest that records a start timestamp, calls the SDK method, records an end timestamp, reads the response header, and logs all three values. Replace every SDK call with this wrapper.

If Profiling Shows High Server-Side Time

When x-notion-request-timing consistently exceeds 1000 ms, the problem is on Notion servers. This is rare but can happen with large databases or complex filtered queries. The first step is to reduce the number of properties returned. Use the filter_properties parameter in your database query to request only the columns you need. If you need all properties, paginate with a smaller page size, such as 25 instead of 100.

Querying a Database Returns Data Slowly

If a database query takes more than 3 seconds, check the number of rows. Notion databases with more than 10,000 rows can cause high server times. Add a filter to narrow the result set before the query. For example, filter by a date range or a status property. This reduces the work Notion must do to serialize the response.

Rate Limiting Adds Delayed Responses

When you exceed 3 requests per second, Notion returns HTTP 429 with a Retry-After header. Your client-side timing will show a total time of several seconds because your code waits before retrying. Check your logs for 429 responses. If you see them, implement exponential backoff with a maximum wait of 30 seconds. Also batch your writes into a single request when possible using the append block children endpoint with multiple blocks.

Notion API Latency Factors Compared

Factor	Typical Impact	How to Measure
Network round-trip time	100–400 ms per request	console.time total minus x-notion-request-timing
Server processing time	50–2000 ms depending on query size	x-notion-request-timing header
Rate limiting delay	1000–30000 ms per retry	HTTP 429 status code and Retry-After header
Response payload size	10–500 ms per 100 KB	Content-Length header and download time in DevTools

You now have three concrete methods to profile Notion API latency: client-side console timing, the x-notion-request-timing header, and browser DevTools waterfall charts. Start by running a baseline test on your most frequent endpoint. If server time is high, reduce the number of properties or rows in your query. If network time is high, move your integration closer to Notion servers using a cloud function in us-east-1 or eu-west-1. An advanced tip: add a custom X-Request-Id header to every request so you can correlate logs between your application and Notion support if you need to escalate a persistent latency issue.