Skip to main content
GET
/
pages
/
{page_type}
Get multiple Pages
curl --request GET \
  --url 'https://api.buttercms.com/v2/pages/{page_type}/?auth_token='
{
  "meta": {
    "previous_page": null,
    "next_page": null,
    "count": 2
  },
  "data": [
    {
      "slug": "single-page-1",
      "page_type": null,
      "published": "2019-11-12T17:23:53.109696Z",
      "updated": "2020-10-22T20:07:52.965850Z",
      "fields": {
        "title": "This is a single page",
        "body": "<p>Single PAGE!</p>"
      }
    },
    {
      "slug": "single-page-2",
      "page_type": null,
      "published": "2019-11-12T17:23:53.109696Z",
      "updated": "2020-10-22T20:07:52.965850Z",
      "fields": {
        "title": "Amazing Single Page",
        "body": "<p>Another single page!</p>"
      }
    }
  ]
}
Retrieve a paginated list of pages for a given page type, or all Single Pages when using the wildcard * as the page type. This endpoint supports comprehensive filtering and sorting for Page Type collections. Single Pages: Use * as your page_type parameter to retrieve Single Pages, which are unique pages like your Homepage, About page, or Contact page. This is particularly useful for generating sitemaps or building navigation structures that include your standalone pages. Page Types: Use the actual page type slug to retrieve all Pages of that type, like new articles, product pages, etc. Pages will all have the same field schema.
Important: Advanced filtering and ordering capabilities are only available for Page Type endpoints, not when retrieving Single Pages with the * wildcard. Use dotted notation for field filters (e.g., fields.title=Home).
See also: Architecture & Performance for guidance on levels, pagination, and performance best practices.

Authorizations

​
auth_token
string
query
required

Pass your API token via the auth_token parameter on every request: ?auth_token=your_read_api_token.

You can access your API token from your settings page.

Requests made with a missing or invalid token will get a 401 Unauthorized response. All requests must be made over HTTPS.

Path Parameters

​
page_type
string
required

The slug of the type of pages you want to retrieve, or * for Single Pages.

  • Use * to get Single Pages (those without a Page Type)
  • Use the actual page type slug to get pages of that specific type

Query Parameters

​
preview
enum<integer>
default:0

Set to 1 to return the latest draft version of a page. Useful for previewing changes before publishing live. i.e. &preview=1. If you are trying to view a scheduled page for which the most recent page version is published, you must pass the preview parameter to see the scheduled changes.

Set to 1 to access unpublished/draft collection items. Useful for staging environments.

Available options:
0,
1
​
page
integer
default:1

Page number for page-based pagination.

Mutually exclusive with limit/offset parameters.

Required range: x >= 1
​
page_size
integer
default:10

Number of items per page for page-based pagination.

Mutually exclusive with limit/offset parameters.

Required range: 1 <= x <= 100
​
locale
string

Set to the api slug of your configured locale (e.g. en or fr). When omitted, this query parameter will default to your organization's default locale.

Maximum string length: 10
Example:

"en"

​
alt_media_text
enum<integer>
default:0

Media field response format.

Affects only media-typed fields. Other field types are unchanged.

  • 0 (default): Media fields return simple URL strings
  • 1: Media fields return objects with at least url and, when available, alt. If the stored media value is just a URL string, the object will include url only.
Available options:
0,
1
​
auth_token
string

Your ButterCMS read API token

​
order
string

Can order by page level published, updated, or a content field of the Page Type. Defaults to ascending, prepend '-' to sort descending.

Note: Only available for Page Type endpoints, not for Single Pages (page_type=*).

​
fields.seo.title
string

Filter the result set by a nested field value. This is an example of field filtering — you can filter by any field using the pattern fields.<field_name>=<value>.

You can pass in multiple filters at once. For example: &fields.seo.title=Home&fields.headline=Welcome

To filter on Reference or Component fields use dot notation. For example: fields.hero.title=value or fields.hero.reference.title=value

Note: Field filtering is only available for Page Type endpoints, not for Single Pages (page_type=*).

​
fields.headline
string

Filter the result set by a top-level field value. This is an example of field filtering — you can filter by any field using the pattern fields.<field_name>=<value>.

Note: Field filtering is only available for Page Type endpoints, not for Single Pages (page_type=*).

Response

Success

Returns a hash with a data property that contains an array of pages, and a meta property that contains pagination information.

  • For Single Pages (page_type=*): Returns pages without a page type
  • For Page Types: Returns pages of the specified type
​
meta
object
​
data
object[]