How to Automate Notion Task Management using the API

Understanding the Notion API

Setting Up Notion API Authentication

Notion uses long-lived Bearer tokens for internal integrations — there is no OAuth flow required for automating your own workspace. Tokens issued on or after 2024-09-25 use the ntn_ prefix. The token must be passed as an Authorization: Bearer header on every request alongside the mandatory Notion-Version header.

1. 1Go to notion.so/my-integrations (you must be a workspace owner)
2. 2Click 'New integration' and give it a name (e.g., 'Task Automation')
3. 3Under Capabilities, enable: Read content, Update content, Insert content
4. 4Click Save and copy the Internal Integration Secret (starts with ntn_)
5. 5Open your task database in Notion, click the '...' menu at the top right
6. 6Click 'Connections' and search for your integration name, then click Connect
7. 7Store the token in an environment variable: export NOTION_TOKEN=ntn_your_token_here

1import os
2import requests
3
4NOTION_TOKEN = os.environ['NOTION_TOKEN']
5
6headers = {
7    'Authorization': f'Bearer {NOTION_TOKEN}',
8    'Notion-Version': '2025-09-03',
9    'Content-Type': 'application/json'
10}
11
12# Verify auth works by fetching the integration's bot user
13response = requests.get('https://api.notion.com/v1/users/me', headers=headers)
14if response.status_code == 200:
15    print('Auth OK:', response.json()['name'])
16else:
17    print('Auth failed:', response.status_code, response.text)

Key endpoints

1{"filter":{"and":[{"property":"Status","status":{"equals":"To Do"}},{"property":"Due Date","date":{"before":"2026-05-07"}}]},"sorts":[{"property":"Due Date","direction":"ascending"}],"page_size":100}

1{"object":"list","results":[{"object":"page","id":"page-id-here","properties":{"Name":{"title":[{"plain_text":"Fix login bug"}]},"Status":{"status":{"name":"To Do"}},"Due Date":{"date":{"start":"2026-05-06"}}}}],"next_cursor":null,"has_more":false}

1{"properties":{"Status":{"status":{"name":"Overdue"}}}}

1{"object":"page","id":"page-id-here","properties":{"Status":{"id":"abc","type":"status","status":{"id":"status-id","name":"Overdue","color":"red"}}},"last_edited_time":"2026-05-07T10:00:00.000Z"}

1{"object":"database","id":"db-id-here","title":[{"plain_text":"Tasks"}],"properties":{"Status":{"id":"prop-id","type":"status","status":{"options":[{"id":"opt1","name":"To Do","color":"gray"},{"id":"opt2","name":"In Progress","color":"blue"},{"id":"opt3","name":"Done","color":"green"},{"id":"opt4","name":"Overdue","color":"red"}]}}},"data_sources":[{"id":"ds-id-here"}]}

Step-by-step automation

1curl -X GET 'https://api.notion.com/v1/databases/YOUR_DATABASE_ID' \
2  -H 'Authorization: Bearer $NOTION_TOKEN' \
3  -H 'Notion-Version: 2025-09-03'

1curl -X POST 'https://api.notion.com/v1/data_sources/YOUR_DATA_SOURCE_ID/query' \
2  -H 'Authorization: Bearer $NOTION_TOKEN' \
3  -H 'Notion-Version: 2025-09-03' \
4  -H 'Content-Type: application/json' \
5  -d '{
6    "filter": {
7      "and": [
8        {"property": "Status", "status": {"equals": "To Do"}},
9        {"property": "Due Date", "date": {"before": "2026-05-07"}}
10      ]
11    },
12    "sorts": [{"property": "Due Date", "direction": "ascending"}],
13    "page_size": 100
14  }'

1curl -X PATCH 'https://api.notion.com/v1/pages/PAGE_ID_HERE' \
2  -H 'Authorization: Bearer $NOTION_TOKEN' \
3  -H 'Notion-Version: 2025-09-03' \
4  -H 'Content-Type: application/json' \
5  -d '{"properties": {"Status": {"status": {"name": "Overdue"}}}}'

1curl -X POST 'https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK' \
2  -H 'Content-Type: application/json' \
3  -d '{"text": ":warning: 3 Notion tasks moved to Overdue: Fix login bug, Update docs, Review PR"}'

Complete working code

