Retrieves a Block object using the ID specified in the request path. Blocks are returned with their content and metadata.
Method Signature
client.blocks.retrieve(args: GetBlockParameters): Promise<GetBlockResponse>
Parameters
The ID of the block to retrieve. Must be a valid Notion block ID.
Optional authentication token to override the client-level auth. Use this to make requests on behalf of specific integrations.
Response
Returns a BlockObjectResponse or PartialBlockObjectResponse representing the requested block.
The unique identifier of the block
The type of block (e.g., "paragraph", "heading_1", "code", etc.)
ISO 8601 timestamp when the block was created
created_by
PartialUserObjectResponse
User who created the block
ISO 8601 timestamp when the block was last edited
last_edited_by
PartialUserObjectResponse
User who last edited the block
Whether the block has child blocks
Whether the block is archived
Whether the block is in the trash
parent
ParentForBlockBasedObjectResponse
The parent of the block (page, block, or workspace)
Type-specific content. For example, a paragraph block has a paragraph property containing its rich_text content.
Examples
Retrieve a Paragraph Block
import { Client } from "@notionhq/client"
const notion = new Client({ auth: process.env.NOTION_TOKEN })
const block = await notion.blocks.retrieve({
block_id: "your-block-id",
})
console.log(block.type) // "paragraph"
if (block.type === "paragraph") {
console.log(block.paragraph.rich_text)
}
Retrieve a Code Block
const codeBlock = await notion.blocks.retrieve({
block_id: "code-block-id",
})
if (codeBlock.type === "code") {
console.log("Language:", codeBlock.code.language)
console.log("Code:", codeBlock.code.rich_text)
console.log("Caption:", codeBlock.code.caption)
}
Retrieve with Custom Auth
// Override the client's auth token for this request
const block = await notion.blocks.retrieve({
block_id: "your-block-id",
auth: "secret_custom_token",
})
Check if Block Has Children
const block = await notion.blocks.retrieve({
block_id: "your-block-id",
})
if (block.has_children) {
console.log("This block has child blocks")
// You can fetch children using blocks.children.list()
}
Type Guards
Use the isFullBlock() helper to check if a block is fully populated:
import { isFullBlock } from "@notionhq/client"
const block = await notion.blocks.retrieve({
block_id: "your-block-id",
})
if (isFullBlock(block)) {
// TypeScript knows this is a full BlockObjectResponse
console.log(block.created_time)
console.log(block.last_edited_time)
}
Error Handling
import { APIResponseError } from "@notionhq/client"
try {
const block = await notion.blocks.retrieve({
block_id: "your-block-id",
})
console.log(block)
} catch (error) {
if (APIResponseError.isAPIResponseError(error)) {
switch (error.code) {
case "object_not_found":
console.error("Block not found")
break
case "unauthorized":
console.error("Not authorized to access this block")
break
default:
console.error("API error:", error.message)
}
}
}
