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.

​
Unknown blocks

Some blocks may appear as <unknown url="..." alt="..."/> tags in the markdown output. This happens when:
  • Truncation: The page exceeds the record limit (approximately 20,000 blocks) and some blocks could not be loaded.
  • Permissions: The page contains child pages or other content that is not shared with the integration.
  • Unsupported block types: Certain block types (such as bookmarks, embeds, and link previews) are not yet supported in the markdown format.
When truncation or permissions cause unknown blocks, the truncated field is set to true and the unknown_block_ids array contains the affected block IDs. You can attempt to fetch unloaded blocks by passing their IDs back to this same endpoint as the page_id path parameter. Blocks that are unknown due to permissions will return a 404 error since the integration does not have access.
The unknown_block_ids array does not distinguish between truncated and inaccessible blocks. Handle object_not_found errors gracefully when re-fetching unknown block IDs.
For unsupported block types, use the block-based API to retrieve the full structured data.

​
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 2026-03-11.

Available options:
2026-03-11

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