> ## 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 Folder Items

> List files or slideshows contained in a folder

Folder item behavior depends on folder media type:

* `slideshow` folder → item IDs are slideshow IDs
* `ai_image`, `ai_video`, and `upload` folders → item IDs are file IDs

## Path Parameters

<ParamField path="folderId" type="string" required>
  Folder UUID.
</ParamField>

## Query Parameters

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

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

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

<ResponseExample>
  ```json Response theme={null}
  {
    "ok": true,
    "code": 200,
    "message": "Folder items retrieved",
    "data": {
      "media_type": "upload",
      "item_type": "file",
      "items": [
        {
          "id": "11111111-1111-1111-1111-111111111111",
          "url": "https://cdn.vireel.io/...",
          "content_type": "image/jpeg",
          "filename": "slide-1.jpg",
          "size": 524288,
          "created_at": "2026-03-01T09:00:00.000Z",
          "added_at": "2026-03-01T09:05:00.000Z"
        }
      ],
      "total": 1,
      "limit": 20,
      "offset": 0
    }
  }
  ```
</ResponseExample>

## Error Responses

* `400 invalid_query_parameter` - invalid `limit` or `offset`
* `422 invalid_path` - `folderId` is not a valid UUID
* `422 invalid_folder_media_type` - folder media type is not supported by Partner folder APIs
* `404 not_found` - folder not visible in key scope
* `401` - authentication failed (missing/invalid/revoked token)
* `402 subscription_required` - active Creator/Professional/Business plan required
* `403 tier_not_allowed` - Scheduler tier cannot use Partner API
* `500 folder_items_list_failed` - unexpected failure