---
title: "List your media library"
method: GET
path: "/media-library"
tags: ["Media library"]
---

# List your media library

`GET /media-library`

## Request

- Base URL: `https://www.sociahive.com/api/v1`
- URL: `https://www.sociahive.com/api/v1/media-library`
- Auth: one of:
  - API key in header `X-API-Key`
  - OAuth 2 (authorization code, authorization URL `/api/oauth/authorize`, token URL `/api/oauth/token`, scopes: `posts:read`)

The images and videos you uploaded to the scheduler, newest first. Filter by `kind` or `tag`, search file names and tags with `q`, page with `cursor`. Behind the SCHEDULER_MEDIA_LIBRARY feature flag (403 `feature_disabled` while off).

## Query parameters

- `kind` 'image' | 'video'
- `tag` string
- `q` string: Search file names and tags.
- `limit` integer: Default 30.
- `cursor` string

## Response `200`

A page of media

- MediaLibraryPage
  - `items` MediaAsset[], required
    - `id` string, required
    - `kind` 'image' | 'video', required
    - `url` string, uri, required: Public URL. Use it as post media.
    - `r2_key` string, required: Storage key, unique per user.
    - `filename` string
    - `mime_type` string
    - `size_bytes` integer
    - `width` integer
    - `height` integer
    - `duration_ms` integer
    - `tags` string[], required
    - `used_in_count` integer, required: How many of your posts use this file.
    - `origin` 'upload' | 'ai_image' | 'backfill', required
    - `created_at` string, date-time, required
  - `next_cursor` string, nullable, required: Pass as `cursor` for the next page; null on the last page.

## Other responses

- `400`: Bad request — invalid parameters
- `401`: Authentication required — provide X-API-Key or Bearer token
- `403`: Insufficient scope for this operation
- `429`: Rate limit exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/sociahive/apis/sociahive-api.md) · [All operations](https://skmtc.dev/sociahive/apis/sociahive-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sociahive/apis/sociahive-api/revisions/791b8548d288?raw)