Create a view query

Execute a view’s query and return the first page of results.

POST /v1/views/{view_id}/queries

TypeScript SDK

JavaScript

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"
})

200

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

This 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 webhooks

If 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

200

application/json

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

Show child attributes

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.

Show child attributes