Skip to content
throttle
Menu
HomeAPI LimitsNotion API

Productivity

Notion API

APIs for Notion pages, blocks, data sources, comments, search, files, and integrations.

PUBLISHED PROVIDER LIMITS

Limits keep their provider-specific dimensions.

Connections have a plan-specific request budget per 60 seconds that can be spent in a burst. Data-source queries and the shared workspace pool impose separate limits.

Authentication: Internal integration token, OAuth access token

Primary scope: Connection, Plus A Shared Workspace Pool

Measured dimensions: Requests, Endpoint Requests, Workspace Capacity

Profile coverage: Plan-specific per-connection windows, the separate data-source query limit, shared workspace capacity, Retry-After, and overload and restricted-access responses. Payload size and property-specific request limits remain outside this profile.

Connection Rate

Notion API Connection Rate
LimitValuePeriodScopeConditions and variability
Per-connection budget: other plans180 requestsPer 60 secondConnectionPlans other than Business and Enterprise The budget may be spent at any pace within the 60-second window.
Per-connection budget: Business and Enterprise600 requestsPer 60 secondConnectionBusiness or Enterprise workspace The budget may be spent at any pace within the 60-second window.

Endpoint limits

Notion API Endpoint limits
LimitValuePeriodScopeConditions and variability
Data-source queries3 requestsPer secondConnection And EndpointApproximately three data-source queries per second per connection, separately from the general connection budget.

Workspace Rate

Notion API Workspace Rate
LimitValuePeriodScopeConditions and variability
Workspace-level shared limitProvider-specificProvider-definedWorkspaceWorkspace capacity scales with the workspace plan and is shared by all connections in the workspace.

RESPONSE METADATA

Headers expose the applicable limit state.

Retry-AfterFormat: Integer Seconds
Integer seconds to wait before retrying.

WHEN A LIMIT IS EXCEEDED

Read the response before choosing a delay.

  • Rate-limit responses can use HTTP 429 or HTTP 529.
  • HTTP 429 can identify a connection, workspace, or endpoint limit. HTTP 529 with service_overload is temporary overload. A 429 with public_api_request_blocked requires support rather than retries.
  • Additional Data.rate Limit Reason: Machine-readable reason associated with the applied request limit.
  • Additional Data.retry After: Wait in whole seconds, represented as a string when Retry-After is supplied.

RECOMMENDED HANDLING

Protect both the provider and your own queue.

  • Honor Retry-After on retryable 429 and 529 responses; workspace waits can exceed one minute.
  • Stop retrying public_api_request_blocked and contact Notion support.
  • Track the plan-specific connection window, data-source query limit, and shared workspace budget separately.
  • Use bounded exponential backoff with jitter; retry server errors only when the operation is safe to repeat.

VERIFICATION RECORD

Official sources reviewed