Workspaces are the recommended way to handle all file operations — uploading input files and downloading results. Prefer workspaces over session-level file uploads.
See your workspace IDs at cloud.browser-use.com/settings.
Upload a file
Upload a file to a workspace, then tell the agent to use it.
import httpx
from browser_use_sdk.v3 import AsyncBrowserUse
client = AsyncBrowserUse()
workspace = await client.workspaces.create(name="my-workspace")
# Get a presigned upload URL
upload = await client.workspaces.upload_files(
workspace.id,
files=[{"name": "people.csv", "contentType": "text/csv", "size": 45}],
)
# Upload the file
with open("people.csv", "rb") as f:
async with httpx.AsyncClient() as http:
await http.put(
upload.files[0].upload_url,
content=f.read(),
headers={"Content-Type": "text/csv", "Content-Length": "45"},
)
# Tell the agent to use it
result = await client.run(
"Read people.csv and tell me who works at Google",
workspace_id=workspace.id,
)
print(result.output)
Download files
Run a task that saves files to a workspace, then download them.
import httpx
from browser_use_sdk.v3 import AsyncBrowserUse
client = AsyncBrowserUse()
workspace = await client.workspaces.create(name="my-workspace")
# Agent saves files to the workspace
result = await client.run(
"Go to Hacker News and save the top 3 posts as posts.json",
workspace_id=workspace.id,
)
# List and download files
files = await client.workspaces.files(workspace.id, include_urls=True)
for f in files.files:
print(f"{f.path} ({f.size} bytes)")
async with httpx.AsyncClient() as http:
resp = await http.get(f.url)
with open(f.path, "wb") as out:
out.write(resp.content)
Manage workspaces
workspace = await client.workspaces.get(workspace_id)
updated = await client.workspaces.update(workspace_id, name="renamed")
workspaces = await client.workspaces.list()
await client.workspaces.delete(workspace_id)
Deleting a workspace permanently removes all its files. This cannot be undone.