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.

Errors

• 400 validation_error: invalid filter, sort, or pagination shape.
• 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 does not exist.

Related Docs

Prerequisites

• Get Database

Next Steps

• Create Page

References

• Page Property Models
• Conventions
• Error Codes