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

# List files

> List files under the current account with pagination and filters.

`GET /api/v1/cloud/files`

Retrieves files under the current account.

## Headers

| Header          | Required | Description         |
| --------------- | -------- | ------------------- |
| `Authorization` | Yes      | `Bearer $QODER_PAT` |

## Query parameters

| Parameter   | Type    | Required | Description                                                                                                     |
| ----------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `limit`     | integer | No       | Maximum number of files per page. Default 20, range 1-100. Values above 100 return `400 invalid_request_error`. |
| `page`      | string  | No       | Claude-style forward cursor. Equivalent to `after_id`; mutually exclusive with `before_id` and `after_id`       |
| `after_id`  | string  | No       | Cursor pagination: return files after this ID. Mutually exclusive with `page` and `before_id`                   |
| `before_id` | string  | No       | Cursor pagination: return files before this ID. Mutually exclusive with `page` and `after_id`                   |
| `name`      | string  | No       | Case-insensitive prefix search on file name                                                                     |
| `scope_id`  | string  | No       | Filter files associated with a resource scope, currently a Session ID                                           |

## Example request

```bash theme={null}
# Basic list
curl -X GET "https://api.qoder.com/api/v1/cloud/files" \
  -H "Authorization: Bearer $QODER_PAT"

# Filter by Session scope with a page size
curl -X GET "https://api.qoder.com/api/v1/cloud/files?scope_id=sess_019e3bb8e6c47d18&limit=10" \
  -H "Authorization: Bearer $QODER_PAT"

# Cursor pagination
curl -X GET "https://api.qoder.com/api/v1/cloud/files?limit=10&page=file_019e3bb8e6c47d18" \
  -H "Authorization: Bearer $QODER_PAT"
```

## Example response

**HTTP 200 OK**

```json theme={null}
{
  "data": [
    {
      "id": "file_019e3bb8e6c47d189212a79642136696",
      "type": "file",
      "filename": "report.txt",
      "mime_type": "text/plain",
      "size_bytes": 110,
      "downloadable": true,
      "scope": {
        "id": "sess_019e3bb8e6c47d18",
        "type": "session"
      },
      "metadata": {
        "project": "demo"
      },
      "created_at": "2026-05-18T15:33:53Z"
    }
  ],
  "next_page": null,
  "first_id": "file_019e3bb8e6c47d189212a79642136696",
  "has_more": false,
  "last_id": "file_019e3bb8e6c47d189212a79642136696"
}
```

## Response fields

| Field       | Type           | Description                                                               |
| ----------- | -------------- | ------------------------------------------------------------------------- |
| `data`      | array          | Array of [File objects](/cloud-agents/api/files/schemas#file-object)      |
| `next_page` | string \| null | Forward cursor for the next page; use as `page` when `has_more` is `true` |
| `first_id`  | string \| null | ID of the first file on the current page; `null` when `data` is empty     |
| `last_id`   | string \| null | ID of the last file on the current page; `null` when `data` is empty      |
| `has_more`  | boolean        | Whether more files are available                                          |

## Pagination

Results are sorted by `created_at` and `id`. To page through files:

1. Make the first request with `limit` to fetch the first page.
2. If `has_more` is `true`, use `page=<next_page>` to fetch the next page.
3. Use `before_id=<first_id>` to page backward.

## Errors

| HTTP | Type                    | Trigger                                                                              |
| ---- | ----------------------- | ------------------------------------------------------------------------------------ |
| 400  | `invalid_request_error` | Invalid `limit`, or more than one of `page`, `before_id`, and `after_id` is provided |
| 401  | `authentication_error`  | Missing or invalid authentication token                                              |

See [Errors](/cloud-agents/api/conventions/errors) for the full error envelope.

## Related

<CardGroup cols={2}>
  <Card title="Attach and download files" icon="paperclip" href="/cloud-agents/files">
    Upload files to give your agent context, and download files it produces.
  </Card>
</CardGroup>