bricks_list_pages

Phase 1BeginnerRead OnlyComplexity: 2/10

List all pages with search, filter, and element counts

Overview

List all Bricks-enabled pages with their status, template info, element counts, and whether the Bricks editor is active. This is more detailed than the standard WordPress page list because it includes Bricks-specific metadata such as the number of elements on each page.

Use this tool as a first step when exploring an existing site to understand which pages already exist, what state they are in, and how complex their content is. Supports filtering by status, searching by title, and paginated results.

Key Features

Bricks-Specific Metadata

Returns element count and Bricks editor status for each page, unlike the standard WordPress page list.

Flexible Filtering

Filter by status (publish, draft, pending, private, trash, any), search by title, and sort by date, title, or modified.

Pagination Support

Handles large sites with configurable per_page (up to 100) and page number parameters.

When to Use

You need to see all existing pages and their Bricks element counts before building new content
You want to find a specific page by title search
You need to check which pages are published vs. draft before going live
You want to understand the site structure and page hierarchy
Phase 1 reconnaissance: always call this early to avoid creating duplicate pages

Prerequisites

No prerequisites. This is a read-only tool that can be called at any time. Typically the first or second tool called during Phase 1 site reconnaissance.

When NOT to Use

You only need to list generic WordPress posts (use wp_list_posts instead)
You need the full element tree of a specific page (use bricks_get_page_content instead)
You want a condensed section-by-section overview (use bricks_get_page_summary instead)

Parameters

6 Total Parameters6 Optional

statusstringoptional

Filter by post status. One of: publish, draft, pending, private, trash, any.

Default: any Values: publish, draft, pending, private, trash, any

per_pagenumberoptional

Number of pages per request (1-100).

Default: 50

pagenumberoptional

Page number for pagination.

Default: 1

searchstringoptional

Search term to filter pages by title.

orderbystringoptional

Sort field for results.

Default: modified Values: date, title, modified

orderstringoptional

Sort direction.

Default: desc Values: asc, desc

Code Examples

List all published pages

Get all published Bricks pages sorted by most recently modified.

JSON

bricks_list_pages({
  status: "publish",
  orderby: "modified",
  order: "desc"
})

Response

{
  "pages": [
    { "id": 33, "title": "Home", "status": "publish", "slug": "home", "element_count": 45 },
    { "id": 42, "title": "About", "status": "publish", "slug": "about", "element_count": 28 }
  ],
  "total": 2
}

Search for a specific page

Find pages with "contact" in the title.

JSON

bricks_list_pages({
  search: "contact",
  status: "any"
})

Response

{
  "pages": [
    { "id": 55, "title": "Contact Us", "status": "draft", "slug": "contact-us", "element_count": 12 }
  ],
  "total": 1
}

Common Mistakes

Creating a new page without checking if one already exists

Always call bricks_list_pages first to avoid duplicate pages. Search by title to verify.

Wrong

bricks_create_page({ title: "About" })
// Might create a duplicate!

Correct

bricks_list_pages({ search: "About" })
// Check results first, then create only if needed

Using wp_list_posts when you need Bricks element counts

wp_list_posts returns basic WordPress data. Use bricks_list_pages for Bricks-specific metadata like element counts.

Wrong

wp_list_posts({ post_type: "pages" })
// Missing element counts

Correct

bricks_list_pages({ status: "any" })
// Includes element_count per page

Tips & Warnings

Phase 1 Essential: This is one of the first tools to call when working with a Bricks site. It gives you the lay of the land before making any changes.

Element Count Insight: The element_count field tells you how complex each page is. Pages with 0 elements are empty and ready for content. Pages with 50+ elements are already built out.

Pagination: For sites with many pages, increase per_page to 100 or use pagination to ensure you see everything.

Return Values

Field	Type	Description
`pages`	array	Array of page objects with id, title, status, slug, link, element_count, bricks_active, and template info.
`total`	number	Total number of pages matching the filter criteria.
`pages_count`	number	Number of pages returned in this response (for pagination).

Related Tools

Technical Details

Tool ID

bricks_list_pages

API Endpoint

/bricks-mcp/v1/pages

HTTP Method

GET

Namespace

pages-elements

Source File

wordpress/site-info.ts

Version

1.0

Min Bricks Version

1.9

Requires Auth

Yes

Changelog

v1.0

Initial release with status filtering, search, pagination, and sorting.

20250101