Workspaces & files

Give a V4 run input files and retrieve files the agent creates.

Every V4 run has a workspace. You can let the API create one automatically, create one yourself, or reuse an existing workspace across otherwise independent sessions.

Upload and attach input files

Uploading stores the file in the workspace and returns an upload ID. Pass that ID in attached_file_ids / attachedFileIds to make the file available to a specific run.

Python

from browser_use_sdk.v4 import AsyncBrowserUse

client = AsyncBrowserUse()
workspace = await client.workspaces.create(name="company-research")
uploaded = await client.workspaces.upload(workspace.id, "people.csv")

created = await client.runs.create(
    "Read the attached people.csv and tell me who works at Google",
    workspace_id=workspace.id,
    attached_file_ids=[uploaded[0].id],
)
run = await client.runs.wait_for_completion(created.id)
print(run.result)

You can upload up to 10 files in one helper call. A run can attach up to 20 upload IDs.

Python

uploaded = await client.workspaces.upload(
    workspace.id,
    "data.csv",
    "config.json",
    "image.png",
)

Attachments are turn-scoped. Reusing a workspace does not automatically attach every uploaded file to every later run.

Retrieve files the agent creates

Ask the agent to save its output in the workspace, then list files with temporary download URLs:

Python

created = await client.runs.create(
    "Save the top three Hacker News posts as outputs/posts.json",
    workspace_id=workspace.id,
)
await client.runs.wait_for_completion(created.id)

files = await client.workspaces.files(
    workspace.id,
    prefix="outputs/",
    include_urls=True,
)
for file in files.files:
    print(file.path, file.url)

Download URLs expire after 60 seconds, so request them immediately before downloading. Use cursor / next_cursor (nextCursor in TypeScript) to paginate large workspaces.

Reuse a workspace

• Pass neither ID to runs.create() to create a new session and workspace.
• Pass session_id / sessionId to continue the same conversation and workspace.
• Pass only workspace_id / workspaceId to start a fresh conversation with existing files.

See Upload workspace files and List workspace files for limits and response fields.