> 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.

# Filter data source entries

When you [query a data source](/reference/query-a-data-source), you can send a `filter` object in the body of the request that limits the returned entries based on the specified criteria. 

For example, the below query limits the response to entries where the `"Task completed"`  `checkbox` property value is `true`: 

**`cURL`**

```curl cURL
curl -X POST 'https://api.notion.com/v1/data_sources/897e5a76ae524b489fdfe71f5945d1af/query' \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H 'Notion-Version: 2022-06-28' \
  -H "Content-Type: application/json" \
--data '{
  "filter": {
    "property": "Task completed",
    "checkbox": {
        "equals": true
   }
  }
}'
```

Here is the same query using the [Notion SDK for JavaScript](https://github.com/makenotion/notion-sdk-js):

**`JavaScript`**

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

const notion = new Client({ auth: process.env.NOTION_API_KEY });
// replace with your own data source ID
const dataSourceId = 'd9824bdc-8445-4327-be8b-5b47500af6ce';

const filteredRows = async () => {
	const response = await notion.databases.query({
	  data_source_id: dataSourceId,
	  filter: {
	    property: "Task completed",
	    checkbox: {
	      equals: true
	    }
	  },
	});
  return response;
}

```

Filters can be chained with the `and` and `or` keys so that multiple filters are applied at the same time. (See [Query a data source](/reference/query-a-data-source) for additional examples.)

**`JSON`**

```json JSON
{
  "and": [
    {
      "property": "Done",
      "checkbox": {
        "equals": true
      }
    }, 
    {
      "or": [
        {
          "property": "Tags",
          "contains": "A"
        },
        {
          "property": "Tags",
          "contains": "B"
        }
      ]
    }
  ]
}
```

If no filter is provided, all the pages in the data source will be returned with pagination.

## The filter object

Each `filter` object contains the following fields: 

| Field | Type | Description | Example value |
| :--- | :--- | :--- | :--- |
| `property` | `string` | The name of the property as it appears in the data source, or the property ID. | `"Task completed"` |
| `checkbox`  `date`  `files`  `formula`  `multi_select`  `number`  `people`  `phone_number`  `relation`  `rich_text`  `select`  `status`  `timestamp`  `verification`  `ID` | `object` | The type-specific filter condition for the query. Only types listed in the Field column of this table are supported.   Refer to [type-specific filter conditions](#type-specific-filter-conditions) for details on corresponding object values. | `"checkbox": {  "equals": true }` |


**`Example checkbox filter object`**

```json Example checkbox filter object
{
  "filter": {
    "property": "Task completed",
    "checkbox": {
      "equals": true
    }
  }
}
```

<Tip>
The filter object mimics the data source [filter option in the Notion UI](https://www.notion.so/help/views-filters-and-sorts).
</Tip>

## Type-specific filter conditions

### Checkbox

| Field | Type | Description | Example value |
| :--- | :--- | :--- | :--- |
| `equals` | `boolean` | Whether a `checkbox` property value matches the provided value exactly.   Returns or excludes all data source entries with an exact value match. | `false` |
| `does_not_equal` | `boolean` | Whether a `checkbox` property value differs from the provided value.   Returns or excludes all data source entries with a difference in values. | `true` |


**`Example checkbox filter condition`**

```json Example checkbox filter condition
{
  "filter": {
    "property": "Task completed",
    "checkbox": {
      "does_not_equal": true
    }
  }
}
```

### Date

<Note title="For the `after`, `before`, `equals, on_or_before`, and `on_or_after` fields, if a date string with a time is provided, then the comparison is done with millisecond precision.">
If no timezone is provided, then the timezone defaults to UTC.
</Note>

A date filter condition can be used to limit `date` property value types and the [timestamp](#timestamp) property types `created_time` and `last_edited_time`.

The condition contains the below fields:  

| Field | Type | Description | Example value |
| :--- | :--- | :--- | :--- |
| `after` | `string` ([ISO 8601 date](https://en.wikipedia.org/wiki/ISO_8601)) | The value to compare the date property value against.   Returns data source entries where the date property value is after the provided date. | `"2021-05-10"`   `"2021-05-10T12:00:00"`   `"2021-10-15T12:00:00-07:00"` |
| `before` | `string` ([ISO 8601 date](https://en.wikipedia.org/wiki/ISO_8601)) | The value to compare the date property value against.   Returns data source entries where the date property value is before the provided date. | `"2021-05-10"`   `"2021-05-10T12:00:00"`   `"2021-10-15T12:00:00-07:00"` |
| `equals` | `string` ([ISO 8601 date](https://en.wikipedia.org/wiki/ISO_8601)) | The value to compare the date property value against.   Returns data source entries where the date property value is the provided date. | `"2021-05-10"`   `"2021-05-10T12:00:00"`   `"2021-10-15T12:00:00-07:00"` |
| `is_empty` | `true` | The value to compare the date property value against.   Returns data source entries where the date property value contains no data. | `true` |
| `is_not_empty` | `true` | The value to compare the date property value against.   Returns data source entries where the date property value is not empty. | `true` |
| `next_month` | `object` (empty) | A filter that limits the results to data source entries where the date property value is within the next month. | `{}` |
| `next_week` | `object` (empty) | A filter that limits the results to data source entries where the date property value is within the next week. | `{}` |
| `next_year` | `object` (empty) | A filter that limits the results to data source entries where the date property value is within the next year. | `{}` |
| `on_or_after` | `string` ([ISO 8601 date](https://en.wikipedia.org/wiki/ISO_8601)) | The value to compare the date property value against.   Returns data source entries where the date property value is on or after the provided date. | `"2021-05-10"`   `"2021-05-10T12:00:00"`   `"2021-10-15T12:00:00-07:00"` |
| `on_or_before` | `string` ([ISO 8601 date](https://en.wikipedia.org/wiki/ISO_8601)) | The value to compare the date property value against.   Returns data source entries where the date property value is on or before the provided date. | `"2021-05-10"`   `"2021-05-10T12:00:00"`   `"2021-10-15T12:00:00-07:00"` |
| `past_month` | `object` (empty) | A filter that limits the results to data source entries where the `date` property value is within the past month. | `{}` |
| `past_week` | `object` (empty) | A filter that limits the results to data source entries where the `date` property value is within the past week. | `{}` |
| `past_year` | `object` (empty) | A filter that limits the results to data source entries where the `date` property value is within the past year. | `{}` |
| `this_week` | `object` (empty) | A filter that limits the results to data source entries where the `date` property value is this week. | `{}` |


**`Example date filter condition`**

```json Example date filter condition
{
  "filter": {
    "property": "Due date",
    "date": {
      "on_or_after": "2023-02-08"
    }
  }
}
```

### Files

| Field | Type | Description | Example value |
| :--- | :--- | :--- | :--- |
| `is_empty` | `true` | Whether the files property value does not contain any data.   Returns all data source entries with an empty `files` property value. | `true` |
| `is_not_empty` | `true` | Whether the `files` property value contains data.   Returns all entries with a populated `files` property value. | `true` |


**`Example files filter condition`**

```json Example files filter condition
{
  "filter": {
    "property": "Blueprint",
    "files": {
      "is_not_empty": true
    }
  }
}
```

### Formula

The primary field of the `formula` filter condition object matches the type of the formula’s result. For example, to filter a formula property that computes a `checkbox`, use a `formula` filter condition object with a `checkbox` field containing a checkbox filter condition as its value.

| Field | Type | Description | Example value |
| :--- | :--- | :--- | :--- |
| `checkbox` | `object` | A [checkbox](#checkbox) filter condition to compare the formula result against.   Returns data source entries where the formula result matches the provided condition. | Refer to the [checkbox](#checkbox) filter condition. |
| `date` | `object` | A [date](#date) filter condition to compare the formula result against.   Returns data source entries where the formula result matches the provided condition. | Refer to the [date](#date) filter condition. |
| `number` | `object` | A [number](#number) filter condition to compare the formula result against.   Returns data source entries where the formula result matches the provided condition. | Refer to the [number](#number) filter condition. |
| `string` | `object` | A [rich text](#rich-text) filter condition to compare the formula result against.   Returns data source entries where the formula result matches the provided condition. | Refer to the [rich text](#rich-text) filter condition. |


**`Example formula filter condition`**

```json Example formula filter condition
{
  "filter": {
    "property": "One month deadline",
    "formula": {
      "date":{
          "after": "2021-05-10"
      }
    }
  }
}
```

### Multi-select

| Field | Type | Description | Example value |
| :--- | :--- | :--- | :--- |
| `contains` | `string` | The value to compare the multi-select property value against.   Returns data source entries where the multi-select value matches the provided string. | `"Marketing"` |
| `does_not_contain` | `string` | The value to compare the multi-select property value against.   Returns data source entries where the multi-select value does not match the provided string. | `"Engineering"` |
| `is_empty` | `true` | Whether the multi-select property value is empty.   Returns data source entries where the multi-select value does not contain any data. | `true` |
| `is_not_empty` | `true` | Whether the multi-select property value is not empty.   Returns data source entries where the multi-select value does contains data. | `true` |


**`Example multi-select filter condition`**

```json Example multi-select filter condition
{
  "filter": {
    "property": "Programming language",
    "multi_select": {
      "contains": "TypeScript"
    }
  }
}
```

### Number

| Field | Type | Description | Example value |
| :--- | :--- | :--- | :--- |
| `does_not_equal` | `number` | The `number` to compare the number property value against.   Returns data source entries where the number property value differs from the provided `number`. | `42` |
| `equals` | `number` | The `number` to compare the number property value against.   Returns data source entries where the number property value is the same as the provided number. | `42` |
| `greater_than` | `number` | The `number` to compare the number property value against.   Returns data source entries where the number property value exceeds the provided `number`. | `42` |
| `greater_than_or_equal_to` | `number` | The `number` to compare the number property value against.   Returns data source entries where the number property value is equal to or exceeds the provided `number`. | `42` |
| `is_empty` | `true` | Whether the `number` property value is empty.   Returns data source entries where the number property value does not contain any data. | `true` |
| `is_not_empty` | `true` | Whether the number property value is not empty.   Returns data source entries where the number property value contains data. | `true` |
| `less_than` | `number` | The `number` to compare the number property value against.   Returns data source entries where the number property value is less than the provided `number`. | `42` |
| `less_than_or_equal_to` | `number` | The `number` to compare the number property value against.   Returns data source entries where the number property value is equal to or is less than the provided `number`. | `42` |


**`Example number filter condition`**

```json Example number filter condition
{
  "filter": {
    "property": "Estimated working days",
    "number": {
      "less_than_or_equal_to": 5
    }
  }
}
```

### People

You can apply a people filter condition to `people`, `created_by`, and `last_edited_by` data source property types. 

The people filter condition contains the following fields:

| Field | Type | Description | Example value |
| :--- | :--- | :--- | :--- |
| `contains` | `string` (UUIDv4) | The value to compare the people property value against.   Returns data source entries where the people property value contains the provided `string`. | `"6c574cee-ca68-41c8-86e0-1b9e992689fb"` |
| `does_not_contain` | `string` (UUIDv4) | The value to compare the people property value against.   Returns data source entries where the people property value does not contain the provided `string`. | `"6c574cee-ca68-41c8-86e0-1b9e992689fb"` |
| `is_empty` | `true` | Whether the people property value does not contain any data.   Returns data source entries where the people property value does not contain any data. | `true` |
| `is_not_empty` | `true` | Whether the people property value contains data.   Returns data source entries where the people property value is not empty. | `true` |


**`Example people filter condition`**

```json Example people filter condition
{
  "filter": {
    "property": "Last edited by",
    "people": {
      "contains": "c2f20311-9e54-4d11-8c79-7398424ae41e"
    }
  }
}
```

### Relation

| Field | Type | Description | Example value |
| :--- | :--- | :--- | :--- |
| `contains` | `string` (UUIDv4) | The value to compare the relation property value against.   Returns data source entries where the relation property value contains the provided `string`. | `"6c574cee-ca68-41c8-86e0-1b9e992689fb"` |
| `does_not_contain` | `string` (UUIDv4) | The value to compare the relation property value against.   Returns entries where the relation property value does not contain the provided `string`. | `"6c574cee-ca68-41c8-86e0-1b9e992689fb"` |
| `is_empty` | `true` | Whether the relation property value does not contain data.   Returns data source entries where the relation property value does not contain any data. | `true` |
| `is_not_empty` | `true` | Whether the relation property value contains data.   Returns data source entries where the property value is not empty. | `true` |


**`Example relation filter condition`**

```json Example relation filter condition
{
  "filter": {
    "property": "✔️ Task List",
    "relation": {
      "contains": "0c1f7cb280904f18924ed92965055e32"
    }
  }
}
```

### Rich text

| Field | Type | Description | Example value |
| :--- | :--- | :--- | :--- |
| `contains` | `string` | The `string` to compare the text property value against.   Returns data source entries with a text property value that includes the provided `string`. | `"Moved to Q2"` |
| `does_not_contain` | `string` | The `string` to compare the text property value against.   Returns data source entries with a text property value that does not include the provided `string`. | `"Moved to Q2"` |
| `does_not_equal` | `string` | The `string` to compare the text property value against.   Returns data source entries with a text property value that does not match the provided `string`. | `"Moved to Q2"` |
| `ends_with` | `string` | The `string` to compare the text property value against.   Returns data source entries with a text property value that ends with the provided `string`. | `"Q2"` |
| `equals` | `string` | The `string` to compare the text property value against.   Returns data source entries with a text property value that matches the provided `string`. | `"Moved to Q2"` |
| `is_empty` | `true` | Whether the text property value does not contain any data.   Returns data source entries with a text property value that is empty. | `true` |
| `is_not_empty` | `true` | Whether the text property value contains any data.   Returns data source entries with a text property value that contains data. | `true` |
| `starts_with` | `string` | The `string` to compare the text property value against.   Returns data source entries with a text property value that starts with the provided `string`. | "Moved" |


**`Example rich text filter condition`**

```json Example rich text filter condition
{
  "filter": {
    "property": "Description",
    "rich_text": {
      "contains": "cross-team"
    }
  }
}
```

### Rollup

A rollup data source property can evaluate to an array, date, or number value. The filter condition for the rollup property contains a `rollup` key and a corresponding object value that depends on the computed value type. 

#### Filter conditions for `array` rollup values

| Field | Type | Description | Example value |
| :--- | :--- | :--- | :--- |
| `any` | `object` | The value to compare each rollup property value against. Can be a [filter condition](#type-specific-filter-conditions) for any other type.   Returns data source entries where the rollup property value matches the provided criteria. | `"rich_text": { "contains": "Take Fig on a walk" }` |
| `every` | `object` | The value to compare each rollup property value against. Can be a [filter condition](#type-specific-filter-conditions) for any other type.   Returns data source entries where every rollup property value matches the provided criteria. | `"rich_text": { "contains": "Take Fig on a walk" }` |
| `none` | `object` | The value to compare each rollup property value against. Can be a [filter condition](#type-specific-filter-conditions) for any other type.   Returns data source entries where no rollup property value matches the provided criteria. | `"rich_text": { "contains": "Take Fig on a walk" }` |


**`Example array rollup filter condition`**

```json Example array rollup filter condition
{
  "filter": {
    "property": "Related tasks",
    "rollup": {
      "any": {
        "rich_text": {
          "contains": "Migrate data source"
        }
      }
    }
  }
}
```

#### Filter conditions for `date` rollup values

A rollup value is stored as a `date` only if the "Earliest date", "Latest date", or "Date range" computation is selected for the property in the Notion UI. 

| Field | Type | Description | Example value |
| :--- | :--- | :--- | :--- |
| `date` | `object` | A [date](#date) filter condition to compare the rollup value against.   Returns data source entries where the rollup value matches the provided condition. | Refer to the [date](#date) filter condition. |


**`Example date rollup filter condition`**

```json Example date rollup filter condition
{
  "filter": {
    "property": "Parent project due date",
    "rollup": {
      "date": {
        "on_or_before": "2023-02-08"
      }
    }
  }
}
```

#### Filter conditions for `number` rollup values

| Field | Type | Description | Example value |
| :--- | :--- | :--- | :--- |
| `number` | `object` | A [number](#number) filter condition to compare the rollup value against.   Returns data source entries where the rollup value matches the provided condition. | Refer to the [number](#number) filter condition. |


**`Example number rollup filter condition`**

```json Example number rollup filter condition
{
  "filter": {
    "property": "Total estimated working days",
    "rollup": {
      "number": {
        "does_not_equal": 42
      }
    }
  }
}
```

### Select

| Field | Type | Description | Example value |
| :--- | :--- | :--- | :--- |
| `equals` | `string` | The `string` to compare the select property value against.   Returns data source entries where the select property value matches the provided string. | `"This week"` |
| `does_not_equal` | `string` | The `string` to compare the select property value against.   Returns data source entries where the select property value does not match the provided `string`. | `"Backlog"` |
| `is_empty` | `true` | Whether the select property value does not contain data.   Returns data source entries where the select property value is empty. | `true` |
| `is_not_empty` | `true` | Whether the select property value contains data.   Returns data source entries where the select property value is not empty. | `true` |


**`Example select filter condition`**

```json Example select filter condition
{
  "filter": {
    "property": "Frontend framework",
    "select": {
      "equals": "React"
    }
  }
}
```

### Status

| Field | Type | Description | Example value |
| :--- | :--- | :--- | :--- |
| equals | string | The string to compare the status property value against.   Returns data source entries where the status property value matches the provided string. | "This week" |
| does_not_equal | string | The string to compare the status property value against.   Returns data source entries where the status property value does not match the provided string. | "Backlog" |
| is_empty | true | Whether the status property value does not contain data.   Returns data source entries where the status property value is empty. | true |
| is_not_empty | true | Whether the status property value contains data.   Returns data source entries where the status property value is not empty. | true |


**`Example status filter condition`**

```json Example status filter condition
{
  "filter": {
    "property": "Project status",
    "status": {
      "equals": "Not started"
    }
  }
}
```

### Timestamp

Use a timestamp filter condition to filter results based on `created_time` or `last_edited_time` values. 

| Field | Type | Description | Example value |
| :--- | :--- | :--- | :--- |
| timestamp | created_time last_edited_time | A constant string representing the type of timestamp to use as a filter. | "created_time" |
| created_time  last_edited_time | object | A date filter condition used to filter the specified timestamp. | Refer to the [date](#date) filter condition. |


**`Example timestamp filter condition for created_time`**

```json Example timestamp filter condition for created_time
{
  "filter": {
    "timestamp": "created_time",
    "created_time": {
      "on_or_before": "2022-10-13"
    }
  }
}
```

<Warning>
The `timestamp` filter condition does not require a property name. The API throws an error if you provide one.
</Warning>

### Verification

| Field | Type | Description | Example value |
| :--- | :--- | :--- | :--- |
| status | string | The verification status being queried. Valid options are: `verified`, `expired`, `none`   Returns data source entries where the current verification status matches the queried status. | "verified" |


**`Example verification filter condition for getting verified pages`**

```json Example verification filter condition for getting verified pages
{
  "filter": {
    "property": "verification",
    "verification": {
      "status": "verified"
    }
  }
}
```

### ID

Use a timestamp filter condition to filter results based on the `unique_id` value.

| Field | Type | Description | Example value |
| :--- | :--- | :--- | :--- |
| `does_not_equal` | `number` | The value to compare the unique_id property value against.   Returns data source entries where the unique_id property value differs from the provided value. | `42` |
| `equals` | `number` | The value to compare the unique_id property value against.   Returns data source entries where the unique_id property value is the same as the provided value. | `42` |
| `greater_than` | `number` | The value to compare the unique_id property value against.   Returns data source entries where the unique_id property value exceeds the provided value. | `42` |
| `greater_than_or_equal_to` | `number` | The value to compare the unique_id property value against.   Returns data source entries where the unique_id property value is equal to or exceeds the provided value. | `42` |
| `less_than` | `number` | The value to compare the unique_id property value against.   Returns data source entries where the unique_id property value is less than the provided value. | `42` |
| `less_than_or_equal_to` | `number` | The value to compare the unique_id property value against.   Returns data source entries where the unique_id property value is equal to or is less than the provided value. | `42` |


**`Example ID filter condition`**

```json Example ID filter condition
{
  "filter": {
    "and": [
      {
        "property": "ID",
        "unique_id": {
          "greater_than": 1
        }
      },
      {
        "property": "ID",
        "unique_id": {
          "less_than": 3
        }
      }
    ]
  }
}
```

## Compound filter conditions

You can use a compound filter condition to limit the results of a data source query based on multiple conditions. This mimics filter chaining in the Notion UI. 

<Frame caption="An example filter chain in the Notion UI">
  <img src="https://files.readme.io/14ec7e8-Untitled.png" alt="Untitled.png"/>
</Frame>


The above filters in the Notion UI are equivalent to the following compound filter condition via the API:

**`JSON`**

```json JSON
{
  "and": [
    {
      "property": "Done",
      "checkbox": {
        "equals": true
      }
    }, 
    {
      "or": [
        {
          "property": "Tags",
          "contains": "A"
        },
        {
          "property": "Tags",
          "contains": "B"
        }
      ]
    }
  ]
}
```

A compound filter condition contains an `and` or `or` key with a value that is an array of filter objects or nested compound filter objects. Nesting is supported up to two levels deep. 

| Field | Type | Description | Example value |
| :--- | :--- | :--- | :--- |
| `and` | `array` | An array of [filter](#type-specific-filter-conditions) objects or compound filter conditions.   Returns data source entries that match **all** of the provided filter conditions. | Refer to the examples below. |
| or | array | An array of [filter](#type-specific-filter-conditions) objects or compound filter conditions.   Returns data source entries that match **any** of the provided filter conditions | Refer to the examples below. |


### Example compound filter conditions

**`Example compound filter condition for a checkbox and number property value`**

```json Example compound filter condition for a checkbox and number property value
{
  "filter": {
    "and": [
      {
        "property": "Complete",
        "checkbox": {
          "equals": true
        }
      },
      {
        "property": "Working days",
        "number": {
          "greater_than": 10
        }
      }
    ]
  }
}
```

**`Example nested filter condition`**

```json Example nested filter condition
{
  "filter": {
    "or": [
      {
        "property": "Description",
        "rich_text": {
          "contains": "2023"
        }
      },
      {
        "and": [
          {
            "property": "Department",
            "select": {
              "equals": "Engineering"
            }
          },
          {
            "property": "Priority goal",
            "checkbox": {
              "equals": true
            }
          }
        ]
      }
    ]
  }
}
```