Query Database

Use Case

Use this endpoint to list database records as pages, optionally filtered, sorted, and paginated.

Endpoint

Permissions

Requires databases.read and access to the database.

Parameters

Request Example

{
  "filter": {
    "property": "Status",
    "select": {
      "equals": "Doing"
    }
  },
  "sorts": [
    {
      "property": "Name",
      "direction": "ascending"
    }
  ],
  "start_cursor": null,
  "page_size": 20
}

Response Example

{
  "object": "list",
  "results": [
    {
      "object": "page",
      "id": "11111111-1111-4111-8111-111111111111",
      "page_type": "page",
      "created_time": "2026-04-09T08:00:00.000Z",
      "last_edited_time": "2026-04-09T09:30:00.000Z",
      "created_by": {
        "object": "user",
        "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
      },
      "last_edited_by": {
        "object": "user",
        "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
      },
      "parent": {
        "type": "page_id",
        "page_id": "55555555-5555-4555-8555-555555555555"
      },
      "in_trash": false,
      "icon": null,
      "cover": null,
      "properties": {
        "title": {
          "id": "title",
          "type": "title",
          "title": [
            {
              "type": "text",
              "text": {
                "content": "Release Checklist",
                "link": null
              },
              "plain_text": "Release Checklist",
              "href": null
            }
          ]
        }
      },
      "url": "https://buildin.ai/docs/11111111-1111-4111-8111-111111111111"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Behavior

• Results are page objects because database records are pages.
• Filters and sorts must match the database property schema.
• Unsupported filters or sorts return explicit errors.
• Use next_cursor and has_more for pagination.

View queries (view_id)

• When view_id is provided, the server applies the view configuration with web-client semantics: the view's sorters sort first, page_sort breaks ties, and the view's filter is evaluated in memory.
• Explicit request filter / sorts override the view configuration respectively (they do not merge).
• Known evaluator limitations: formula/rollup conditions are skipped like invalid conditions; page-link and person segments in text conditions render as @<uuid>. See Get Database View for the stored structure contract.
• Cursors are bound to the effective configuration signature (request filter + sorts + view version). If any of them changes between pages, the next page returns 409 conflict and the query must be restarted with a fresh cursor.

Errors

• 400 validation_error: invalid filter, sort, pagination shape, or view_id.
• 400 unsupported_filter: unsupported filter type.
• 400 unsupported_sort: unsupported sort type.
• 401 unauthorized: invalid or expired token.
• 403 forbidden: missing databases.read or no access.
• 404 not_found: database or view does not exist.
• 409 conflict: the effective filter, sorts, or view configuration changed during pagination.

Related Docs

Prerequisites

• Get Database

Next Steps

• Create Page

References

• Page Property Models
• Conventions
• Error Codes