Python Notion API - Block references not appearing in API response

Other Questions Notion
1

UPDATE: Block references are not supported in API version 2022-06-28

I’m working on a Python integration to process existing Notion pages. Everything works fine except when I try to retrieve content that includes block references (when you copy a block link and paste it as a mention).

The integration has access to all the pages I need, but block mentions just show up as empty content in the API response. Page mentions and user mentions work perfectly though.

I’m making requests to the blocks endpoint like this:

api_headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json",
    "Notion-Version": "2022-06-28",
}

response = requests.get(f"https://api.notion.com/v1/blocks/{target_block_id}", headers=api_headers)

When I fetch a normal block, I get the expected structure:

{
    "archived": False,
    "bulleted_list_item": {
        "color": "default",
        "rich_text": [
            {
                "annotations": {
                    "bold": False,
                    "code": False,
                    "color": "default",
                    "italic": False,
                    "strikethrough": False,
                    "underline": False,
                },
                "href": None,
                "plain_text": "Here is some example content that I want to reference",
                "text": {
                    "content": "Here is some example content that I want to reference",
                    "link": None,
                },
                "type": "text",
            }
        ],
    },
    "has_children": False,
    "object": "block",
    "type": "bulleted_list_item",
}

But when I try to get a block that contains a block mention, the mention part is missing:

{
    "archived": False,
    "bulleted_list_item": {
        "color": "default",
        "rich_text": [
            {
                "annotations": {
                    "bold": False,
                    "code": False,
                    "color": "default",
                    "italic": False,
                    "strikethrough": False,
                    "underline": False,
                },
                "href": None,
                "plain_text": " ",
                "text": {"content": " ", "link": None},
                "type": "text",
            }
        ],
    },
    "has_children": False,
    "object": "block",
    "type": "bulleted_list_item",
}

Is there a way to access block mentions through the API or is this feature not available yet?

2

I encountered this exact issue while building a content migration tool last year. Since block references aren’t supported in the current API version, I ended up implementing a workaround by maintaining a local mapping of block IDs to their content. When processing pages, I first do a full scan to catalog all blocks and their content, then when I encounter those empty spaces where block references should be, I can substitute the actual content from my mapping. It’s not elegant but works reliably for read-only operations. For dynamic content that changes frequently, you might need to refresh your mapping periodically. The API team has acknowledged this limitation so hopefully we’ll see proper support in future versions.

3

totally feel you on this! ran into the same roadblock with block refs. searching for related content via search api might help but yeah, not as neat as using block refs directly. just gotta work with it till they update the api.

4

Block references are indeed a pain point with the current API implementation. I faced this limitation when working on a documentation sync project where block references were heavily used. What I discovered is that while the referenced content doesn’t appear in the API response, you can sometimes identify where these references should be by looking for those suspicious empty text blocks with just spaces. My approach was to parse the page structure first to understand the context, then manually reconstruct the relationships by cross-referencing block IDs from the original Notion page URLs. It requires some additional preprocessing but helps maintain content integrity when the full context matters for your integration.