Skip to main content
Moves a page to a new parent location. The page can be moved to a different page (making it a child page) or to a different data source (database).

​
Method Signature

notion.pages.move(args: MovePageParameters): Promise<PageObjectResponse | PartialPageObjectResponse>

​
Parameters

​
page_id
string
required
The ID of the page to move (with or without dashes).
​
parent
object
required
The new parent location for the page.
​
auth
string
Bearer token for authentication. Overrides the client-level authentication.

​
Response

​
object
string
Always "page"
​
id
string
The ID of the moved page
​
created_time
string
ISO 8601 timestamp when the page was created
​
last_edited_time
string
ISO 8601 timestamp when the page was last edited (updated after the move)
​
archived
boolean
Whether the page is archived
​
in_trash
boolean
Whether the page is in trash
​
is_locked
boolean
Whether the page is locked from editing
​
url
string
The URL of the Notion page (may change after move)
​
public_url
string | null
The public URL if published to the web
​
parent
object
Information about the page’s new parent location
​
properties
object
Property values of the page
​
icon
object | null
Page icon
​
cover
object | null
Page cover image
​
created_by
object
User who created the page
​
last_edited_by
object
User who last edited the page

​
Examples

​
Move Page to Another Page

Move a page to become a child of another page: 
const page = await notion.pages.move({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  parent: {
    page_id: "b55c9c91-384d-452b-81db-d1ef79372b75",
  },
})

console.log("Page moved successfully")
console.log("New parent:", page.parent)

​
Move Page to a Data Source

Move a page into a database (data source): 
const page = await notion.pages.move({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  parent: {
    data_source_id: "f336d0bc-b841-465b-8045-024475c079dd",
  },
})

console.log("Page moved to data source")

​
Move with Type Guard

import { isFullPage } from "@notionhq/client"

const response = await notion.pages.move({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  parent: {
    page_id: "b55c9c91-384d-452b-81db-d1ef79372b75",
  },
})

if (isFullPage(response)) {
  console.log("New URL:", response.url)
  console.log("Parent type:", response.parent.type)
  
  if (response.parent.type === "page_id") {
    console.log("Parent page ID:", response.parent.page_id)
  } else if (response.parent.type === "data_source_id") {
    console.log("Parent data source:", response.parent.data_source_id)
  }
}

​
Organize Pages into Sections

// Move multiple pages under a section page
const sectionPageId = "b55c9c91-384d-452b-81db-d1ef79372b75"

const pageIdsToMove = [
  "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  "c66d0c02-495e-563c-92ec-e80f8496c186",
  "d77e1d13-506f-674d-03fd-f91f9507d297",
]

for (const pageId of pageIdsToMove) {
  await notion.pages.move({
    page_id: pageId,
    parent: {
      page_id: sectionPageId,
    },
  })
  console.log(`Moved page ${pageId} to section`)
}

​
Move Page from Database to Page

// Extract a database item and convert it to a standalone page
const page = await notion.pages.move({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  parent: {
    page_id: "b55c9c91-384d-452b-81db-d1ef79372b75",
  },
})

console.log("Converted database item to child page")

​
Error Handling

import { APIResponseError, APIErrorCode } from "@notionhq/client"

try {
  const page = await notion.pages.move({
    page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
    parent: {
      page_id: "invalid-parent-id",
    },
  })
} catch (error) {
  if (APIResponseError.isAPIResponseError(error)) {
    if (error.code === APIErrorCode.ObjectNotFound) {
      console.error("Page or parent not found")
    } else if (error.code === APIErrorCode.ValidationError) {
      console.error("Invalid parent or insufficient permissions")
    } else {
      console.error("API error:", error.message)
    }
  } else {
    console.error("Unexpected error:", error)
  }
}

​
Conditional Move Based on Property

import { isFullPage } from "@notionhq/client"

// Retrieve the page first
const page = await notion.pages.retrieve({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
})

if (isFullPage(page)) {
  const statusProp = page.properties.Status
  
  if (statusProp.type === "select" && statusProp.select?.name === "Done") {
    // Move completed items to archive page
    await notion.pages.move({
      page_id: page.id,
      parent: {
        page_id: "archive-page-id",
      },
    })
    console.log("Moved completed page to archive")
  }
}

​
Important Notes

When moving a page from one database to another, ensure the target database has compatible properties. The page will retain its property values, but incompatible properties may be lost.
Moving a page updates its last_edited_time and last_edited_by fields. The page URL may also change after the move.
You need appropriate permissions to move a page. The integration must have access to both the page being moved and the destination parent.

​
Use Cases

  • Organize content: Move pages into different sections or categories
  • Archive completed items: Move finished tasks to an archive page
  • Restructure hierarchy: Reorganize your workspace structure
  • Promote database items: Convert database entries to standalone pages
  • Migrate data: Move pages between databases

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us