Notion API - Public Beta (English)
  1. Search
Notion API - Public Beta (English)
  • Introduction
  • Integration capabilities
  • Request limits
  • Status codes
  • ENDPOINTS
    • Authentication
      • Authentication
      • Token
    • Blocks
      • Delete a block
      • Append block children
      • Retrieve a block
      • Update a block
      • Retrieve block children
    • Databases
      • Filter database entries
      • Sort database entries
      • Update database properties
      • Retrieve a database
      • Update a database
      • Query a database
    • Pages
      • Archive a page
      • Retrieve a page property item
      • Create a page
      • Retrieve a Page
      • Update Page properties
    • Users
      • List all users
      • Retrieve your token's bot user
      • Retrieve a user
    • Comments
      • Create comment
      • Retrieve comments
    • Search
      • Search optimizations and limitations
      • Search by title
        GET
  • OBJECTS
    • Block
    • Comment
    • Unfurl attribute object for Link Previews
    • Page
      • Page
      • Page properties
    • Database
      • Database
      • Database properties
    • User
      • User
      • Comment
    • Other
      • Emoji object
      • File object
      • Parent object
      • Rich text object
  • Versioning
    • Versioning
    • Changes by version
  • ENDPOINTS Copy
    • Authentication
      • Authentication
      • Token
    • Blocks
      • Retrieve a block
      • Update a block
      • Retrieve block children
      • Delete a block
      • Append block children
    • Databases
      • Filter database entries
      • Sort database entries
      • Update database properties
      • Retrieve a database
      • Update a database
      • Query a database
      • Create a database
    • Pages
      • Archive a page
      • Retrieve a Page
      • Update Page properties
      • Retrieve a page property item
      • Create a page
    • Users
      • Retrieve a user
      • List all users
      • Retrieve your token's bot user
    • Comments
      • Create comment
      • Retrieve comments
  1. Search

Search optimizations and limitations

Optimizations#

Search works best when the request is as specific as possible. We recommend filtering by object (such as page or database) and providing a text query to narrow down results.
To speed up results, try reducing the page_size. The default page_size is 100.
Our implementation of the search endpoint includes an optimization where any pages or databases that are directly shared with an integration are guaranteed to be returned. If your use case requires pages or databases to immediately be available in search without an indexing delay, we recommend that you share relevant pages/databases with your integration directly.

Limitations#

The search endpoint works best when it's being used to query for pages and databases by name. It is not optimized for the following use cases:
Exhaustively enumerating through all the documents that a bot has access to in a workspace. Search is not guaranteed to return everything, and the index may change as your integration iterates through pages and databases.
Searching or filtering within a particular database. This use case is much better served by finding the database ID and using the Query a database endpoint.
Immediate and complete results.
Search indexing is not immediate. If an integration performs a search quickly after a page is shared with the integration (such as immediately after a user performs OAuth), then the response may not contain the page.
When an integration needs to present a user interface that depends on search results, we recommend including a Refresh button to retry the search. This will allow users to determine if the expected result is present or not, and give them a way to try again.
Previous
Retrieve comments
Next
Search by title
Built with