> ## 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 Files

> List partner files in the authenticated key scope

Retrieve a paginated list of partner files in the authenticated key scope.
This includes:

* direct uploads created via `POST /files`
* media ingested by partner posting flows

## Query Parameters

<ParamField query="limit" type="number" default="50">
  Number of files to return. Must be an integer between `1` and `100`.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of files to skip for pagination. Must be an integer `>= 0`.
</ParamField>

<ParamField query="type" type="string">
  Filter by file type: `image` or `video`.
</ParamField>

<ParamField query="context" type="string">
  Optional context filter.

  * Omit `context` to keep default partner-only results.
  * Use a single context (example: `ai-studio`) or comma-separated contexts (example: `ai-studio,media-upload`).
  * Use `context=all` to return all file contexts in your authenticated key scope.
</ParamField>

## Response

Successful requests return `200` with:

* `files` - Array of file objects
* `total` - Total count of matching files
* `limit` - Applied limit
* `offset` - Applied offset

### File Object

| Field         | Type     | Description            |
| ------------- | -------- | ---------------------- |
| `id`          | `string` | Unique file identifier |
| `url`         | `string` | CDN URL for the file   |
| `contentType` | `string` | MIME type of the file  |
| `filename`    | `string` | Original filename      |
| `size`        | `number` | File size in bytes     |
| `createdAt`   | `string` | ISO 8601 timestamp     |

## Examples

### List all files

<RequestExample>
  ```javascript theme={null}
  import fetch from "node-fetch";

  const response = await fetch(
    "https://www.genviral.io/api/partner/v1/files?limit=20",
    {
      headers: {
        Authorization: "Bearer <token>",
      },
    }
  );

  const { data } = await response.json();
  console.log(`Found ${data.total} files`);
  data.files.forEach((file) => {
    console.log(`${file.filename}: ${file.url}`);
  });
  ```
</RequestExample>

```bash theme={null}
# List all files
curl --request GET \
  --url 'https://www.genviral.io/api/partner/v1/files?limit=20' \
  --header 'Authorization: Bearer <token>'

# List only videos
curl --request GET \
  --url 'https://www.genviral.io/api/partner/v1/files?type=video&limit=10' \
  --header 'Authorization: Bearer <token>'

# Paginate through results
curl --request GET \
  --url 'https://www.genviral.io/api/partner/v1/files?limit=20&offset=20' \
  --header 'Authorization: Bearer <token>'

# Query AI Studio + media uploads contexts
curl --request GET \
  --url 'https://www.genviral.io/api/partner/v1/files?context=ai-studio,media-upload&limit=20' \
  --header 'Authorization: Bearer <token>'

# Query all file contexts in key scope
curl --request GET \
  --url 'https://www.genviral.io/api/partner/v1/files?context=all&limit=20' \
  --header 'Authorization: Bearer <token>'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "ok": true,
    "code": 200,
    "message": "Files retrieved",
    "data": {
      "files": [
        {
          "id": "abc123",
          "url": "https://cdn.vireel.io/partner-api/workspaces/workspace_123/abc123.mp4",
          "contentType": "video/mp4",
          "filename": "promo-video.mp4",
          "size": 15728640,
          "createdAt": "2025-01-20T14:30:00.000Z"
        },
        {
          "id": "def456",
          "url": "https://cdn.vireel.io/partner-api/workspaces/workspace_123/def456.jpg",
          "contentType": "image/jpeg",
          "filename": "slide-1.jpg",
          "size": 524288,
          "createdAt": "2025-01-20T14:25:00.000Z"
        }
      ],
      "total": 42,
      "limit": 20,
      "offset": 0,
      "context": null
    }
  }
  ```
</ResponseExample>

## Error Responses

* `400 invalid_query_parameter` - one or more query parameters are invalid
* `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 list_failed` - Failed to retrieve files (retry)

<Tip>
  Use the `type` filter to quickly find videos or images when building slideshows
  or selecting media for posts.
</Tip>