Notion API - Public Beta (English)
  1. Databases
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
        GET
      • Update a database
        PATCH
      • Query a database
        POST
    • 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
  • 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. Databases

Query a database

POST
/v1/databases/{id}/query
Databases
Query a database
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST '/v1/databases//query' \
--header 'Content-Type: application/json' \
--data-raw '{
    "filter": {
        "or": [
            {
                "property": "Status",
                "select": {
                    "equals": "Reading"
                }
            },
            {
                "property": "Publisher",
                "select": {
                    "equals": "NYT"
                }
            }
        ]
    },
    "sorts": [
        {
            "direction": "ascending",
            "property": "Score /5"
        }
    ]
}'
Response Response Example
{
    "has_more": false,
    "next_cursor": null,
    "object": "list",
    "results": [
        {
            "archived": false,
            "created_time": "2021-04-27T20:38:19.437Z",
            "id": "557ef501-bfdb-4586-918e-4434f31bca8c",
            "last_edited_time": "2021-04-27T20:38:19.437Z",
            "object": "page",
            "parent": {
                "database_id": "8e2c2b76-9e1d-47d2-87b9-ed3035d607ae",
                "type": "database_id"
            },
            "properties": {
                "Author": {
                    "id": "qNw_",
                    "multi_select": [
                        {
                            "color": "default",
                            "id": "ae3a2cbe-1fc9-4376-be35-331628b34623",
                            "name": "Karen Swallow Prior"
                        }
                    ],
                    "type": "multi_select"
                },
                "Link": {
                    "id": "VVMi",
                    "type": "url",
                    "url": "https://www.theatlantic.com/entertainment/archive/2016/03/how-jane-eyre-created-the-modern-self/460461/"
                },
                "Name": {
                    "id": "title",
                    "title": [
                        {
                            "annotations": {
                                "bold": false,
                                "code": false,
                                "color": "default",
                                "italic": true,
                                "strikethrough": false,
                                "underline": false
                            },
                            "href": null,
                            "plain_text": "Jane Eyre",
                            "text": {
                                "content": "Jane Eyre",
                                "link": null
                            },
                            "type": "text"
                        },
                        {
                            "annotations": {
                                "bold": false,
                                "code": false,
                                "color": "default",
                                "italic": false,
                                "strikethrough": false,
                                "underline": false
                            },
                            "href": null,
                            "plain_text": " and the Invention of Self",
                            "text": {
                                "content": " and the Invention of Self",
                                "link": null
                            },
                            "type": "text"
                        }
                    ],
                    "type": "title"
                },
                "Publisher": {
                    "id": ">$Pb",
                    "select": {
                        "color": "red",
                        "id": "01f82d08-aa1f-4884-a4e0-3bc32f909ec4",
                        "name": "The Atlantic"
                    },
                    "type": "select"
                },
                "Publishing/Release Date": {
                    "date": {
                        "end": null,
                        "start": "2016-10-03"
                    },
                    "id": "?ex+",
                    "type": "date"
                },
                "Read": {
                    "checkbox": false,
                    "id": "_MWJ",
                    "type": "checkbox"
                },
                "Score /5": {
                    "id": ")Y7\"",
                    "select": {
                        "color": "default",
                        "id": "66d3d050-086c-4a91-8c56-d55dc67e7789",
                        "name": "⭐️⭐️"
                    },
                    "type": "select"
                },
                "Status": {
                    "id": "`zz5",
                    "select": {
                        "color": "red",
                        "id": "5925ba22-0126-4b58-90c7-b8bbb2c3c895",
                        "name": "Reading"
                    },
                    "type": "select"
                },
                "Summary": {
                    "id": "?\\25",
                    "text": [],
                    "type": "text"
                },
                "Type": {
                    "id": "/7eo",
                    "select": {
                        "color": "default",
                        "id": "9cc30548-59d6-4cd3-94bc-d234081525c4",
                        "name": "Essay Resource"
                    },
                    "type": "select"
                }
            }
        },
        {
            "archived": false,
            "created_time": "2021-04-27T20:38:19.437Z",
            "id": "a1712d54-53e4-4893-a69d-4d581cd2c845",
            "last_edited_time": "2021-04-28T23:12:53.160Z",
            "object": "page",
            "parent": {
                "database_id": "8e2c2b76-9e1d-47d2-87b9-ed3035d607ae",
                "type": "database_id"
            },
            "properties": {
                "Author": {
                    "id": "qNw_",
                    "multi_select": [
                        {
                            "color": "default",
                            "id": "833e2c78-35ed-4601-badc-50c323341d76",
                            "name": "Kara Swisher"
                        }
                    ],
                    "type": "multi_select"
                },
                "Link": {
                    "id": "VVMi",
                    "type": "url",
                    "url": "https://www.nytimes.com/2018/10/21/opinion/who-will-teach-silicon-valley-to-be-ethical.html"
                },
                "Name": {
                    "id": "title",
                    "title": [
                        {
                            "annotations": {
                                "bold": false,
                                "code": false,
                                "color": "default",
                                "italic": false,
                                "strikethrough": false,
                                "underline": false
                            },
                            "href": null,
                            "plain_text": "Who Will Teach Silicon Valley to Be Ethical? ",
                            "text": {
                                "content": "Who Will Teach Silicon Valley to Be Ethical? ",
                                "link": null
                            },
                            "type": "text"
                        }
                    ],
                    "type": "title"
                },
                "Publisher": {
                    "id": ">$Pb",
                    "select": {
                        "color": "default",
                        "id": "c5ee409a-f307-4176-99ee-6e424fa89afa",
                        "name": "NYT"
                    },
                    "type": "select"
                },
                "Publishing/Release Date": {
                    "date": {
                        "end": null,
                        "start": "2018-10-21"
                    },
                    "id": "?ex+",
                    "type": "date"
                },
                "Read": {
                    "checkbox": true,
                    "id": "_MWJ",
                    "type": "checkbox"
                },
                "Score /5": {
                    "id": ")Y7\"",
                    "select": {
                        "color": "default",
                        "id": "b7307e35-c80a-4cb5-bb6b-6054523b394a",
                        "name": "⭐️⭐️⭐️⭐️"
                    },
                    "type": "select"
                },
                "Status": {
                    "id": "`zz5",
                    "select": {
                        "color": "red",
                        "id": "5925ba22-0126-4b58-90c7-b8bbb2c3c895",
                        "name": "Reading"
                    },
                    "type": "select"
                },
                "Summary": {
                    "id": "?\\25",
                    "text": [
                        {
                            "annotations": {
                                "bold": false,
                                "code": false,
                                "color": "default",
                                "italic": false,
                                "strikethrough": false,
                                "underline": false
                            },
                            "href": null,
                            "plain_text": "Some think chief ethics officers could help technology companies navigate political and social questions.",
                            "text": {
                                "content": "Some think chief ethics officers could help technology companies navigate political and social questions.",
                                "link": null
                            },
                            "type": "text"
                        }
                    ],
                    "type": "text"
                },
                "Type": {
                    "id": "/7eo",
                    "select": {
                        "color": "default",
                        "id": "f96d0d0a-5564-4a20-ab15-5f040d49759e",
                        "name": "Article"
                    },
                    "type": "select"
                }
            }
        }
    ]
}

Request

Path Params
id
string 
required
Body Params application/json
filter
object 
optional
or
array [object {2}] 
optional
sorts
array [object {2}] 
optional
direction
string 
optional
Example:
ascending
property
string 
optional
Example:
Score /5
Examples

Responses

🟢200200 Success - Query a Database (Single Filter)
application/json
Body
has_more
boolean 
optional
Example:
false
next_cursor
null 
optional
Example:
null
object
string 
optional
Example:
list
results
array [object {7}] 
optional
archived
boolean 
optional
Example:
false
created_time
string 
optional
Example:
2021-04-27T20:38:19.437Z
id
string 
optional
Example:
557ef501-bfdb-4586-918e-4434f31bca8c
last_edited_time
string 
optional
Example:
2021-04-27T20:38:19.437Z
object
string 
optional
Example:
page
parent
object 
optional
properties
object 
optional
Previous
Update a database
Next
Archive a page
Built with