---
title: "Retrieve media"
method: GET
path: "/v1/media"
tags: ["MediaLibrary"]
---

# Retrieve media

`GET /v1/media`

Retrieve media content and optionally filter by search criteria and mediaType. If no parameters are given, the app should return either the contents of the base folder if it has a folder hierarchy or trending/popular media results otherwise.

## Query parameters

- `parentId` string
- `cursor` string
- `query` string
- `pageSize` integer

## Response `200`

successful operation

- MediaResponseEnvelope
  - `data` MediaEntryResult[], required — The media results
    - `id` string — Resource ID. This field must be included for folders.
    - `name` string — Resource filename.
    - `altText` string — Alt-text for the image, if available.
    - `mediaType` 'AnimatedGif' | 'Image' | 'Folder' | 'Video', required
    - `mimeType` 'image/jpeg' | 'image/png' | 'image/gif' | 'video/mp4' | 'application/vnd.hootsuite.folder' — This field is optional ONLY in the case where the original.url field ends in an identifiable file extension (such as '.jpg'). In every other case it is required. Regardless of whether the mimeType is included or inferred from the URL, the response must be one of the enumerated mimeTypes.
    - `original` MediaInfo — The original media file. This field is required for all files except folders.
      - `url` string, required — URL to the media resource.
      - `width` integer, required — Width in pixels.
      - `height` integer, required — Height in pixels.
      - `sizeInBytes` integer — File size in bytes. This is a hint and should be provided if available.
    - `thumbnail` ThumbnailInfo — A smaller thumbnail for display in a selector. This field is REQUIRED for all files except folders.
      - `url` string, required — URL to the thumbnail.
      - `width` integer, required — Width in pixels.
      - `height` integer, required — Height in pixels.
    - `durationInSeconds` integer — This field is REQUIRED for videos.
    - `subtitleFileName` string — Name for the SubRip subtitles file in the format given here: https://www.facebook.com/help/www/1528795707381162
    - `subtitles` string — URL to the SubRip subtitles file (max 200kB)
    - `tags` string[] — Tags for the image, these may be included in posts when the media item is attached
  - `metadata` MediaResponseMetadataEnvelope, required — The metadata response envelope.
    - `cursor` MediaResponseCursors, required — The cursors used to get the next or previous page of results. These should be URL-safe. All params from the request must be encoded in the cursor, so that a subsequent call can be made with only the cursor to fetch the next or previous page of results. If there are no more results in the cursor's direction, it can be omitted.
      - `next` string — A cursor that can be used to return the next page of results. This should be URL-safe. If there are no more results, it can be omitted.
      - `previous` string — A cursor that can be used to return the previous page of results. This should be URL-safe. If there are no previous results, this can be omitted.

---

[API](https://skmtc.dev/hootsuite/apis/hootsuite-apps-api.md) · [All operations](https://skmtc.dev/hootsuite/apis/hootsuite-apps-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hootsuite/hootsuite-apps-api/revisions/015e2672e012/schema)