> ## Documentation Index
> Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve Collection

> Retrieve items from a specific Collection with comprehensive filtering, pagination, and relationship serialization.

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.


## OpenAPI

````yaml /api/openapi/read_api.yaml get /content/{collection_key}/
openapi: 3.1.0
info:
  title: ButterCMS Read API
  version: 2.0.0
  description: >
    Read endpoints for the ButterCMS API — Pages, Collections, Blog Posts, Blog
    Metadata, and Feeds.
  contact:
    email: support@buttercms.com
  license:
    name: ButterCMS Terms of Service
    url: https://buttercms.com/terms/
servers:
  - url: https://api.buttercms.com/v2
    description: ButterCMS API v2
security:
  - readTokenAuthHeader: []
  - readTokenAuthQuery: []
tags:
  - name: Pages
    description: >
      Retrieve pages from your ButterCMS account.


      **Single Pages**: Use `*` as the page_type to get Single Pages (those
      without a Page Type) which represent unique pages on your site like your
      Homepage. Useful for creating your sitemap.xml.


      **Page Type Pages**: Use the actual page type slug to get pages of that
      specific type. Page Types allow you to create many pages with the same
      structure.


      **Note:** The fields of a page are defined by you, they are customizable.
      Sample responses below contain a basic set of fields for illustrative
      purposes.
  - name: Collections
    description: >
      Retrieve collection items from your ButterCMS account. Collections are
      flexible, user-defined content structures with completely customizable
      field schemas.


      See also: Architecture & Performance for guidance on `levels`, pagination,
      and performance best practices.
  - name: Blog posts
    description: >
      Retrieve blog posts from your ButterCMS account. List blog posts with
      pagination and filtering options, or retrieve individual posts by slug.
  - name: Blog metadata
    description: >
      Retrieve blog-related metadata including authors, categories, and tags.
      These endpoints provide access to the organizational structure of your
      blog content.
  - name: Feeds and utilities
    description: >
      Generate XML feeds for content syndication and SEO.


      - **RSS Feed**: Fully generated RSS 2.0 feed for your blog

      - **Atom Feed**: Standards-compliant Atom 1.0 feed

      - **Sitemap**: XML sitemap for search engine discovery


      All feeds can be filtered by category or tag and include only published
      content from your organization.
  - name: Images - Info
    description: >
      ButterCMS has an integration with
      [Filestack](https://www.filestack.com/docs/api/processing/) for image
      transformations. You can leverage their robust set of image transformation
      capabilities.


      After you upload an image, to create a thumbnail, here's an example:


      - **Original URL**: `https://cdn.buttercms.com/3ccPHhYHTNK2zQ14gCOy`

      - **Thumbnail URL**:
      `https://cdn.buttercms.com/resize=width:100,height:100/3ccPHhYHTNK2zQ14gCOy`


      For complete transformation options and parameters, see the [full
      Filestack documentation](https://www.filestack.com/docs/api/processing/).
paths:
  /content/{collection_key}/:
    get:
      tags:
        - Collections
      summary: Retrieve Collection
      description: >
        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.
      operationId: retrieveCollection
      parameters:
        - name: collection_key
          in: path
          required: true
          schema:
            type: string
            maxLength: 100
          description: |
            The unique identifier/slug of the Collection to retrieve.

            Must match an existing collection in your organization.
          example: artists
        - $ref: '#/components/parameters/auth_token'
        - name: keys
          in: query
          required: false
          schema:
            type: string
          description: >
            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.
          example: artists,albums
        - $ref: '#/components/parameters/preview'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/page_size'
        - $ref: 93cf2c7e-75ce-4beb-b455-38e9541bd339
        - $ref: 86c8b313-f5c9-4a9e-9b7a-5b789f6e0aae
        - $ref: '#/components/parameters/locale'
        - $ref: 43ca77a3-2fdc-4e00-a9e8-459d3b50cfc0
        - $ref: e37f56db-252c-4d03-80b7-ce2afd7eaaae
        - name: fields
          in: query
          required: false
          style: deepObject
          explode: true
          schema:
            type: object
            additionalProperties:
              type: string
          description: >
            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.
          examples:
            genre_filter:
              summary: Filter by genre
              value:
                genre: Rock
            status_filter:
              summary: Filter by status
              value:
                status: published
            multi_filter:
              summary: Multiple filters
              value:
                genre: Rock
                year: '2023'
      responses:
        '200':
          description: Collection retrieved successfully
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PageBasedCollectionResponse'
                  - $ref: '#/components/schemas/OffsetBasedCollectionResponse'
              examples:
                artists_collection:
                  summary: Artists collection response
                  value:
                    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
                filtered_response:
                  summary: Filtered collection response
                  value:
                    meta:
                      count: 5
                      next_page: null
                      previous_page: null
                    data:
                      products:
                        - meta:
                            id: 456
                          title: Premium Headphones
                          category: Electronics
                          price: 299.99
                          in_stock: true
                localized_response:
                  summary: Localized collection response
                  value:
                    meta:
                      count: 10
                      next_page: 2
                      previous_page: null
                    data:
                      articles:
                        - meta:
                            id: 789
                          title: Bonjour le monde
                          content: Contenu en français...
                          locale: fr
                offset_collection_response:
                  summary: Offset-based pagination collection response
                  description: Using ?limit=10&offset=5 parameters
                  value:
                    meta:
                      count: 25
                      next_offset: 15
                      previous_offset: null
                    data:
                      artists:
                        - meta:
                            id: 125
                          name: Pink Floyd
                          genre: Progressive Rock
                          formed_year: 1965
                          description: English rock band known for philosophical lyrics
                        - meta:
                            id: 126
                          name: Led Zeppelin
                          genre: Hard Rock
                          formed_year: 1968
                          description: Influential English rock band
                media_url_format:
                  summary: Media field as URL string (alt_media_text=0)
                  description: >
                    When `alt_media_text=0` (default), media fields are returned
                    as URL strings.
                  value:
                    meta:
                      count: 1
                      next_page: null
                      previous_page: null
                    data:
                      products:
                        - meta:
                            id: 900
                          title: Poster
                          media: https://cdn.example.com/media/poster.jpg
                media_object_format:
                  summary: Media field as object (alt_media_text=1)
                  description: >
                    When `alt_media_text=1`, media fields are returned as
                    objects. The object always includes `url`, and `alt` is
                    included when available.
                  value:
                    meta:
                      count: 1
                      next_page: null
                      previous_page: null
                    data:
                      products:
                        - meta:
                            id: 901
                          title: Poster
                          media:
                            url: https://cdn.example.com/media/poster.jpg
                            alt: Movie poster artwork
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_locale:
                  summary: Invalid locale
                  value:
                    detail: Invalid locale 'xyz' specified
                invalid_levels:
                  summary: Invalid levels parameter
                  value:
                    detail: >-
                      levels query parameter should be an integer between 1 and
                      5 (inclusive)
                invalid_filter:
                  summary: Invalid filter key
                  value:
                    detail: Invalid filter key 'nonexistent_field'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          description: Not Found - Collection not found or Invalid Pagination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                collection_not_found:
                  summary: Collection not found
                  value:
                    detail: Not found.
                invalid_pagination:
                  summary: Invalid pagination
                  value:
                    detail: Invalid Page.
      security:
        - readTokenAuthHeader: []
        - readTokenAuthQuery: []
components:
  parameters:
    auth_token:
      name: auth_token
      in: query
      required: false
      schema:
        type: string
      description: |
        Your ButterCMS read API token
      example: your_api_token
    preview:
      name: preview
      in: query
      description: >
        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.
      required: false
      schema:
        type: integer
        enum:
          - 0
          - 1
        default: 0
      example: 1
    order:
      name: order
      in: query
      description: >
        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=*`).
      required: false
      schema:
        type: string
      examples:
        ascending_title:
          value: title
          description: Order by title ascending
        descending_published:
          value: '-published'
          description: Order by published date descending
        ascending_updated:
          value: updated
          description: Order by updated date ascending
    page:
      name: page
      in: query
      description: |
        Page number for page-based pagination.

        **Mutually exclusive with limit/offset parameters.**
      required: false
      schema:
        type: integer
        default: 1
        minimum: 1
      example: 2
    page_size:
      name: page_size
      in: query
      description: |
        Number of items per page for page-based pagination.

        **Mutually exclusive with limit/offset parameters.**
      required: false
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 100
      example: 5
    locale:
      name: locale
      in: query
      description: >
        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.
      required: false
      schema:
        type: string
        maxLength: 10
        example: en
      examples:
        english:
          value: en
          description: English locale
        spanish:
          value: es
          description: Spanish locale
        french:
          value: fr
          description: French locale
  schemas:
    PageBasedCollectionResponse:
      type: object
      description: Collection response using page-based pagination
      properties:
        meta:
          $ref: '#/components/schemas/CollectionPaginationMeta'
        data:
          type: object
          description: Collection data object with dynamic key based on collection name
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/CollectionItemObject'
      required:
        - meta
        - data
    OffsetBasedCollectionResponse:
      type: object
      description: Collection response using offset-based pagination
      properties:
        meta:
          $ref: '#/components/schemas/OffsetPaginationMeta'
        data:
          type: object
          description: Collection data object with dynamic key based on collection name
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/CollectionItemObject'
      required:
        - meta
        - data
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Error message describing what went wrong
          example: Authentication credentials were not provided
    CollectionPaginationMeta:
      type: object
      description: Pagination metadata for collection retrieval
      properties:
        count:
          type: integer
          description: Total number of items in the collection (across all pages)
          example: 150
        next_page:
          type:
            - integer
            - 'null'
          description: Next page number if more pages exist, null if this is the last page
          example: 3
        previous_page:
          type:
            - integer
            - 'null'
          description: >-
            Previous page number if previous pages exist, null if this is the
            first page
          example: 1
    CollectionItemObject:
      type: object
      description: Individual collection item with dynamic field structure and metadata
      properties:
        meta:
          $ref: '#/components/schemas/CollectionItemMeta'
      additionalProperties: true
      example:
        meta:
          id: 123
        name: The Beatles
        genre: Rock
        formed_year: 1960
        members:
          - John Lennon
          - Paul McCartney
          - George Harrison
          - Ringo Starr
        description: Legendary British rock band
    OffsetPaginationMeta:
      type: object
      description: Pagination metadata for limit/offset pagination
      properties:
        count:
          type: integer
          description: Total number of items
          example: 25
        next_offset:
          type:
            - integer
            - 'null'
          description: Offset for the next page, null if no next page
          example: 20
        previous_offset:
          type:
            - integer
            - 'null'
          description: Offset for the previous page, null if no previous page
          example: null
    CollectionItemMeta:
      type: object
      description: Metadata for collection items containing unique identifier
      properties:
        id:
          type: integer
          description: >-
            Unique identifier for the collection item, used for updates and
            deletions
          example: 123
      required:
        - id
  responses:
    UnauthorizedResponse:
      description: Unauthorized - Invalid or missing API token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing_token:
              summary: Missing API token
              value:
                detail: Authentication credentials were not provided
            invalid_token:
              summary: Invalid API token
              value:
                detail: Invalid token
  securitySchemes:
    readTokenAuthHeader:
      type: apiKey
      in: header
      name: Authorization
      description: |
        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.
    readTokenAuthQuery:
      type: apiKey
      in: query
      name: auth_token
      description: >
        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.

````