Skip to main content
GET
/
v1
/
pages
/
{page_id}
/
markdown
TypeScript SDK
import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const response = await notion.pages.retrieveMarkdown({
  page_id: "b55c9c91-384d-452b-81db-d1ef79372b75"
})

console.log(response.markdown)
{
  "object": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "markdown": "<string>",
  "truncated": true,
  "unknown_block_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}

​
Use cases

Use this endpoint to retrieve the full content of a Notion page as enhanced markdown, instead of working with the block-based API. This is especially useful for agentic systems and developer tools that work natively with markdown. The endpoint also accepts non-navigable block IDs returned in unknown_block_ids from a previous truncated response. Pass these IDs to fetch additional subtrees of a large page.

​
General behavior

Returns a page_markdown object containing the page content as an enhanced markdown string.
RequirementsYour integration must have read content capabilities on the target page in order to call this endpoint. To update your integration’s capabilities, navigate to the My integrations dashboard, select your integration, go to the Capabilities tab, and update your settings as needed.Attempting to call this endpoint without read content capabilities returns an HTTP response with a 403 status code.

​
Truncation

Pages are rendered up to a limit of approximately 20,000 records. When a page exceeds this limit:
  1. The truncated field is set to true.
  2. Blocks that could not be loaded appear as <unknown> tags in the markdown.
  3. The unknown_block_ids array contains the IDs of these unloaded blocks.
You can fetch the content of unloaded blocks by passing their IDs back to this same endpoint as the page_id path parameter.

​
Errors

Returns a 404 HTTP response if the page doesn’t exist, or if the integration doesn’t have access to the page. Returns a 400 or 429 HTTP response if the request exceeds the request limits. Each Public API endpoint can return several possible error codes. See the Error codes section of the Status codes documentation for more information.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Notion-Version
enum<string>
required

The API version to use for this request. The latest version is 2025-09-03.

Available options:
2025-09-03

Path Parameters

​
page_id
string
required

The ID of the page (or block) to retrieve as markdown. Non-navigable block IDs from truncated responses can be passed here to fetch their subtrees.

Query Parameters

​
include_transcript
boolean

Whether to include meeting note transcripts. Defaults to false. When true, full transcripts are included; when false, a placeholder with the meeting note URL is shown instead.

Response

​
object
string
required

The type of object, always 'page_markdown'.

Allowed value: "page_markdown"
​
id
string<uuid>
required

The ID of the page or block.

​
markdown
string
required

The page content rendered as enhanced Markdown.

​
truncated
boolean
required

Whether the content was truncated due to exceeding the record count limit.

​
unknown_block_ids
string<uuid>[]
required

Block IDs that could not be loaded (appeared as tags in the markdown). Pass these IDs back to this endpoint to fetch their content separately.

Maximum array length: 100