A workspace stores files that can be restored into later V4 runs, including
runs in a different session. Use it for inputs, scripts, and generated files.A session holds the conversation; a workspace holds files; a profile holds
browser login state. Their IDs are different. Create and reuse workspaces
through API V4. A V3 workspace ID is not a V4 workspace ID.Workspace files are synchronized to storage between runs. This is not a live
shared filesystem between simultaneous sessions: finish one writer before
starting another run that needs its changes.
from browser_use_sdk.v4 import BrowserUseclient = BrowserUse()workspace = client.workspaces.create(name="research")client.workspaces.upload(workspace.id, "people.csv")run = client.runs.create( "Find everyone in the CSV who works at Google", workspace_id=workspace.id,)
import { BrowserUse } from "browser-use-sdk/v4";const client = new BrowserUse();const workspace = await client.workspaces.create({ name: "research",});await client.workspaces.upload( workspace.id, "people.csv",);const run = await client.runs.create({ task: "Find everyone in the CSV who works at Google", model: "gpt-5.6-luna", modelParams: { reasoning: { effort: "xhigh" } }, workspaceId: workspace.id,});
V4 restores files uploaded to that workspace under uploads/ when a run uses
its workspaceId. You do not need to repeat their IDs in attachedFileIds.Staged attachments are different: attach their IDs when creating the run.
Files attached to a session remain available to its follow-ups. An explicitly
attached staged file takes precedence over a workspace upload with the same
stored filename. For a new conversation that needs persistent files, pass the
same workspaceId; reusing a workspace does not copy conversation history.
Check GET /api/v4/workspaces/{workspace_id}/size for usedBytes and
maxBytes. The current V4 upload allowance is 950 MiB per workspace for every
account, with 50 MiB per file. It leaves room for runtime files on the agent’s
1 GiB persistent disk. An upload quota is separate from the number of
workspaces you can create, and from temporary disk used by a running agent.A 413 response means a file or workspace limit was exceeded. Remove unneeded
files, split large files, or use a fresh workspace. Do not retry an unchanged
oversized upload. Deleting a session, archiving a workspace, and deleting a
workspace are different operations; archiving is not a file-deletion request.Download a file promptly or request a fresh URL when its link expires. A
short-lived download URL does not mean the stored file expires after 60 seconds.
Was this page helpful?
⌘I
Assistant
Responses are generated using AI and may contain mistakes.