Retrieve Collection

curl --request GET \
  --url https://api.buttercms.com/v2/content/{collection_key}/ \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.buttercms.com/v2/content/{collection_key}/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.buttercms.com/v2/content/{collection_key}/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.buttercms.com/v2/content/{collection_key}/"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.buttercms.com/v2/content/{collection_key}/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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"
      }
    ]
  }
}

GET

content

{collection_key}

Retrieve Collection

curl --request GET \
  --url https://api.buttercms.com/v2/content/{collection_key}/ \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.buttercms.com/v2/content/{collection_key}/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.buttercms.com/v2/content/{collection_key}/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.buttercms.com/v2/content/{collection_key}/"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.buttercms.com/v2/content/{collection_key}/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

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

limit

integer

default:10

Maximum number of items to return for offset-based pagination.

Mutually exclusive with page/page_size parameters.

Values above 100 are capped at 100; values below 1 or invalid fall back to the default of 10 (the request is not rejected).

Required range: 1 <= x <= 100

offset

integer

default:0

Number of items to skip before starting to return results.

Mutually exclusive with page/page_size parameters.

Required range: x >= 0

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"

levels

integer

default:2

Depth of relationship serialization.

Controls how many levels of referenced content to include:

1: Direct fields only, references as URIs
2: Direct fields + one level of references (default)
3-5: Deeper relationship traversal

Important: Higher levels increase response size. Maximum 10MB per response.

Valid range: 1-5 (inclusive). Values outside this range will be automatically capped.

Required range: 1 <= x <= 5

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

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.

Show child attributes

Response

Collection retrieved successfully

Option 1
Option 2

Collection response using page-based pagination

Overview

Read API

Write API

Webhooks API

Image API

Retrieve Collection

Authorizations

Path Parameters

Query Parameters

Response