Retrieve a Block

Retrieve a single block object by its ID

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>

Source: Client.ts:581-592

Parameters

block_id · string · required

The ID of the block to retrieve. Must be a valid Notion block ID.

auth · string

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.

object · string

Always "block"

id · string

The unique identifier of the block

type · string

The type of block (e.g., "paragraph", "heading_1", "code", etc.)

created_time · string

ISO 8601 timestamp when the block was created

created_by · PartialUserObjectResponse

User who created the block

last_edited_time · string

ISO 8601 timestamp when the block was last edited

last_edited_by · PartialUserObjectResponse

User who last edited the block

has_children · boolean

Whether the block has child blocks

archived · boolean

Whether the block is archived

in_trash · boolean

Whether the block is in the trash

parent · ParentForBlockBasedObjectResponse

The parent of the block (page, block, or workspace)

[type] · object

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)
    }
  }
}

Related

• Update a Block
• Delete a Block
• List Block Children
• Type Guards Guide