Skip to main content
GET
/
content
/
{collection_key}
Retrieve Collection
curl --request GET \
  --url https://api.buttercms.com/v2/content/{collection_key}/ \
  --header 'Authorization: <api-key>'
{
  "meta": {
    "count": 25,
    "next_page": 3,
    "previous_page": 1
  },
  "data": {
    "artists": [
      {
        "meta": {
          "id": 123
        },
        "name": "The Beatles",
        "genre": "Rock",
        "formed_year": 1960,
        "description": "Legendary British rock band"
      },
      {
        "meta": {
          "id": 124
        },
        "name": "The Rolling Stones",
        "genre": "Rock",
        "formed_year": 1962,
        "description": "Iconic rock and roll band"
      }
    ]
  }
}
Retrieve items from a specific Collection with comprehensive filtering, pagination, and relationship serialization capabilities. This endpoint provides flexible access to your dynamic content with powerful query options. Collection Structure: Collections contain completely user-defined content with customizable field schemas that you configure through the dashboard. Each collection can have different field types, validation rules, and structural requirements based on your content needs. Response Format: The response includes a meta object containing pagination information and result counts, a data array with the actual collection items, and individual item.meta objects containing unique IDs that you’ll need for update and delete operations. See also: Architecture & Performance for guidance on levels, pagination, and performance best practices.

Authorizations

​
Authorization
string
header
required

Set the Authorization header to Token your_read_api_token.

Example: Authorization: Token abc123def456

Note: The header value includes the Token prefix.

You can access your API token from your settings page.

Path Parameters

​
collection_key
string
required

The unique identifier/slug of the Collection to retrieve.

Must match an existing collection in your organization.

Maximum string length: 100

Query Parameters

​
auth_token
string

Your ButterCMS read API token

​
keys
string

Comma-delimited list of Collection keys for multi-collection retrieval.

Note: This is a legacy parameter. For single collection retrieval, use the path parameter instead.

​
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
​
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=*).

​
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"

​
fields
object

Dynamic field filtering using dot notation.

Filter collection items by any field using the pattern fields.{field_name}=value:

  • fields.genre=Rock - Filter by genre field
  • fields.status=published - Filter by status field
  • fields.year=2023 - Filter by year field

Multiple field filters can be combined in a single request.

Response

Collection retrieved successfully

Collection response using page-based pagination

​
meta
object
required

Pagination metadata for collection retrieval

​
data
object
required

Collection data object with dynamic key based on collection name