This complete script polls a Notion task database for items with status 'To Do' that are past their due date, marks them all as 'Overdue', and posts a summary to a Slack webhook. It handles pagination for large boards and respects the 3 req/s rate limit with 350ms delays between PATCH calls.

1import os
2import time
3import requests
4from datetime import date
5
6NOTION_TOKEN = os.environ['NOTION_TOKEN']
7DATA_SOURCE_ID = os.environ['NOTION_DATA_SOURCE_ID']
8SLACK_WEBHOOK_URL = os.environ.get('SLACK_WEBHOOK_URL')
9
10HEADERS = {
11    'Authorization': f'Bearer {NOTION_TOKEN}',
12    'Notion-Version': '2025-09-03',
13    'Content-Type': 'application/json'
14}
15
16def query_overdue_tasks():
17    today = date.today().isoformat()
18    tasks = []
19    cursor = None
20    while True:
21        payload = {
22            'filter': {'and': [
23                {'property': 'Status', 'status': {'equals': 'To Do'}},
24                {'property': 'Due Date', 'date': {'before': today}}
25            ]},
26            'page_size': 100
27        }
28        if cursor:
29            payload['start_cursor'] = cursor
30        resp = requests.post(
31            f'https://api.notion.com/v1/data_sources/{DATA_SOURCE_ID}/query',
32            headers=HEADERS, json=payload
33        )
34        resp.raise_for_status()
35        data = resp.json()
36        tasks.extend(data['results'])
37        if not data['has_more']:
38            break
39        cursor = data['next_cursor']
40    return tasks
41
42def update_status(page_id, status_name):
43    resp = requests.patch(
44        f'https://api.notion.com/v1/pages/{page_id}',
45        headers=HEADERS,
46        json={'properties': {'Status': {'status': {'name': status_name}}}}
47    )
48    if resp.status_code == 429:
49        retry_after = int(resp.headers.get('Retry-After', 5))
50        time.sleep(retry_after)
51        return update_status(page_id, status_name)
52    resp.raise_for_status()
53    return resp.json()
54
55def post_to_slack(task_names):
56    if not task_names or not SLACK_WEBHOOK_URL:
57        return
58    names = ', '.join(task_names[:10])
59    if len(task_names) > 10:
60        names += f' ...and {len(task_names) - 10} more'
61    requests.post(SLACK_WEBHOOK_URL, json={
62        'text': f':warning: {len(task_names)} task(s) marked Overdue: {names}'
63    })
64
65def main():
66    print('Querying overdue tasks...')
67    tasks = query_overdue_tasks()
68    print(f'Found {len(tasks)} overdue tasks')
69    updated_names = []
70    for task in tasks:
71        title = task['properties'].get('Name', {}).get('title', [])
72        name = title[0]['plain_text'] if title else 'Untitled'
73        update_status(task['id'], 'Overdue')
74        updated_names.append(name)
75        print(f'  Updated: {name}')
76        time.sleep(0.35)
77    post_to_slack(updated_names)
78    print('Done.')
79
80if __name__ == '__main__':
81    main()

Error handling

Rate Limits for Notion API

1import time
2import requests
3
4def notion_request(method, url, headers, **kwargs):
5    for attempt in range(5):
6        resp = getattr(requests, method)(url, headers=headers, **kwargs)
7        if resp.status_code == 429:
8            retry_after = int(resp.headers.get('Retry-After', 2 ** attempt))
9            print(f'Rate limited. Waiting {retry_after}s...')
10            time.sleep(retry_after)
11            continue
12        return resp
13    raise Exception('Max retries exceeded')

• Add 350ms delays between sequential requests to stay safely under the 3 req/s average
• Batch your status updates during off-peak hours to reduce the impact on interactive Notion users on the same workspace
• Cache the database schema (GET /v1/databases/{id}) locally — it does not change frequently and wastes a request slot each run
• Use the filter parameter in POST /v1/data_sources/{id}/query instead of fetching all pages and filtering in code
• Monitor the Retry-After header value — a persistently high value indicates you need to reduce your request frequency

Security checklist

Automation use cases

No-code alternatives

Don't want to write code? These platforms can automate the same workflows visually.

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

Ask AI to help

Copy one of these prompts to get a personalized, working implementation.

Related automations

Explore related guides

Guides from other topics that help with this issue