Filter data source entries

Learn how to specify which pages from a data source to return.

Pass a filter in the body of a data source query. This example returns rows where the Task completed checkbox is checked. Set NOTION_API_KEY and NOTION_DATA_SOURCE_ID before running it.

curl

curl -X POST "https://api.notion.com/v1/data_sources/$NOTION_DATA_SOURCE_ID/query" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  --data '{"filter":{"property":"Task completed","checkbox":{"equals":true}}}'

Use compound filter conditions to combine filters with and or or.

If no filter is provided, non-archived pages in the data source will be returned with pagination. To query archived pages, set is_archived to true in the Query a data source request body.

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 for details on corresponding object values.	"checkbox": { "equals": true }

Example checkbox filter object

{
  "filter": {
    "property": "Task completed",
    "checkbox": {
      "equals": true
    }
  }
}

The filter object mimics the data source filter option in the Notion UI.

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

{
  "filter": {
    "property": "Task completed",
    "checkbox": {
      "does_not_equal": true
    }
  }
}

Date

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.

A date filter condition can be used to limit date property value types and the 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 or relative date)	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" "yesterday"
before	string (ISO 8601 date or relative date)	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" "tomorrow"
equals	string (ISO 8601 date or relative date)	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" "today"
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 or relative date)	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" "today"
on_or_before	string (ISO 8601 date or relative date)	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" "today"
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.	{}

Relative date values

The after, before, equals, on_or_after, and on_or_before fields accept the following relative date strings in addition to ISO 8601 dates. These are resolved at query time:

Value	Description
"today"	The current date.
"tomorrow"	The day after the current date.
"yesterday"	The day before the current date.
"one_week_ago"	Seven days before the current date.
"one_week_from_now"	Seven days after the current date.
"one_month_ago"	One month before the current date.
"one_month_from_now"	One month after the current date.

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

{
  "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 filter condition to compare the formula result against. Returns data source entries where the formula result matches the provided condition.	Refer to the checkbox filter condition.
date	object	A 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 filter condition.
number	object	A 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 filter condition.
string	object	A 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 filter condition.

Example formula filter condition

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

Multi-select

Field	Type	Description	Example value
contains	string or string[]	The value(s) to compare the multi-select property value against. Returns data source entries where the multi-select value matches any of the provided values.	"Marketing" or ["Marketing", "Sales"]
does_not_contain	string or string[]	The value(s) to compare the multi-select property value against. Returns data source entries where the multi-select value does not match any of the provided values.	"Engineering" or ["Engineering", "QA"]
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

{
  "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

{
  "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) or "me"	The value to compare the people property value against. Returns data source entries where the people property value contains the provided user. Pass a user UUID or "me" to match the current user (see note below).	"6c574cee-ca68-41c8-86e0-1b9e992689fb"
does_not_contain	string (UUIDv4) or "me"	The value to compare the people property value against. Returns data source entries where the people property value does not contain the provided user. Pass a user UUID or "me" to match the current user (see note below).	"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

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

The "me" value resolves to the user associated with the token. For public connections, this is the user who completed the OAuth flow. For personal access tokens, this is the user who created the token. For internal connections, there is no associated user — contains: "me" returns no results and does_not_contain: "me" matches all entries.

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

{
  "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

{
  "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 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 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 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

{
  "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 filter condition to compare the rollup value against. Returns data source entries where the rollup value matches the provided condition.	Refer to the date filter condition.

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 filter condition to compare the rollup value against. Returns data source entries where the rollup value matches the provided condition.	Refer to the number filter condition.

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 or string[]	The value(s) to compare the select property value against. Returns data source entries where the select property value matches any of the provided values.	"This week" or ["Low", "Medium"]
does_not_equal	string or string[]	The value(s) to compare the select property value against. Returns data source entries where the select property value does not match any of the provided values.	"Backlog" or ["Done", "Archive"]
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

{
  "filter": {
    "property": "Frontend framework",
    "select": {
      "equals": "React"
    }
  }
}

Status

Field	Type	Description	Example value
equals	string or string[]	The option name(s) to compare the status property value against. Returns data source entries where the status property value matches any of the provided values. If a value matches no option but matches a status group name, it matches the group. With the status group filters beta, values must be option names.	”This week” or [“Not started”, “In progress”]
does_not_equal	string or string[]	The option name(s) to compare the status property value against. Returns data source entries where the status property value does not match any of the provided values. The same status group rule as equals applies.	”Backlog” or [“Done”, “Archive”]
group_equals	string or string[]	Requires the status group filters beta. The status group names to match. An array must have at least one name. Returns entries whose status option belongs to any listed group.	"In progress" or ["To-do", "Complete"]
group_does_not_equal	string or string[]	Requires the status group filters beta. The status group names to exclude. An array must have at least one name. Returns entries whose status option belongs to none of the listed groups.	"In progress" or ["To-do", "Complete"]
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

{
  "filter": {
    "property": "Project status",
    "status": {
      "equals": "Not started"
    }
  }
}

Inside a rollup filter, equals and does_not_equal match only option names. Rollup filters aren’t checked against the target property’s options or groups, so an unknown name matches nothing instead of returning an error.

Status group filters beta

Each status option belongs to a status group, such as “To-do”, “In progress”, or “Complete”. An option and a group can have the same name. Notion’s default status property has an “In progress” option in the “In progress” group, for example. There, "equals": "In progress" matches only the option. Entries with other options in that group, such as “In review”, don’t match, and there’s no way to name the whole group.

To fix this, send the Notion-Beta: status-group-filters-2026-10-06 header. We recommend it for new integrations that filter by status. With the header:

• group_equals and group_does_not_equal match status groups. They work in compound filters, quick filters, and rollup filters.
• equals and does_not_equal match only option names. A group name there returns a validation_error with the correct group operator.
• Some older databases store translated group names. Direct status filters accept the stored and English names. Inside a rollup filter, send the stored name.
• Views return saved group filters with group operators. Mixed filters return nested or or and conditions when possible.

Without the header, status filters and view responses work as before. Group operators return a validation_error.

Example status group filter condition

{
  "filter": {
    "property": "Project status",
    "status": {
      "group_equals": "In progress"
    }
  }
}

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

Example timestamp filter condition for created_time

{
  "filter": {
    "timestamp": "created_time",
    "created_time": {
      "on_or_before": "2022-10-13"
    }
  }
}

The timestamp filter condition does not require a property name. The API throws an error if you provide one.

Verification

Field	Type	Description	Example value
status	string	Returns entries whose verification status matches the value.	"verified"
does_not_equal	string	Returns entries whose verification status does not match the value.	"expired"

Both fields accept verified, expired, or none.

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

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

An example filter chain in the Notion UI

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

Filter object

{
  "and": [
    { "property": "Done", "checkbox": { "equals": true } },
    {
      "or": [
        { "property": "Tags", "multi_select": { "contains": "A" } },
        { "property": "Tags", "multi_select": { "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 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 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

{
  "filter": {
    "and": [
      {
        "property": "Complete",
        "checkbox": {
          "equals": true
        }
      },
      {
        "property": "Working days",
        "number": {
          "greater_than": 10
        }
      }
    ]
  }
}

Example nested filter condition

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