> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genviral.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Folders

> List folders by media type and parent level in the authenticated key scope

Returns paginated folders for one `media_type` at a hierarchy level.

## Query Parameters

<ParamField query="media_type" type="string" required>
  Folder media type: `ai_image`, `ai_video`, `upload`, or `slideshow`.
</ParamField>

<ParamField query="parent_folder_id" type="string">
  Optional parent folder ID. Omit to list root-level folders.
</ParamField>

<ParamField query="limit" type="number" default="50">
  Number of folders to return (`1-100`).
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of folders to skip.
</ParamField>

## Response

* `folders` - Folder summaries (`file_count`, `subfolder_count`, `preview_files`)
* `total` - Total matching folders
* `limit` / `offset` - Applied pagination values

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://www.genviral.io/api/partner/v1/folders?media_type=upload&limit=20&offset=0' \
    --header 'Authorization: Bearer <token>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "ok": true,
    "code": 200,
    "message": "Folders retrieved",
    "data": {
      "folders": [
        {
          "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
          "name": "Product Shots",
          "media_type": "upload",
          "parent_folder_id": null,
          "path": "/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
          "file_count": 12,
          "subfolder_count": 2,
          "preview_files": [
            {
              "id": "file_1",
              "url": "https://cdn.vireel.io/...",
              "content_type": "image/jpeg"
            }
          ],
          "created_at": "2026-03-01T09:00:00.000Z",
          "updated_at": "2026-03-01T09:00:00.000Z"
        }
      ],
      "total": 1,
      "limit": 20,
      "offset": 0
    }
  }
  ```
</ResponseExample>

## Error Responses

* `400 invalid_query_parameter` - query validation failed
* `401` / `403` - auth/entitlement failure
* `500 folders_list_failed` - unexpected folder query failure