# Notion

Create, find and update pages in Notion databases, write and read page content as Markdown or blocks, comment, and look up databases, data sources and users.

## Connect Notion

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `notion` and choose **Notion**.
3. Choose **Sign in with Notion**.
4. Press **Sign in with Notion** at the bottom of the sheet, then choose your account in Notion’s window and allow access.

Or choose **Paste your integration secret or access token**, paste it, and press **Test and save**. It stays until someone deletes it.

Sign in with Notion and pick the pages the connection may use, or paste a token: an internal integration secret (notion.so/profile/integrations → New integration; then share each page or database with it under ••• → Connections) or a personal access token.

**What if it says “Sign-in isn’t set up here yet”?**

Signing in with Notion needs a Notion app on this installation, and it has none yet. Until it is set up, **Paste your integration secret or access token** works without it.

**On Cloud:** The sheet says “It’s set up once for everyone who uses this service, not by an organization.”

**Self-hosted:** An admin of the installation sees **Set up Notion sign-in** instead, and sets it up once for everyone. Everyone else sees who to ask.

1. Create an app in Notion’s developer settings ([Notion’s guide](https://www.notion.so/profile/integrations)).
2. In GoRunner, copy the **Redirect address to add in Notion’s developer settings**, and add it to the app.
3. Paste the **Client ID** and **Client secret**, then press **Save and sign in**.

[Set up a sign-in app](https://docs.gorunner.io/self-host/oauth-apps#other-providers)

**Can I use my own Notion app?**

Yes. In the sheet, open **Use your own Notion app** and paste its **Client ID** and **Client secret**. Add the redirect address it shows to your app first. The connection then signs in through your app instead of the installation’s.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Start a workflow

Add a trigger and choose **Notion**. The trigger uses the same connection as the steps.

### On Page Added or Updated

Checks a Notion database about once a minute and starts a run for each page added, or changed, since the check before. The first check after publishing only takes note of what is there (it starts nothing); changing the trigger starts over the same way. It reads every page of the database (at most 2,000; use a filter for a bigger one), and a page that leaves the filter and comes back counts as added again.

- **Database · Required**: The database (data source) to watch.
- **Trigger on · Required**: Which changes start a run. Options: Page added, Page updated, Page added or updated. Default: Page added.
- **Only Pages Matching · Optional**: Watch only the pages this Notion filter keeps, such as {"property": "Status", "status": {"does_not_equal": "Done"}}. Empty watches every page.

A later step can use its data, such as `{{trigger.change_type}}`, `{{trigger.created_time}}`, `{{trigger.id}}` and 5 more. See [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Do things in Notion

Add a **Notion** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Database Page](https://docs.gorunner.io/apps/notion#fields-f-databasepage): Create · Get · Get Many · Update
- [Page](https://docs.gorunner.io/apps/notion#fields-f-page): Create · Get Markdown · Update Markdown · Search · Archive · Restore
- [Block](https://docs.gorunner.io/apps/notion#fields-f-block): Append After · Get Many · Get Markdown · Delete
- [Comment](https://docs.gorunner.io/apps/notion#fields-f-comment): Add · Get Many
- [Database](https://docs.gorunner.io/apps/notion#fields-f-database): Get
- [Data Source](https://docs.gorunner.io/apps/notion#fields-f-datasource): Get · Search
- [User](https://docs.gorunner.io/apps/notion#fields-f-user): Get · Get Many

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from Notion can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When Notion says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, Notion is `pieceId: "notion"` with `actionId: "notion"`, set by `resource` and an `operation_…` field, such as `operation_block`. Its trigger is `notiontrigger` / `notion_poll`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### Notion › Database Page

### Create

- **Data Source · Required**: The database (data source) to add the page to, or to read pages from.
- **Title · Optional**: The page's title (its title property, whatever that property is called).
- **Properties · Optional**: Property values by property name, such as {"Status": "In progress", "Tags": ["Launch", "Q4"], "Due": "2026-11-07", "Estimate": 3, "Done": false}. Each value is read by the property's type in the database.
- **Content · Optional**: How the content is given. Options: None, Markdown, Notion blocks (JSON). Default: None.
- **Blocks (JSON) · Optional**: Notion block objects, such as [{"type":"paragraph","paragraph":{"rich_text":[{"text":{"content":"Hello"}}]}}]. More than 100 are sent 100 at a time. Shows when **Content** is **Notion blocks (JSON)**.
- **Markdown · Optional**: The content as Markdown: headings, lists, to-dos (- [ ]), quotes, code blocks, dividers and paragraphs. Shows when **Content** is **Markdown**.
- **Icon · Optional**: An emoji (🚀) or an image URL.

### Get

- **Page · Required**: The database page to read or change.

### Get Many

- **Data Source · Required**: The database (data source) to add the page to, or to read pages from.
- **Filter · Optional**: A Notion filter, such as {"property": "Status", "status": {"equals": "Done"}} or {"and": [ … ]}. Empty reads every page.
- **Sort · Optional**: Notion sorts, such as [{"property": "Due", "direction": "ascending"}] or [{"timestamp": "created_time", "direction": "descending"}].
- **Return All · Optional**: Read every page, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many pages to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **Page · Required**: The database page to read or change.
- **Properties · Optional**: Property values by property name, such as {"Status": "In progress", "Tags": ["Launch", "Q4"], "Due": "2026-11-07", "Estimate": 3, "Done": false}. Each value is read by the property's type in the database.
- **Icon · Optional**: An emoji (🚀) or an image URL.
- **Trash · Optional**: Leave the page where it is, move it to the trash, or restore it. Options: Leave as it is, Move to trash, Restore from trash. Default: Leave as it is.

### Notion › Page

### Create

- **Parent Page · Required**: The page the new page goes under.
- **Title · Required**: The new page's title.
- **Content · Optional**: How the content is given. Options: None, Markdown, Notion blocks (JSON). Default: None.
- **Blocks (JSON) · Optional**: Notion block objects, such as [{"type":"paragraph","paragraph":{"rich_text":[{"text":{"content":"Hello"}}]}}]. More than 100 are sent 100 at a time. Shows when **Content** is **Notion blocks (JSON)**.
- **Markdown · Optional**: The content as Markdown: headings, lists, to-dos (- [ ]), quotes, code blocks, dividers and paragraphs. Shows when **Content** is **Markdown**.
- **Icon · Optional**: An emoji (🚀) or an image URL.

### Get Markdown

- **Page · Required**: The page to read, change, move to the trash or restore.
- **Include Meeting Transcripts · Optional**: Include the transcript of meeting notes blocks. Off by default.

### Update Markdown

- **Page · Required**: The page to read, change, move to the trash or restore.
- **Update · Required**: Find and replace text, replace the whole content, or add content at the start or end. Options: Find and replace, Replace all content, Add content. Default: Find and replace.
- **Replacements · Required**: What to replace, such as [{"old_str": "Status: draft", "new_str": "Status: final"}]. Each old text must appear exactly once, unless "replace_all_matches": true. Shows when **Update** is **Find and replace**.
- **Markdown · Required**: The Markdown to put on the page (Replace all) or to add to it (Add content). Shows when **Update** is **Replace all content** or **Add content**.
- **Add At · Optional**: Where the Markdown goes. Options: The end, The start. Default: The end. Shows when **Update** is **Add content**.
- **Allow Deleting Child Pages · Optional**: Let the update remove child pages or databases the old content held. Off, Notion refuses an update that would. Off by default. Shows when **Update** is **Replace all content** or **Find and replace**.

### Search

- **Search Text · Optional**: Text in the page title. Empty lists every page the connection can see.
- **Exact Title · Optional**: Keep only pages whose title is the search text exactly (any case). Off keeps titles that contain it. Off by default.
- **Order · Optional**: Best match first, or by when it was last edited. Options: Best match, Last edited, newest first, Last edited, oldest first. Default: Best match.
- **Return All · Optional**: Read every page, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many pages to return (1–2000). Default: 50. Shows when **Return All** is off.

### Archive and Restore

- **Page · Required**: The page to read, change, move to the trash or restore.

### Notion › Block

### Append After

- **Block · Required**: The page (or block) to add to, read or delete. A page is its own top block.
- **Content · Optional**: How the content is given. Options: Markdown, Notion blocks (JSON). Default: Markdown.
- **Blocks (JSON) · Optional**: Notion block objects, such as [{"type":"paragraph","paragraph":{"rich_text":[{"text":{"content":"Hello"}}]}}]. More than 100 are sent 100 at a time. Shows when **Content** is **Notion blocks (JSON)**.
- **Markdown · Optional**: The content as Markdown: headings, lists, to-dos (- [ ]), quotes, code blocks, dividers and paragraphs. Shows when **Content** is **Markdown**.
- **Insert · Optional**: Where the new blocks go among the block's children. Options: At the end, At the start, After a block. Default: At the end.
- **After Block · Required**: The id (or link) of the child block to insert after. Shows when **Insert** is **After a block**.

### Get Many

- **Block · Required**: The page (or block) to add to, read or delete. A page is its own top block.
- **Return All · Optional**: Read every block, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many blocks to return (1–2000). Default: 50. Shows when **Return All** is off.

### Get Markdown

- **Block · Required**: The page (or block) to add to, read or delete. A page is its own top block.
- **Include Meeting Transcripts · Optional**: Include the transcript of meeting notes blocks. Off by default.

### Delete

- **Block · Required**: The page (or block) to add to, read or delete. A page is its own top block.

### Notion › Comment

### Add

- **Comment On · Optional**: A new comment on a page or a block, or a reply in an existing discussion. Options: A page, A block, A discussion (reply). Default: A page.
- **Page, Block or Discussion · Required**: The id or link of the page or block, or, for a reply, the discussion_id of a comment in the thread.
- **Comment · Required**: The comment's text.

### Get Many

- **Page, Block or Discussion · Required**: The id or link of the page or block, or, for a reply, the discussion_id of a comment in the thread.
- **Return All · Optional**: Read every comment, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many comments to return (1–2000). Default: 50. Shows when **Return All** is off.

### Notion › Database

### Get

- **Database · Required**: The database to read.

### Notion › Data Source

### Get

- **Data Source · Required**: The data source to read (its properties and their types).

### Search

- **Search Text · Optional**: Text in the data source's title. Empty lists every data source the connection can see.
- **Order · Optional**: Best match first, or by when it was last edited. Options: Best match, Last edited, newest first, Last edited, oldest first. Default: Best match.
- **Return All · Optional**: Read every data source, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many data sources to return (1–2000). Default: 50. Shows when **Return All** is off.

### Notion › User

### Get

- **User · Required**: The user's id.

### Get Many

- **Return All · Optional**: Read every user, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many users to return (1–2000). Default: 50. Shows when **Return All** is off.

Source: https://docs.gorunner.io/apps/notion