---
title: "List and query Objects"
method: GET
path: "/buckets/{slug}/objects"
tags: ["Objects"]
---

# List and query Objects

`GET /buckets/{slug}/objects`

Query Objects in the Bucket. This is the main read endpoint and also the way to fetch a single Object by slug: pass `query={"type":"posts","slug":"my-post"}` and read the first element of `objects`.

The `query` parameter is a URL-encoded JSON object following MongoDB comparison and logical operator syntax. Use `props` to limit the response to the fields you need, which matters because the API rejects responses over roughly 6 MB with a 413. Use `depth` to resolve Object Relationship Metafields into nested Objects. For large collections, prefer cursor pagination with `after` over large `skip` offsets.

## Query parameters

- `read_key` string
- `preview_token` string
- `query` string
- `props` string
- `status` 'published' | 'draft' | 'any'
- `sort` string
- `limit` integer
- `skip` integer
- `depth` integer
- `after` string
- `useCache` boolean
- `pretty` boolean

## Response `200`

The matching Objects.

- ObjectListResponse
  - `objects` Object[], required
    - `id` string — Unique identifier.
    - `type` string — Object type slug.
    - `title` string
    - `slug` string — Unique within the Object type. Localized versions of an Object share a slug and count as one Object against plan limits.
    - `status` 'published' | 'draft'
    - `content` string, nullable — HTML content. Deprecated in v3; use a Metafield instead.
    - `metadata` Metadata — Values of the Metafields defined on the Object type, keyed by Metafield `key`. The value shape follows the Metafield type, and differs between write and read for two of them: - Text, textarea, markdown, and HTML Metafields are strings. Number Metafields are numbers, switches are booleans, dates are ISO 8601 strings. - Object Relationship Metafields are written as an Object `id` string (or an array of ids for the multiple variant) and returned as a nested Object (or array of Objects) once `depth` is at least 1. - File and Image Metafields are written as a media `name` string (or an array of names) and returned as an object with `url` and `imgix_url`, plus `alt_text`, `width`, and `height` when requested via `props`. - Repeater Metafields are arrays of objects keyed by the child Metafield keys.
    - `bucket` string — Bucket id.
    - `thumbnail` string, nullable — Media `name` of the Object thumbnail. Returned as a URL on read.
    - `locale` string, nullable — Locale code, when the Object type has localization enabled.
    - `created_at` string, date-time
    - `created_by` string — User id.
    - `modified_at` string, date-time
    - `modified_by` string — User id.
    - `published_at` string, date-time, nullable
    - `publish_at` union — UNIX millisecond timestamp for scheduled publishing.
      - string
      - number
    - `unpublish_at` union — UNIX millisecond timestamp for scheduled unpublishing.
      - string
      - number
    - `assigned_to` string, nullable — User id.
    - `assigned_by` string, nullable — User id.
    - `assigned_at` string, date-time, nullable
  - `total` integer — Total number of Objects matching the query, ignoring `limit` and `skip`.
  - `limit` integer — The `limit` applied to this response.

## Other responses

- `400` — The request was invalid, most often a malformed `query` or a Metafield value that failed validation.
- `401` — The access key is missing or incorrect.
- `402` — The Bucket needs to be upgraded before it can be used again.
- `404` — No Objects matched the query.
- `413` — The response exceeded the 6 MB limit. Narrow `props`, lower `limit`, or paginate.
- `429` — Too many requests hit the API too quickly. Back off and retry.
- `500` — Something went wrong on the Cosmic side.

---

[API](https://skmtc.dev/cosmicjs/apis/cosmic-rest-api-v3.md) · [All operations](https://skmtc.dev/cosmicjs/apis/cosmic-rest-api-v3/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cosmicjs/cosmic-rest-api-v3/revisions/e0aa2a0913b3/schema)