# Retrieve Collection

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.

Endpoint: GET /content/{collection_key}/
Version: 2.0.0
Security: readTokenAuthHeader, readTokenAuthQuery

## Path parameters:

  - `collection_key` (string, required)
    The unique identifier/slug of the Collection to retrieve.

Must match an existing collection in your organization.
    Example: "artists"

## Query parameters:

  - `auth_token` (string)
    Your ButterCMS read API token
    Example: "your_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.
    Example: "artists,albums"

  - `preview` (integer)
    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.
    Enum: 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)
    Page number for page-based pagination.

Mutually exclusive with limit/offset parameters.
    Example: 2

  - `page_size` (integer)
    Number of items per page for page-based pagination.

Mutually exclusive with limit/offset parameters.
    Example: 5

  - `limit` (integer)
    Maximum number of items to return for offset-based pagination.

Mutually exclusive with page/page_size parameters.
    Example: 5

  - `offset` (integer)
    Number of items to skip before starting to return results.

Mutually exclusive with page/page_size parameters.
    Example: 10

  - `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.
    Example: "en"

  - `levels` (integer)
    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.

  - `alt_media_text` (integer)
    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.
    Enum: 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.

## Response 400 fields (application/json):

  - `detail` (string)
    Error message describing what went wrong
    Example: "Authentication credentials were not provided"

## Response 401 fields (application/json):

  - `detail` (string)
    Error message describing what went wrong
    Example: "Authentication credentials were not provided"

## Response 404 fields (application/json):

  - `detail` (string)
    Error message describing what went wrong
    Example: "Authentication credentials were not provided"