# How to Automate Notion Task Management using the API

- Tool: API Automations
- Difficulty: Beginner
- Fix time: 15-30 minutes
- Compatibility: Free — internal Notion integration (workspace owner access required to create integration)
- Last updated: May 2026

## TL;DR

Automate Notion task management by polling overdue tasks with POST /v1/data_sources/{id}/query and updating their status property via PATCH /v1/pages/{id}. Every request must include the Notion-Version: 2025-09-03 header or you get a 400 missing_version error. The key rate limit is 3 requests/second per integration — batching status updates for large boards requires careful throttling.

## Best practices

- Always include the Notion-Version: 2025-09-03 header — pin this in a constants file so you never accidentally omit it
- Fetch the database schema once at startup to validate property names and option values before running bulk updates
- Use the filter parameter server-side rather than fetching all tasks and filtering in memory — this reduces both API calls and processing time
- Process status updates with 350ms delays between requests to stay under the 3 req/s rate limit even during burst operations
- Check response status_code before accessing the response body — do not assume a 200 response for every call
- Use the has_more and next_cursor fields to paginate large result sets rather than assuming all results fit in the first page
- Store the data_source_id alongside the database_id in your configuration — the two are different IDs and both are needed

## Frequently asked questions

### What is the difference between /v1/databases/{id}/query and /v1/data_sources/{id}/query?

In Notion API version 2022-06-28, you queried database rows with POST /v1/databases/{id}/query. Starting with version 2025-09-03, Notion restructured databases as containers holding one or more 'data sources,' and row-level queries moved to POST /v1/data_sources/{id}/query. If you send the old query endpoint with Notion-Version: 2025-09-03, you will get a 404 or unexpected behavior. Fetch your database with GET /v1/databases/{id} to find the data_sources[0].id value.

### Why do I get a 404 object_not_found even though the database exists?

Notion returns 404 (not 403) when a resource is not shared with your integration. Open the database in Notion, click the '...' menu, go to Connections, and connect your integration. The 404 behavior is intentional — Notion treats unshared pages as non-existent from the integration's perspective to avoid information leakage.

### How do I get the data_source_id for my database?

Call GET /v1/databases/{database_id} and look at the data_sources array in the response. The first element's id is your data_source_id. The database_id is the UUID in the Notion URL: notion.so/workspace/DATABASE_ID?v=viewId. Copy only the UUID part, not the view parameter.

### What happens when I hit the Notion API rate limit?

Notion returns HTTP 429 with a Retry-After header containing the number of seconds to wait. The body is {"object":"error","status":429,"code":"rate_limited","message":"..."}. Read the Retry-After value and sleep for that duration before retrying. To avoid hitting the limit, keep your request rate below 3 per second — a 350ms delay between sequential requests keeps you safely under the threshold.

### Is the Notion API free?

Yes, the Notion API is free to use regardless of your Notion plan. There is no paid API tier, and the rate limit (3 req/s) is the same for all plans. However, some Notion features (like automation buttons and webhooks) may require paid workspace plans.

### Can I update multiple task properties in a single PATCH request?

Yes. The PATCH /v1/pages/{id} endpoint accepts a properties object with multiple keys. For example: {"properties": {"Status": {"status": {"name": "Done"}}, "Due Date": {"date": {"start": "2026-05-10"}}}} updates both Status and Due Date in one request. This is more efficient than separate requests.

### Why does my filter return no results even though I can see matching tasks in Notion?

The most common cause is a property name mismatch — Notion property names are case-sensitive. If your database has a property named 'due date' (lowercase) but your filter uses 'Due Date', the filter will silently return no matches. Fetch the database schema with GET /v1/databases/{id} and copy the exact property names from the properties object.

### Can RapidDev help build a custom Notion integration?

Yes. RapidDev has built 600+ apps including numerous Notion automations for task management, CRM pipelines, and content workflows. We can build a fully managed integration tailored to your workspace structure. Reach out for a free consultation at rapidevelopers.com.

---

Source: https://www.rapidevelopers.com/api-automations/how-to-automate-notion-task-management-using-the-api
© RapidDev — https://www.rapidevelopers.com/api-automations/how-to-automate-notion-task-management-using-the-api