Skip to main content
POST
/
v1
/
views
/
{view_id}
/
queries
TypeScript SDK
import { Client } from "@notionhq/client"

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

const response = await notion.views.queries.create({
  view_id: "a3f1b2c4-5678-4def-abcd-1234567890ab"
})
{
  "object": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "view_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "expires_at": "2023-11-07T05:31:56Z",
  "total_count": 123,
  "results": [
    {
      "object": "<string>",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "next_cursor": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "has_more": true,
  "request_status": {
    "type": "complete",
    "incomplete_reason": "<string>"
  }
}
Executes the view’s filter and sort configuration against its data source, caches the full result set, and returns the first page of page references along with a query_id for paginating through results. Cached results expire after 15 minutes. Use the expires_at field to check when the cache will be invalidated.
Connection capabilitiesThis endpoint requires a connection to have read content capabilities. For more information on connection capabilities, see the capabilities guide.

​
Pagination limit

This endpoint caches up to 10,000 results per query. If the view’s filter and sort configuration matches more rows than this limit, the cache will be truncated and the response will include: 
{
  "request_status": {
    "type": "incomplete",
    "incomplete_reason": "query_result_limit_reached"
  }
}
When request_status.type is "incomplete", the total_count reflects only the truncated cache size (not the full matching row count), and subsequent paginated requests will stop once the cache is exhausted. To work around this limit:
  • Narrow the view’s filter and sort configuration via Update a view (for example, filter by last_edited_time to only include recently changed rows).
  • Set up connection webhooks to detect changes in real time instead of polling this endpoint.
Incremental sync via webhooksIf your connection runs this endpoint on a recurring schedule to detect changes, consider switching to connection webhooks for incremental sync. Webhooks notify your connection when rows change, removing the need to re-query the view and avoiding the pagination depth limit entirely.

​
Errors

Returns a 404 HTTP response if the view doesn’t exist, or if the connection doesn’t have access. Returns a 400 or 429 HTTP response if the request exceeds the request limits.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Notion-Version
enum<string>
required

The API version to use for this request. The latest version is 2026-03-11.

Available options:
2026-03-11

Path Parameters

​
view_id
string
required

The ID of the view.

Body

application/json
​
page_size
integer

The number of results to return per page. Maximum: 100

Required range: 1 <= x <= 100

Response

​
object
string
required

The object type.

Allowed value: "view_query"
​
id
string<uuid>
required

The query ID.

​
view_id
string<uuid>
required

The view this query was executed against.

​
expires_at
string<date-time>
required

When the cached query results expire.

​
total_count
number
required

Total number of results in the query.

​
results
object[]
required

The page results for this page.

Maximum array length: 100
​
next_cursor
string<uuid> | null
required

Cursor for the next page of results.

​
has_more
boolean
required

Whether there are more results.

​
request_status
object

Set to { type: 'incomplete', incomplete_reason: 'query_result_limit_reached' } when the view's underlying data source has more rows matching this query than the server-side pagination depth limit allows.