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

> ## Agent Instructions
> H Platform has four products: the Agents API (managed computer-use agents, base URL https://agp.eu.hcompany.ai/api/v2 or https://agp.hcompany.ai/api/v2 for the US), the Models API (OpenAI-compatible Holo vision-language models at https://api.hcompany.ai/v1), HoloDesktop CLI (Holo on the user's own desktop), and HoloTab (a free no-code Chrome extension that runs Holo in the user's browser, with recordable routines and schedules).
> Authenticate with a bearer API key from the HAI_API_KEY environment variable. SDKs: `pip install hai-agents` (Python, `from hai_agents import Client`) and `npm install hai-agents` (TypeScript, `import { HaiAgentsClient } from "hai-agents"`). CLI: `hai`.
> Agents do work in a browser or on a desktop; describe the task as an imperative instruction. To run a task quickly, prefer the pre-built agent `h/web-surfer-flash`. Read results from the session's `latest_answer` after it reaches a terminal status.
> Sessions are the unit of work; wait for a terminal status (completed, failed, timed_out, interrupted) before reading the answer. Use webhooks or the `changes` long-poll endpoint to follow progress.

# List files

> List the files on a cloud browser's machine, such as what the agent downloaded.

Lists a directory on the machine hosting a cloud browser, newest first. Use it to see what the agent downloaded, then [read](/agents-api/sessions/read-file) a file out or [write](/agents-api/sessions/write-file) one in for the agent to use.

**Returns** the directory `path`, its `files`, and `truncated`, `true` when the listing stopped at `max_entries`.

<Note>
  The `session_id` here is the **browser session id**, not the agent session id from [`/api/v2/sessions`](/agents-api/sessions/create). Each cloud browser runs in its own browser session, and the agent publishes that id on the [events stream](/agents-api/sessions/events#event-types-type) as a `RunnerSessionEvent` (`data.runner_session_id`) when it connects. An agent session id is answered with `404`.
</Note>

Only the browser's download directory (`~/Downloads`) is reachable. Paths outside it, including the browser profile, are rejected.

***

## Path parameters

<ParamField path="session_id" type="string" required>
  The browser session id, from the session's `RunnerSessionEvent`.
</ParamField>

***

## Request body

<ParamField body="path" type="string" default="~/Downloads">
  Directory to list.
</ParamField>

<ParamField body="max_entries" type="integer" default="500">
  Maximum number of entries to return. When the directory holds more, `truncated` is `true` and the page ends at the oldest entry returned.
</ParamField>

<ParamField body="modified_before" type="string">
  Page cursor: the `modified_at` of the last entry of the previous page. Always send it together with `name_after`.
</ParamField>

<ParamField body="name_after" type="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.
</ParamField>

***

## Response

<ResponseField name="path" type="string">
  The listed directory, resolved.
</ResponseField>

<ResponseField name="files" type="array">
  Entries, newest first. Each is `{ name, path, size_bytes, modified_at, is_dir }`.
</ResponseField>

<ResponseField name="truncated" type="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.
</ResponseField>

***

## Examples

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions/$BROWSER_SESSION_ID/files/list_files \
    -H "Authorization: Bearer $HAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"path": "~/Downloads", "max_entries": 100}'
  ```

  ```python Python theme={"system"}
  from hai_agents import Client

  client = Client()

  page = client.session_files.list_files(browser_session_id, path="~/Downloads", max_entries=100)
  for entry in page.files:
      print(entry.name, entry.size_bytes, entry.modified_at)
  ```

  ```typescript TypeScript theme={"system"}
  import { HaiAgentsClient } from "hai-agents";

  const client = new HaiAgentsClient();

  const page = await client.sessionFiles.listFiles({
    sessionId: browserSessionId,
    path: "~/Downloads",
    maxEntries: 100,
  });
  for (const entry of page.files) {
    console.log(entry.name, entry.sizeBytes, entry.modifiedAt);
  }
  ```
</CodeGroup>

```json Response theme={"system"}
{
  "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's `modified_at` and `name` back as the cursor until `truncated` is `false`:

```python Python theme={"system"}
cursor = {}
while True:
    page = client.session_files.list_files(browser_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}
```