> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://notion.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://notion.ferndocs.com/_mcp/server.

# Search by title

POST https://api.notion.com/v1/search
Content-Type: application/json

Searches all parent or child pages and databases that have been shared with an integration.

Returns all [pages](https://developers.notion.com/reference/page) or [databases](https://developers.notion.com/reference/database), excluding duplicated linked databases, that have titles that include the `query` param. If no `query` param is provided, then the response contains all pages or databases that have been shared with the integration. The results adhere to any limitations related to an [integration's capabilities](https://developers.notion.com/reference/capabilities).

To limit the request to search only pages or to search only databases, use the `filter` param.

### Errors

Each Public API endpoint can return several possible error codes. See the [Error codes section](https://developers.notion.com/reference/status-codes#error-codes) of the Status codes documentation for more information.

The Search endpoint supports pagination. To learn more about working with [paginated](https://developers.notion.com/reference/intro#pagination) responses, see the pagination section of the Notion API Introduction.

To search a specific database — not all databases shared with the integration — use the [Query a database](https://developers.notion.com/reference/post-database-query) endpoint instead.

Reference: https://notion.ferndocs.com/reference/post-search

## Request

### Headers

- `Notion-Version` (string, required) — The [API version](/reference/versioning) to use for this request. The latest version is `<<latestNotionVersion>>`.

### Body (application/json)

This endpoint expects an object.

- `query` (string, optional) — The text that the API compares page and database titles against.
- `sort` (V1SearchPostRequestBodyContentApplicationJsonSchemaSort, optional) — A set of criteria, `direction` and `timestamp` keys, that orders the results. The **only** supported timestamp value is `"last_edited_time"`. Supported `direction` values are `"ascending"` and `"descending"`. If `sort` is not provided, then the most recently edited results are returned first.
- `filter` (V1SearchPostRequestBodyContentApplicationJsonSchemaFilter, optional) — A set of criteria, `value` and `property` keys, that limits the results to either only pages or only databases. Possible `value` values are `"page"` or `"database"`. The only supported `property` value is `"object"`.
- `start_cursor` (string, optional) — A `cursor` value returned in a previous response that If supplied, limits the response to results starting after the `cursor`. If not supplied, then the first page of results is returned. Refer to [pagination](https://developers.notion.com/reference/intro#pagination) for more details.
- `page_size` (integer, optional, default: 100) — The number of items from the full list to include in the response. Maximum: `100`.

## Response

### 200

200

- `object` (string, optional)
- `results` (list of V1SearchPostResponsesContentApplicationJsonSchemaResultsItems, optional)
- `next_cursor` (any, optional)
- `has_more` (boolean, optional, default: true)
- `type` (string, optional)
- `page_or_database` (V1SearchPostResponsesContentApplicationJsonSchemaPageOrDatabase, optional)

## Errors

### 400 Bad Request Error

400

- `object` (string, optional)
- `status` (integer, optional, default: 0)
- `code` (string, optional)
- `message` (string, optional)

### 429 Too Many Requests Error

429

- `object` (string, optional)
- `status` (integer, optional, default: 0)
- `code` (string, optional)
- `message` (string, optional)

## Types

### V1SearchPostRequestBodyContentApplicationJsonSchemaSort

A set of criteria, `direction` and `timestamp` keys, that orders the results. The **only** supported timestamp value is `"last_edited_time"`. Supported `direction` values are `"ascending"` and `"descending"`. If `sort` is not provided, then the most recently edited results are returned first.

- `direction` (string, optional) — The direction to sort. Possible values include `ascending` and `descending`.
- `timestamp` (string, optional) — The name of the timestamp to sort against. Possible values include `last_edited_time`.

### V1SearchPostRequestBodyContentApplicationJsonSchemaFilter

A set of criteria, `value` and `property` keys, that limits the results to either only pages or only databases. Possible `value` values are `"page"` or `"database"`. The only supported `property` value is `"object"`.

- `value` (string, optional) — The value of the property to filter the results by. Possible values for object type include `page` or `database`. **Limitation**: Currently the only filter allowed is `object` which will filter by type of object (either `page` or `database`)
- `property` (string, optional) — The name of the property to filter by. Currently the only property you can filter by is the object type. Possible values include `object`. Limitation: Currently the only filter allowed is `object` which will filter by type of object (either `page` or `database`)

### V1SearchPostResponsesContentApplicationJsonSchemaResultsItems

- `object` (string, optional)
- `id` (string, optional)
- `created_time` (string, optional)
- `last_edited_time` (string, optional)
- `created_by` (V1SearchPostResponsesContentApplicationJsonSchemaResultsItemsCreatedBy, optional)
- `last_edited_by` (V1SearchPostResponsesContentApplicationJsonSchemaResultsItemsLastEditedBy, optional)
- `cover` (V1SearchPostResponsesContentApplicationJsonSchemaResultsItemsCover, optional)
- `icon` (V1SearchPostResponsesContentApplicationJsonSchemaResultsItemsIcon, optional)
- `parent` (V1SearchPostResponsesContentApplicationJsonSchemaResultsItemsParent, optional)
- `archived` (boolean, optional, default: true)
- `properties` (V1SearchPostResponsesContentApplicationJsonSchemaResultsItems, optional)
- `url` (string, optional)

### V1SearchPostResponsesContentApplicationJsonSchemaPageOrDatabase

### V1SearchPostResponsesContentApplicationJsonSchemaResultsItemsCreatedBy

- `object` (string, optional)
- `id` (string, optional)

### V1SearchPostResponsesContentApplicationJsonSchemaResultsItemsLastEditedBy

- `object` (string, optional)
- `id` (string, optional)

### V1SearchPostResponsesContentApplicationJsonSchemaResultsItemsCover

- `type` (string, optional)
- `external` (V1SearchPostResponsesContentApplicationJsonSchemaResultsItemsCoverExternal, optional)

### V1SearchPostResponsesContentApplicationJsonSchemaResultsItemsIcon

- `type` (string, optional)
- `emoji` (string, optional)

### V1SearchPostResponsesContentApplicationJsonSchemaResultsItemsParent

- `type` (string, optional)
- `database_id` (string, optional)

### V1SearchPostResponsesContentApplicationJsonSchemaResultsItemsCoverExternal

- `url` (string, optional)

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "object": "list",
  "results": [
    {
      "object": "page",
      "id": "954b67f9-3f87-41db-8874-23b92bbd31ee",
      "created_time": "2022-07-06T19:30:00.000Z",
      "last_edited_time": "2022-07-06T19:30:00.000Z",
      "created_by": {
        "object": "user",
        "id": "ee5f0f84-409a-440f-983a-a5315961c6e4"
      },
      "last_edited_by": {
        "object": "user",
        "id": "ee5f0f84-409a-440f-983a-a5315961c6e4"
      },
      "cover": {
        "type": "external",
        "external": {
          "url": "https://upload.wikimedia.org/wikipedia/commons/6/62/Tuscankale.jpg"
        }
      },
      "icon": {
        "type": "emoji",
        "emoji": "🥬"
      },
      "parent": {
        "type": "database_id",
        "database_id": "d9824bdc-8445-4327-be8b-5b47500af6ce"
      },
      "archived": false,
      "properties": {
        "Store availability": {
          "id": "%3AUPp",
          "type": "multi_select",
          "multi_select": []
        },
        "Food group": {
          "id": "A%40Hk",
          "type": "select",
          "select": {
            "id": "5e8e7e8f-432e-4d8a-8166-1821e10225fc",
            "name": "🥬 Vegetable",
            "color": "pink"
          }
        },
        "Price": {
          "id": "BJXS",
          "type": "number",
          "number": {}
        },
        "Responsible Person": {
          "id": "Iowm",
          "type": "people",
          "people": []
        },
        "Last ordered": {
          "id": "Jsfb",
          "type": "date",
          "date": {}
        },
        "Cost of next trip": {
          "id": "WOd%3B",
          "type": "formula",
          "formula": {
            "type": "number",
            "number": {}
          }
        },
        "Recipes": {
          "id": "YfIu",
          "type": "relation",
          "relation": []
        },
        "Description": {
          "id": "_Tc_",
          "type": "rich_text",
          "rich_text": [
            {
              "type": "text",
              "text": {
                "content": "A dark green leafy vegetable",
                "link": {}
              },
              "annotations": {
                "bold": false,
                "italic": false,
                "strikethrough": false,
                "underline": false,
                "code": false,
                "color": "default"
              },
              "plain_text": "A dark green leafy vegetable",
              "href": {}
            }
          ]
        },
        "In stock": {
          "id": "%60%5Bq%3F",
          "type": "checkbox",
          "checkbox": false
        },
        "Number of meals": {
          "id": "zag~",
          "type": "rollup",
          "rollup": {
            "type": "number",
            "number": 0,
            "function": "count"
          }
        },
        "Photo": {
          "id": "%7DF_L",
          "type": "url",
          "url": {}
        },
        "Name": {
          "id": "title",
          "type": "title",
          "title": [
            {
              "type": "text",
              "text": {
                "content": "Tuscan kale",
                "link": {}
              },
              "annotations": {
                "bold": false,
                "italic": false,
                "strikethrough": false,
                "underline": false,
                "code": false,
                "color": "default"
              },
              "plain_text": "Tuscan kale",
              "href": {}
            }
          ]
        }
      },
      "url": "https://www.notion.so/Tuscan-kale-954b67f93f8741db887423b92bbd31ee"
    },
    {
      "object": "page",
      "id": "59833787-2cf9-4fdf-8782-e53db20768a5",
      "created_time": "2022-03-01T19:05:00.000Z",
      "last_edited_time": "2022-07-06T20:25:00.000Z",
      "created_by": {
        "object": "user",
        "id": "ee5f0f84-409a-440f-983a-a5315961c6e4"
      },
      "last_edited_by": {
        "object": "user",
        "id": "0c3e9826-b8f7-4f73-927d-2caaf86f1103"
      },
      "cover": {
        "type": "external",
        "external": {
          "url": "https://upload.wikimedia.org/wikipedia/commons/6/62/Tuscankale.jpg"
        }
      },
      "icon": {
        "type": "emoji",
        "emoji": "🥬"
      },
      "parent": {
        "type": "database_id",
        "database_id": "d9824bdc-8445-4327-be8b-5b47500af6ce"
      },
      "archived": false,
      "properties": {
        "Store availability": {
          "id": "%3AUPp",
          "type": "multi_select",
          "multi_select": [
            "string",
            "string"
          ]
        },
        "Food group": {
          "id": "A%40Hk",
          "type": "select",
          "select": {
            "id": "5e8e7e8f-432e-4d8a-8166-1821e10225fc",
            "name": "🥬 Vegetable",
            "color": "pink"
          }
        },
        "Price": {
          "id": "BJXS",
          "type": "number",
          "number": 2.5
        },
        "Responsible Person": {
          "id": "Iowm",
          "type": "people",
          "people": [
            "string"
          ]
        },
        "Last ordered": {
          "id": "Jsfb",
          "type": "date",
          "date": {
            "start": "2022-02-22",
            "end": null,
            "time_zone": null
          }
        },
        "Cost of next trip": {
          "id": "WOd%3B",
          "type": "formula",
          "formula": {
            "type": "number",
            "number": 0
          }
        },
        "Recipes": {
          "id": "YfIu",
          "type": "relation",
          "relation": [
            "string",
            "string"
          ],
          "has_more": false
        },
        "Description": {
          "id": "_Tc_",
          "type": "rich_text",
          "rich_text": [
            {
              "type": "text",
              "text": {
                "content": "A dark ",
                "link": {}
              },
              "annotations": {
                "bold": false,
                "italic": false,
                "strikethrough": false,
                "underline": false,
                "code": false,
                "color": "default"
              },
              "plain_text": "A dark ",
              "href": {}
            },
            {
              "type": "text",
              "text": {
                "content": "green",
                "link": {}
              },
              "annotations": {
                "bold": false,
                "italic": false,
                "strikethrough": false,
                "underline": false,
                "code": false,
                "color": "green"
              },
              "plain_text": "green",
              "href": {}
            },
            {
              "type": "text",
              "text": {
                "content": " leafy vegetable",
                "link": {}
              },
              "annotations": {
                "bold": false,
                "italic": false,
                "strikethrough": false,
                "underline": false,
                "code": false,
                "color": "default"
              },
              "plain_text": " leafy vegetable",
              "href": {}
            }
          ]
        },
        "In stock": {
          "id": "%60%5Bq%3F",
          "type": "checkbox",
          "checkbox": true
        },
        "Number of meals": {
          "id": "zag~",
          "type": "rollup",
          "rollup": {
            "type": "number",
            "number": 2,
            "function": "count"
          }
        },
        "Photo": {
          "id": "%7DF_L",
          "type": "url",
          "url": "https://i.insider.com/612fb23c9ef1e50018f93198?width=1136&format=jpeg"
        },
        "Name": {
          "id": "title",
          "type": "title",
          "title": [
            {
              "type": "text",
              "text": {
                "content": "Tuscan kale",
                "link": {}
              },
              "annotations": {
                "bold": false,
                "italic": false,
                "strikethrough": false,
                "underline": false,
                "code": false,
                "color": "default"
              },
              "plain_text": "Tuscan kale",
              "href": {}
            }
          ]
        }
      },
      "url": "https://www.notion.so/Tuscan-kale-598337872cf94fdf8782e53db20768a5"
    }
  ],
  "next_cursor": {},
  "has_more": false,
  "type": "page_or_database",
  "page_or_database": {}
}
```

**SDK Code**

```javascript Notion SDK for JavaScript
const { Client } = require('@notionhq/client');

const notion = new Client({ auth: process.env.NOTION_API_KEY });

(async () => {
  const response = await notion.search({
    query: 'External tasks',
    filter: {
      value: 'database',
      property: 'object'
    },
    sort: {
      direction: 'ascending',
      timestamp: 'last_edited_time'
    },
  });
  console.log(response);
})();
```

```python
import requests

url = "https://api.notion.com/v1/search"

payload = {}
headers = {
    "Notion-Version": "Notion-Version",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.notion.com/v1/search"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Notion-Version", "Notion-Version")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.notion.com/v1/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Notion-Version"] = 'Notion-Version'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.notion.com/v1/search")
  .header("Notion-Version", "Notion-Version")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.notion.com/v1/search', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
    'Notion-Version' => 'Notion-Version',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.notion.com/v1/search");
var request = new RestRequest(Method.POST);
request.AddHeader("Notion-Version", "Notion-Version");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Notion-Version": "Notion-Version",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.notion.com/v1/search")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```