Files

Give an agent files and get its output files back. Files live on the conversation, not a workspace you manage.

The model in one sentence: each conversation has a disk. Add files and attach them to a run; the agent reads them and writes outputs to the disk; everything stays on the disk for the whole conversation.

You never create or name a “workspace” on the normal path. A run makes a disk for you, invisibly, and keeps it for the conversation. (The only time a workspace becomes visible is when you deliberately share files across different conversations — see the bottom.)

Where an agent’s answer comes back

	Short answer	Structured / large output
browser-use	result string on the run	describe the JSON shape in the task, parse result (typed output via a request schema: not available yet)
browsercode	result string on the run	a file — ask for it in the task, then fetch it (below)

Every run has a short result string. For anything bigger, browsercode writes a file, and that’s what you fetch.

Give an agent a file

Two steps: add the file, then attach its id on the run. Adding is a presigned-URL flow — request a URL, PUT your bytes to it.

Python

from browser_use import BrowserUse

client = BrowserUse()

# 1. add — SDK handles the presigned PUT for you, returns file ids
added = client.agents.browsercode.files(files=["./data.csv"])
file_ids = [f.id for f in added]

# 2. attach to a run — this is what pulls the file onto the run's disk
run = client.agents.browsercode.run(
    task="Clean data.csv: drop empty rows, save as clean.csv",
    attached_file_ids=file_ids,
)

# 1a. add a file → get an id + presigned URL
curl -s -X POST https://api.browser-use.com/api/v1/agents/browsercode/files \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"files": [{"name": "data.csv"}]}'
# → { "items": [{ "id": "up_123", "name": "data.csv", "upload_url": "https://s3..." }] }

# 1b. PUT the bytes to the returned upload_url
curl -X PUT "https://s3.../up_123?..." --upload-file ./data.csv

# 2. attach the id on the run
curl -X POST https://api.browser-use.com/api/v1/agents/browsercode/runs \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "Clean data.csv, save as clean.csv", "attached_file_ids": ["up_123"]}'

No workspace_id. Adding a file gets you an id; attaching it on a run is what makes the agent get it. Add many at once ({"files": [{"name":"a.csv"},{"name":"b.csv"}]} → many ids) and attach them all.

Attach a bad id and the run still starts (202) — the unknown ids come back in missingFileIds on the create response. Always check that array; a missing file is not an error status.

Get output files back

Files the agent wrote come back from the run’s files endpoint. Filter kind=output for what the agent produced (kind=input is what you attached).

Python

files = client.agents.browsercode.runs.files(run.id, kind="output")
for f in files:
    print(f.name, f.download_url)   # download_url is a direct link — GET it

curl "https://api.browser-use.com/api/v1/agents/browsercode/runs/RUN_ID/files?kind=output" \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY"
# → { "items": [{ "id": "out_1", "name": "clean.csv", "kind": "output", "downloadUrl": "https://..." }] }

# downloadUrl is a presigned direct link — fetch it straight (no API endpoint, no key)
curl -L "https://.../presigned-download-url" -o clean.csv

downloadUrl is a presigned, expiring link you GET directly (the Python SDK exposes it as download_url) — it points straight at storage, not at a Browser Use endpoint. If it expires, re-list to get a fresh one.

Structured output from browsercode — it’s a file

browsercode has no structured_output parameter. To get structured data, put the shape in the task and tell it where to write it, then fetch that file:

Python

run = client.agents.browsercode.run(
    task=(
        "Scrape the product catalog. Write output.json as a JSON array of "
        '{"name": str, "price": number, "url": str}.'
    ),
)
# ...poll until completed, then:
files = client.agents.browsercode.runs.files(run.id, kind="output")
out = next(f for f in files if f.name == "output.json")
# GET out.download_url for the structured JSON

curl -X POST https://api.browser-use.com/api/v1/agents/browsercode/runs \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "Scrape the catalog. Write output.json as [{\"name\":str,\"price\":number,\"url\":str}]."}'

# after it completes, fetch output.json
curl "https://api.browser-use.com/api/v1/agents/browsercode/runs/RUN_ID/files?kind=output" \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY"

