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

# List and query media

`GET /buckets/{slug}/media`

Query media in the Bucket. This is also how you fetch a single media item by name: pass `query={"name":"7f9403a32f29-toucan.jpg"}`.

The `name` of a media item is the value you assign to a File or Image Metafield when creating or updating an Object. Upload is not part of this host: `POST /v3/buckets/{slug}/media` is served by `https://workers.cosmicjs.com`.

## Query parameters

- `read_key` string
- `query` string
- `props` string
- `sort` 'created_at' | '-created_at' | 'modified_at' | '-modified_at' | 'random'
- `limit` integer
- `skip` integer
- `useCache` boolean
- `pretty` boolean

## Response `200`

The matching media.

- MediaListResponse
  - `media` Media[], required
    - `id` string
    - `name` string — Unique file name within the Bucket. This is the value you assign to a File or Image Metafield.
    - `original_name` string — The file name as uploaded.
    - `size` union — File size in bytes.
      - integer
      - string
    - `type` string — MIME type.
    - `bucket` string — Bucket id.
    - `folder` string, nullable
    - `alt_text` string, nullable — Images only.
    - `width` integer, nullable — Pixel width. Images only.
    - `height` integer, nullable — Pixel height. Images only.
    - `url` string, uri — CDN URL.
    - `imgix_url` string, uri — imgix URL, which accepts image processing query parameters.
    - `metadata` object, nullable — Arbitrary JSON metadata you attach to the media.
    - `created_at` string, date-time
  - `total` integer
  - `limit` integer

## 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` — The addressed resource does not exist in this Bucket. Note that this covers a resource missing from a route that exists; an unrecognized route answers 200 with a `Route not found` body instead, as described in the API description above.
- `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)