Files
List files
List the files on a cloud browser’s machine, such as what the agent downloaded.
POST
/
api
/
v2
/
sessions
/
{session_id}
/
files
/
list_files
from hai_agents import Client
client = Client()
page = client.session_files.list_files(session_id, path="~/Downloads", max_entries=100)
for entry in page.files:
print(entry.name, entry.size_bytes, entry.modified_at)
import { HaiAgentsClient } from "hai-agents";
const client = new HaiAgentsClient();
const page = await client.sessionFiles.listFiles({
sessionId,
path: "~/Downloads",
maxEntries: 100,
});
for (const entry of page.files) {
console.log(entry.name, entry.sizeBytes, entry.modifiedAt);
}
curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/files/list_files \
-H "Authorization: Bearer $HAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"path": "~/Downloads", "max_entries": 100}'
{
"path": "/home/hai/Downloads",
"files": [
{
"name": "invoice-2026-09.pdf",
"path": "/home/hai/Downloads/invoice-2026-09.pdf",
"size_bytes": 48213,
"modified_at": "2026-09-15T09:41:12Z",
"is_dir": false
}
],
"truncated": false
}
Behavior
Only the browser’s download directory (~/Downloads) is reachable, and only while the cloud browser runs. Paths outside it, including the browser profile, are rejected.
Path parameters
string
required
The agent session ID, or the browser session ID from its
RunnerSessionEvent.Request body
string
default:"~/Downloads"
Directory to list.
integer
default:"500"
Maximum number of entries to return, at least
1. When the directory holds more, truncated is true and the page ends at the oldest entry returned.string
Page cursor: the
modified_at of the last entry of the previous page. Always send it together with name_after.string
Page cursor: the
name of the last entry of the previous page. Modification times are not unique, so the name is what keeps files sharing one from being skipped.Response
200 with the directory listing.
string
The listed directory, resolved.
boolean
true when the listing stopped at max_entries. Take modified_at and name from the last entry and send them as modified_before and name_after for the next page.from hai_agents import Client
client = Client()
page = client.session_files.list_files(session_id, path="~/Downloads", max_entries=100)
for entry in page.files:
print(entry.name, entry.size_bytes, entry.modified_at)
import { HaiAgentsClient } from "hai-agents";
const client = new HaiAgentsClient();
const page = await client.sessionFiles.listFiles({
sessionId,
path: "~/Downloads",
maxEntries: 100,
});
for (const entry of page.files) {
console.log(entry.name, entry.sizeBytes, entry.modifiedAt);
}
curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/files/list_files \
-H "Authorization: Bearer $HAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"path": "~/Downloads", "max_entries": 100}'
{
"path": "/home/hai/Downloads",
"files": [
{
"name": "invoice-2026-09.pdf",
"path": "/home/hai/Downloads/invoice-2026-09.pdf",
"size_bytes": 48213,
"modified_at": "2026-09-15T09:41:12Z",
"is_dir": false
}
],
"truncated": false
}
Page through a large directory
Pass the last entry’smodified_at and name back as the cursor until truncated is false:
Python
cursor = {}
while True:
page = client.session_files.list_files(session_id, max_entries=100, **cursor)
handle(page.files)
if not page.truncated:
break
last = page.files[-1]
cursor = {"modified_before": last.modified_at, "name_after": last.name}
Errors
| Status | Cause |
|---|---|
403 | Path outside ~/Downloads, or not a directory. |
404 | No browser session with this id. |
Was this page helpful?
⌘I
from hai_agents import Client
client = Client()
page = client.session_files.list_files(session_id, path="~/Downloads", max_entries=100)
for entry in page.files:
print(entry.name, entry.size_bytes, entry.modified_at)
import { HaiAgentsClient } from "hai-agents";
const client = new HaiAgentsClient();
const page = await client.sessionFiles.listFiles({
sessionId,
path: "~/Downloads",
maxEntries: 100,
});
for (const entry of page.files) {
console.log(entry.name, entry.sizeBytes, entry.modifiedAt);
}
curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/files/list_files \
-H "Authorization: Bearer $HAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"path": "~/Downloads", "max_entries": 100}'
{
"path": "/home/hai/Downloads",
"files": [
{
"name": "invoice-2026-09.pdf",
"path": "/home/hai/Downloads/invoice-2026-09.pdf",
"size_bytes": 48213,
"modified_at": "2026-09-15T09:41:12Z",
"is_dir": false
}
],
"truncated": false
}