browsercode’s output is always files — a CSV, a report, a chart PNG, a schema’d output.json. Name the file in the task, fetch it with ?kind=output. browser-use answers inline via the result string — describe the exact JSON shape you want in the task text and parse result (a structured_output request parameter is not available yet).

Files carry across the conversation

Attach files on the first run, then continue with session_id — later runs share the same disk, so they see everything earlier runs added or produced. To add more files mid-conversation, add them (POST /agents/{agent}/files) and attach them on your next run.

curl

# run 1 adds + uses a file
curl -X POST .../agents/browsercode/runs -d '{"task":"analyze data.csv", "attached_file_ids":["up_1"]}'
# → { "sessionId": "ses_x", ... }

# run 2 continues the thread and adds another file
curl -X POST .../agents/browsercode/files -d '{"files":[{"name":"extra.csv"}]}'   # → up_2
curl -X POST .../agents/browsercode/runs \
  -d '{"task":"now merge extra.csv", "session_id":"ses_x", "attached_file_ids":["up_2"]}'

Files share the conversation’s disk, so writing the same path twice overwrites it. If two runs both write output.json, fetch the first run’s output before the second run reuses that name.

Output files vs. browser downloads — two different things

	Where	What it is
Output files (agent wrote)	GET /agents/{agent}/runs/{id}/files?kind=output	Files the agent produced — a CSV it built, a report, output.json.
Browser-downloaded files	GET /browsers/{browser_id}/downloads	Files the browser itself downloaded off the web while navigating — a PDF it clicked, an export a site handed back.

Rule of thumb: the agent made it → output files (?kind=output); a website gave it to the browser → downloads (see Manage a browser).

Hand off from one agent to another

A common workflow: browser-use scrapes data, then browsercode processes it. They’re separate agents, so the handoff is explicit — pass the first agent’s result into the second.

The clean way: have browser-use return the data as JSON in its result (describe the shape in the task), then feed it into browsercode’s task or attach it as a file.

Python

import json

# 1. browser-use scrapes → JSON in the result string
scrape = client.agents.browser_use.run(
    task=(
        "Scrape all product names and prices from this catalog. "
        'Return ONLY a JSON object: {"products": [{"name": str, "price": number}]}'
    ),
)
data = json.loads(scrape.result)

# 2. hand it to browsercode — attach as a file, or inline it in the task
up = client.agents.browsercode.files(files=[("products.json", json.dumps(data))])
report = client.agents.browsercode.run(
    task="Read products.json, compute price stats, write report.md",
    attached_file_ids=[up[0].id],
)

# browser-use returns typed `output`; write it to a file, add it to browsercode, attach it.
# (or just paste the scraped data straight into browsercode's task text for small results)
curl -X POST .../agents/browsercode/files -d '{"files":[{"name":"products.json"}]}'   # → up_1
# PUT the scraped JSON to the upload_url, then:
curl -X POST .../agents/browsercode/runs \
  -d '{"task":"Read products.json, compute stats, write report.md", "attached_file_ids":["up_1"]}'

Two different agents don’t automatically share a disk — each conversation’s disk is its own. To move data between agents, carry the result across (inline for small data, a file for large). For a disk deliberately shared across agents/conversations, use an explicit workspace (below).

Sharing files across conversations (advanced)

Everything above keeps files on one conversation. If you want a file library reused across different conversations — or to pre-load a large dataset before your first run — create an explicit workspace:

curl

# create a named, reusable disk
curl -X POST https://api.browser-use.com/api/v1/agent-workspaces \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" -d '{"name":"shared-data"}'
# → { "id": "ws_1" }

# add files straight into it
curl -X POST https://api.browser-use.com/api/v1/agent-workspaces/ws_1/files \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" -d '{"files":[{"name":"dataset.parquet"}]}'

# point any run at it
curl -X POST .../agents/browsercode/runs -d '{"task":"analyze the dataset", "workspace_id":"ws_1"}'

This is the only time you handle a workspace_id. ~95% of usage never needs it — a conversation’s disk is automatic. Create a workspace only for cross-conversation sharing.