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
}
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.
Integration capabilitiesThis endpoint requires an integration to have read content capabilities. For more information on integration capabilities, see the capabilities guide.

​
Errors

Returns a 404 HTTP response if the view doesn’t exist, or if the integration 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.