# Browser Use

> Hand a web task to a Browser Use cloud agent in plain English: it drives a real browser to research, fill in forms, pull data off pages, and report back. Give it files in a workspace and download what it saves, start it signed in with a browser profile, follow up in the same session to keep the browser and context, and read the agent's step-by-step trace when you need to see how it got there.

App · AI Agents · 33 actions. Web page: https://docs.lodol.com/docs/integrations/browser-use

## Actions

### Cancel follow-up message

Withdraw a follow-up message that is still waiting in the session's queue. Once the agent has picked it up it can no longer be withdrawn; cancel the run it started instead.

**Inputs**

- Session ID (`session_id`, text, required): The session (conversation) to use: the 'session_id' returned by 'Start a browser task', 'Get run' or 'List sessions'.
- Message ID (`message_id`, number, required): The 'message_id' that 'Send follow-up message' returned. At least 0.

**Outputs**

- `created_at` (text): When the message was sent (ISO 8601).
- `is_waiting` (true/false): True while the message is still pending or dispatching; once false it has either started 'run_id' or never will.
- `message_id` (number): The message's ID. Pass it to 'Get follow-up message' to find the run it starts, or to 'Cancel follow-up message'.
- `mode` (text): 'queue' (runs after the current turn) or 'interrupt' (cancels the current turn).
- `run_id` (text): The run the message started, or null until Browser Use starts it. Pass it to 'Get run status' and 'Get run'.
- `session_id` (text): The session the message was sent to.
- `status` (text): One of pending, dispatching, consumed (it started its run), cancelled, superseded, or failed.
- `text` (text): The message itself.

**Example output**

```json
{
  "created_at": "2026-07-27T18:07:02.118Z",
  "is_waiting": false,
  "message_id": 42,
  "mode": "queue",
  "run_id": null,
  "session_id": "9c0d1f77-2b53-4a6e-9d09-1c7f2a8e5b31",
  "status": "cancelled",
  "text": "Now open the top result and summarize it"
}
```

### Cancel run

Stop a run that is still in flight. A run that has already finished is returned unchanged. The run's browser stays up for follow-ups; stop it with 'Stop browser' if you are done.

**Inputs**

- Run ID (`run_id`, text, required): The ID of the Browser Use run (the 'id' returned by 'Start a browser task' or 'List runs').

**Outputs**: The run as it stands after the cancellation.

- `attached_file_ids` (list): IDs of files attached to the run.
- `context_limit` (number): Context window the run was given, in tokens.
- `created_at` (text): When the run was created (ISO 8601).
- `error` (text): Why the run failed, or null if it did not fail.
- `id` (text): The run's ID.
- `is_terminal` (true/false): True once the run is finished (completed, failed, or cancelled).
- `judgement` (object): The LLM judge's verdict when judging was requested, otherwise null (it stays null until the judge finishes).
- `model` (text): Model that ran the task.
- `result` (text): What the agent reported back. Null until the run completes.
- `session_id` (text): ID of the session (conversation) the run belongs to. Pass it to 'Send follow-up message' or to a later run to continue.
- `status` (text): One of queued, dispatching, running, completed, failed, or cancelled.
- `task` (text): The instruction the agent was given.
- `title` (text): Short title Browser Use generated for the run, or null.
- `total_cost_usd` (text): What the run's model and web searches cost, in US dollars. Browser time is billed to the session: see 'Get session cost'.
- `total_input_tokens` (number): Input tokens the run consumed.
- `total_output_tokens` (number): Output tokens the run produced.
- `updated_at` (text): When the run was last updated (ISO 8601).
- `workspace_id` (text): ID of the workspace the run's files live in. Pass it to 'List workspace files' to see what the agent saved.

**Example output**

```json
{
  "attached_file_ids": [],
  "context_limit": 200000,
  "created_at": "2026-07-27T18:04:11.512Z",
  "error": null,
  "id": "3f1c8a52-6f47-4f1a-9d2f-27b0c5d9a1e4",
  "is_terminal": true,
  "judgement": null,
  "model": "gpt-6-luna",
  "result": null,
  "session_id": "9c0d1f77-2b53-4a6e-9d09-1c7f2a8e5b31",
  "status": "cancelled",
  "task": "Find the top 3 trending repos on GitHub today",
  "title": "GitHub trending repos",
  "total_cost_usd": "0.0421",
  "total_input_tokens": 48213,
  "total_output_tokens": 3120,
  "updated_at": "2026-07-27T18:06:48.902Z",
  "workspace_id": "51b0f8a3-9a3d-4f7c-bb2e-6e1d0c4a9f22"
}
```

### Create profile

Create a browser profile, which keeps cookies and logins between runs. Sign in once, with a run or by hand in the live view of 'Start a browser', then start later runs with the profile to skip the login.

**Inputs**

- Name (`name`, text): A name to recognize the profile by, such as 'Acme admin login'.
- Your user ID (`external_user_id`, text): Your own identifier for whoever the profile belongs to, so you can find it again with 'List profiles' (Browser Use recommends one profile per end user).

**Outputs**

- `cookie_domains` (list): Sites the profile holds cookies (logins) for.
- `created_at` (text): When the profile was created (ISO 8601).
- `external_user_id` (text): Your own user identifier for the profile, or null.
- `id` (text): The profile's ID. Pass it as 'Browser profile ID' to start a browser that is already signed in.
- `last_used_at` (text): When a browser last used the profile (ISO 8601).
- `name` (text): The profile's name, or null.
- `updated_at` (text): When the profile was last updated (ISO 8601).

**Example output**

```json
{
  "cookie_domains": [],
  "created_at": "2026-07-20T09:15:00.000Z",
  "external_user_id": "customer-1042",
  "id": "b7e4c1d2-8a90-4f3e-9c55-0d2f6a1e7b34",
  "last_used_at": null,
  "name": "Acme admin login",
  "updated_at": "2026-07-27T18:06:49.000Z"
}
```

### Create workspace

Create an empty workspace: a place for files that outlasts any one run. Upload input files to it, pass its ID to 'Start a browser task', and download what the agent saves there.

**Inputs**

- Name (`name`, text): A name to recognize the workspace by.

**Outputs**

- `archived` (true/false): Whether the workspace has been deleted (archived).
- `created_at` (text): When the workspace was created (ISO 8601).
- `id` (text): The workspace's ID. Pass it as 'Workspace ID' to 'Start a browser task' and the file actions.
- `name` (text): The workspace's name, or null.
- `updated_at` (text): When the workspace was last updated (ISO 8601).

**Example output**

```json
{
  "archived": false,
  "created_at": "2026-07-27T17:58:00.000Z",
  "id": "51b0f8a3-9a3d-4f7c-bb2e-6e1d0c4a9f22",
  "name": "Lead research",
  "updated_at": "2026-07-27T17:58:00.000Z"
}
```

### Delete profile

Permanently delete a browser profile and the cookies and logins it holds. Browsers already running with it are not affected.

**Inputs**

- Profile ID (`profile_id`, text, required): The browser profile's ID, from 'List profiles' or 'Create profile'.

**Outputs**

- `deleted` (true/false): Always true once it is deleted.
- `profile_id` (text): The profile that was deleted.

**Example output**

```json
{
  "deleted": true,
  "profile_id": "b7e4c1d2-8a90-4f3e-9c55-0d2f6a1e7b34"
}
```

### Delete session

Delete a session so it can no longer be opened or continued. A run still in progress is cancelled first, and waiting follow-up messages are dropped.

**Inputs**

- Session ID (`session_id`, text, required): The session (conversation) to use: the 'session_id' returned by 'Start a browser task', 'Get run' or 'List sessions'.

**Outputs**

- `deleted` (true/false): Always true once it is deleted.
- `session_id` (text): The session that was deleted.

**Example output**

```json
{
  "deleted": true,
  "session_id": "9c0d1f77-2b53-4a6e-9d09-1c7f2a8e5b31"
}
```

### Delete workspace

Delete (archive) a workspace so runs can no longer use it. Deleting one that is already gone does nothing.

**Inputs**

- Workspace ID (`workspace_id`, text, required): The workspace holding the files: the 'workspace_id' a run returns, or the 'id' from 'Create workspace'.

**Outputs**

- `deleted` (true/false): Always true once it is deleted.
- `workspace_id` (text): The workspace that was deleted.

**Example output**

```json
{
  "deleted": true,
  "workspace_id": "51b0f8a3-9a3d-4f7c-bb2e-6e1d0c4a9f22"
}
```

### Delete workspace file

Delete one file from a workspace.

**Inputs**

- Workspace ID (`workspace_id`, text, required): The workspace holding the files: the 'workspace_id' a run returns, or the 'id' from 'Create workspace'.
- File path (`path`, text, required): The file's path in the workspace, as 'List workspace files' shows it, such as 'uploads/leads.csv'.

**Outputs**

- `deleted` (true/false): Always true once it is deleted.
- `path` (text): The path that was deleted.
- `workspace_id` (text): The workspace the file was in.

**Example output**

```json
{
  "deleted": true,
  "path": "uploads/brief.pdf",
  "workspace_id": "51b0f8a3-9a3d-4f7c-bb2e-6e1d0c4a9f22"
}
```

### Download workspace file

Save a file from a workspace, such as a report or spreadsheet the agent made, so later steps can email it, upload it elsewhere, or read it. Up to 100 MB.

**Inputs**

- Workspace ID (`workspace_id`, text, required): The workspace holding the files: the 'workspace_id' a run returns, or the 'id' from 'Create workspace'.
- File path (`path`, text, required): The file's path in the workspace, as 'List workspace files' shows it, such as 'desks.csv'.
- Save as (`filename`, text): The name to save the file under. Leave blank to keep its own name.

**Outputs**

- `content_type` (text): The file's MIME type.
- `document_ref` (text): Reference to the saved file, for steps that take a file (email it, upload it elsewhere, and so on).
- `documents` (list): The saved file, as a one-item list of documents.
- `filename` (text): The saved file's name.
- `path` (text): Where the file was in the workspace.
- `size_bytes` (number): The file's size in bytes.
- `url` (text): Link to view the saved file.
- `workspace_id` (text): The workspace the file came from.

**Example output**

```json
{
  "content_type": "text/csv",
  "document_ref": "doc_7f3a9c21e4b84d0f9a6c3e1b5d2f8a47",
  "documents": [
    {
      "content_type": "text/csv",
      "document_ref": "doc_7f3a9c21e4b84d0f9a6c3e1b5d2f8a47",
      "filename": "desks.csv",
      "size_bytes": 1832,
      "url": "/actions/core/serve-document/doc_7f3a9c21e4b84d0f9a6c3e1b5d2f8a47"
    }
  ],
  "filename": "desks.csv",
  "path": "desks.csv",
  "size_bytes": 1832,
  "url": "/actions/core/serve-document/doc_7f3a9c21e4b84d0f9a6c3e1b5d2f8a47",
  "workspace_id": "51b0f8a3-9a3d-4f7c-bb2e-6e1d0c4a9f22"
}
```

### Get account

Read your Browser Use credit balance and how many browsers are running against the project's limit, for example to alert before credits run out.

**Inputs**: None.

**Outputs**

- `active_browser_count` (number): How many browsers are running now.
- `additional_credits_usd` (number): Of which top-up credits.
- `concurrent_browser_limit` (number): How many browsers may run at once.
- `is_free_tier` (true/false): Whether the account is on the free tier.
- `monthly_credits_usd` (number): Of which monthly plan credits.
- `name` (text): The account's name.
- `plan_name` (text): The plan's name, or null when there is none (pay as you go, or the free plan).
- `project_id` (text): The project the API key belongs to.
- `subscription_status` (text): The subscription's status, or null.
- `total_credits_usd` (number): Credits left, in US dollars.

**Example output**

```json
{
  "active_browser_count": 2,
  "additional_credits_usd": 48.75,
  "concurrent_browser_limit": 50,
  "is_free_tier": false,
  "monthly_credits_usd": 0,
  "name": "Acme Ops",
  "plan_name": null,
  "project_id": "proj_4f2a9c",
  "subscription_status": null,
  "total_credits_usd": 48.75
}
```

### Get browser

Fetch a cloud browser: whether it is running, its live view link, what it has cost, and once a recorded browser has stopped, its recording.

**Inputs**

- Browser ID (`browser_id`, text, required): The cloud browser's ID, from 'List browsers' (filter it by a run's session to find the browser that run used) or 'Start a browser'.

**Outputs**

- `agent_session_id` (text): The agent session that started the browser, or null for one started with 'Start a browser'.
- `browser_cost_usd` (text): What the browser's running time cost, in US dollars.
- `cdp_url` (text): Chrome DevTools Protocol URL, for automation tools.
- `finished_at` (text): When the browser stopped (ISO 8601), or null.
- `id` (text): The browser's ID.
- `is_active` (true/false): True while the browser is running (and billing).
- `live_url` (text): Link to watch and control the browser live. Treat it like a password: anyone with it can use the browser.
- `proxy_cost_usd` (text): What its proxy traffic cost, in US dollars.
- `proxy_used_mb` (text): Proxy traffic used, in megabytes.
- `recording_available` (true/false): False when no recording will ever appear (recording was off). Null in lists.
- `recording_url` (text): Download link for the recording, once a recorded browser has stopped and the video is processed. Only 'Get browser' fills it in.
- `started_at` (text): When the browser started (ISO 8601).
- `status` (text): Either 'active' or 'stopped'.
- `timeout_at` (text): When the browser stops on its own (ISO 8601).

**Example output**

```json
{
  "agent_session_id": null,
  "browser_cost_usd": "0.02",
  "cdp_url": "wss://cdp.browser-use.com/e2a8f0c4",
  "finished_at": "2026-07-27T18:25:00.000Z",
  "id": "e2a8f0c4-51d7-4b6e-8f19-7c3a9d0b2e65",
  "is_active": false,
  "live_url": null,
  "proxy_cost_usd": "0",
  "proxy_used_mb": "0",
  "recording_available": true,
  "recording_url": "https://recordings.browser-use.com/e2a8f0c4.mp4?signature=abc",
  "started_at": "2026-07-27T18:10:00.000Z",
  "status": "stopped",
  "timeout_at": "2026-07-27T19:10:00.000Z"
}
```

### Get follow-up message

Check on a follow-up message: whether it is still waiting, and once Browser Use starts it, the ID of the run it became. Poll this while 'is_waiting' is true, then follow 'run_id' with 'Get run status'.

**Inputs**

- Session ID (`session_id`, text, required): The session (conversation) to use: the 'session_id' returned by 'Start a browser task', 'Get run' or 'List sessions'.
- Message ID (`message_id`, number, required): The 'message_id' that 'Send follow-up message' returned. At least 0.

**Outputs**

- `created_at` (text): When the message was sent (ISO 8601).
- `is_waiting` (true/false): True while the message is still pending or dispatching; once false it has either started 'run_id' or never will.
- `message_id` (number): The message's ID. Pass it to 'Get follow-up message' to find the run it starts, or to 'Cancel follow-up message'.
- `mode` (text): 'queue' (runs after the current turn) or 'interrupt' (cancels the current turn).
- `run_id` (text): The run the message started, or null until Browser Use starts it. Pass it to 'Get run status' and 'Get run'.
- `session_id` (text): The session the message was sent to.
- `status` (text): One of pending, dispatching, consumed (it started its run), cancelled, superseded, or failed.
- `text` (text): The message itself.

**Example output**

```json
{
  "created_at": "2026-07-27T18:07:02.118Z",
  "is_waiting": false,
  "message_id": 42,
  "mode": "queue",
  "run_id": "6d2b7e90-3c1a-4f58-b0e2-91a4c7d3f816",
  "session_id": "9c0d1f77-2b53-4a6e-9d09-1c7f2a8e5b31",
  "status": "consumed",
  "text": "Now open the top result and summarize it"
}
```

### Get profile

Fetch a browser profile, including the sites it holds cookies for, which shows which logins it has saved.

**Inputs**

- Profile ID (`profile_id`, text, required): The browser profile's ID, from 'List profiles' or 'Create profile'.

**Outputs**

- `cookie_domains` (list): Sites the profile holds cookies (logins) for.
- `created_at` (text): When the profile was created (ISO 8601).
- `external_user_id` (text): Your own user identifier for the profile, or null.
- `id` (text): The profile's ID. Pass it as 'Browser profile ID' to start a browser that is already signed in.
- `last_used_at` (text): When a browser last used the profile (ISO 8601).
- `name` (text): The profile's name, or null.
- `updated_at` (text): When the profile was last updated (ISO 8601).

**Example output**

```json
{
  "cookie_domains": [
    "acme.example.com"
  ],
  "created_at": "2026-07-20T09:15:00.000Z",
  "external_user_id": "customer-1042",
  "id": "b7e4c1d2-8a90-4f3e-9c55-0d2f6a1e7b34",
  "last_used_at": "2026-07-27T18:04:12.000Z",
  "name": "Acme admin login",
  "updated_at": "2026-07-27T18:06:49.000Z"
}
```

### Get run

Fetch a Browser Use run by ID, including the agent's result, why it failed if it did, what it cost, and how many tokens it used. Use this once 'Get run status' reports the run has finished.

**Inputs**

- Run ID (`run_id`, text, required): The ID of the Browser Use run (the 'id' returned by 'Start a browser task' or 'List runs').

**Outputs**: The run and its result.

- `attached_file_ids` (list): IDs of files attached to the run.
- `context_limit` (number): Context window the run was given, in tokens.
- `created_at` (text): When the run was created (ISO 8601).
- `error` (text): Why the run failed, or null if it did not fail.
- `id` (text): The run's ID.
- `is_terminal` (true/false): True once the run is finished (completed, failed, or cancelled).
- `judgement` (object): The LLM judge's verdict when judging was requested, otherwise null (it stays null until the judge finishes).
- `model` (text): Model that ran the task.
- `result` (text): What the agent reported back. Null until the run completes.
- `session_id` (text): ID of the session (conversation) the run belongs to. Pass it to 'Send follow-up message' or to a later run to continue.
- `status` (text): One of queued, dispatching, running, completed, failed, or cancelled.
- `task` (text): The instruction the agent was given.
- `title` (text): Short title Browser Use generated for the run, or null.
- `total_cost_usd` (text): What the run's model and web searches cost, in US dollars. Browser time is billed to the session: see 'Get session cost'.
- `total_input_tokens` (number): Input tokens the run consumed.
- `total_output_tokens` (number): Output tokens the run produced.
- `updated_at` (text): When the run was last updated (ISO 8601).
- `workspace_id` (text): ID of the workspace the run's files live in. Pass it to 'List workspace files' to see what the agent saved.

**Example output**

```json
{
  "attached_file_ids": [],
  "context_limit": 200000,
  "created_at": "2026-07-27T18:04:11.512Z",
  "error": null,
  "id": "3f1c8a52-6f47-4f1a-9d2f-27b0c5d9a1e4",
  "is_terminal": true,
  "judgement": null,
  "model": "gpt-6-luna",
  "result": "The top 3 trending repositories today are browser-use/browser-use, openai/whisper, and vercel/next.js.",
  "session_id": "9c0d1f77-2b53-4a6e-9d09-1c7f2a8e5b31",
  "status": "completed",
  "task": "Find the top 3 trending repos on GitHub today",
  "title": "GitHub trending repos",
  "total_cost_usd": "0.0421",
  "total_input_tokens": 48213,
  "total_output_tokens": 3120,
  "updated_at": "2026-07-27T18:06:48.902Z",
  "workspace_id": "51b0f8a3-9a3d-4f7c-bb2e-6e1d0c4a9f22"
}
```

### Get run events

Read a run's event log: the agent's step-by-step trace of what it did in the browser. Useful for debugging a run that failed or went the wrong way, and the 'browser.ready' event carries the live view link a person can use to step in.

**Inputs**

- Run ID (`run_id`, text, required): The ID of the Browser Use run (the 'id' returned by 'Start a browser task' or 'List runs').
- Limit (`limit`, number): Maximum number of events to return (default 200). At least 1. Default: `200`.
- After event ID (`after`, number): Only return events newer than this event ID; pass the 'next_after' from a previous call to get just the new ones. Leave blank to start from the beginning. At least 0.
- Include tool output (`include_output`, true/false): Include what each of the agent's tools returned. Turn off for a much smaller trace of just the steps. Default: `true`.

**Outputs**

- `events` (list): The run's events, oldest first.
- `has_more` (true/false): Whether more events are available.
- `next_after` (number): Pass this back as 'after' to fetch only newer events, or null when there are none.

**Example output**

```json
{
  "events": [
    {
      "data": {
        "live_view_url": "https://live.browser-use.com/session/e2a8f0c4"
      },
      "id": 1,
      "run_id": "3f1c8a52-6f47-4f1a-9d2f-27b0c5d9a1e4",
      "timestamp": "2026-07-27T18:04:13.108Z",
      "type": "browser.ready"
    },
    {
      "data": {
        "action": "go_to_url",
        "url": "https://github.com"
      },
      "id": 2,
      "run_id": "3f1c8a52-6f47-4f1a-9d2f-27b0c5d9a1e4",
      "timestamp": "2026-07-27T18:04:26.774Z",
      "type": "step"
    }
  ],
  "has_more": false,
  "next_after": 2
}
```

### Get run status

Check just the status of a run: the cheap endpoint to poll while an agent works. Returns 'is_terminal' as true once the run has finished (completed, failed, or cancelled), which is the signal to stop waiting and call 'Get run'.

**Inputs**

- Run ID (`run_id`, text, required): The ID of the Browser Use run (the 'id' returned by 'Start a browser task' or 'List runs').

**Outputs**

- `id` (text): The run's ID.
- `is_terminal` (true/false): True once the run is finished (completed, failed, or cancelled).
- `status` (text): One of queued, dispatching, running, completed, failed, or cancelled.

**Example output**

```json
{
  "id": "3f1c8a52-6f47-4f1a-9d2f-27b0c5d9a1e4",
  "is_terminal": false,
  "status": "running"
}
```

### Get session

Fetch a session and its latest run's status. A cheap way to wait on a conversation: 'is_terminal' turns true once the latest run, a follow-up's included, has finished.

**Inputs**

- Session ID (`session_id`, text, required): The session (conversation) to use: the 'session_id' returned by 'Start a browser task', 'Get run' or 'List sessions'.

**Outputs**

- `created_at` (text): When the latest run was created (ISO 8601).
- `is_terminal` (true/false): True once the latest run has finished, so the session is idle.
- `latest_run_id` (text): ID of the session's most recent run.
- `session_id` (text): The session's ID.
- `status` (text): The latest run's status: queued, dispatching, running, completed, failed, or cancelled.
- `task` (text): The instruction the latest run was given.
- `title` (text): The session's title, or null if it has none.
- `updated_at` (text): When the latest run was last updated (ISO 8601).
- `workspace_id` (text): ID of the workspace the session's files live in.

**Example output**

```json
{
  "created_at": "2026-07-27T18:04:11.512Z",
  "is_terminal": true,
  "latest_run_id": "3f1c8a52-6f47-4f1a-9d2f-27b0c5d9a1e4",
  "session_id": "9c0d1f77-2b53-4a6e-9d09-1c7f2a8e5b31",
  "status": "completed",
  "task": "Find the top 3 trending repos on GitHub today",
  "title": "GitHub trending repos",
  "updated_at": "2026-07-27T18:06:48.902Z",
  "workspace_id": "51b0f8a3-9a3d-4f7c-bb2e-6e1d0c4a9f22"
}
```

### Get session cost

Everything a session has cost so far, split into model, web search, browser time and proxy traffic. A run's own cost only covers the model and search, so this is the full figure.

**Inputs**

- Session ID (`session_id`, text, required): The session (conversation) to use: the 'session_id' returned by 'Start a browser task', 'Get run' or 'List sessions'.

**Outputs**: Recorded usage in US dollars, before any credits.

- `browser_cost_usd` (text): What the browser's running time cost.
- `llm_cost_usd` (text): What the model calls cost.
- `proxy_cost_usd` (text): What proxy traffic cost.
- `proxy_used_mb` (text): Proxy traffic used, in megabytes.
- `run_count` (number): How many runs the session has had.
- `search_cost_usd` (text): What web searches cost.
- `session_id` (text): The session.
- `total_cost_usd` (text): All of the above together.

**Example output**

```json
{
  "browser_cost_usd": "0.0011",
  "llm_cost_usd": "0.0421",
  "proxy_cost_usd": "0.0120",
  "proxy_used_mb": "2.4",
  "run_count": 2,
  "search_cost_usd": "0.0000",
  "session_id": "9c0d1f77-2b53-4a6e-9d09-1c7f2a8e5b31",
  "total_cost_usd": "0.0552"
}
```

### List browsers

List your cloud browsers, newest first. Filter by a run's session to find the browser it used (a finished run leaves its browser running for follow-ups), or by status to find active ones still billing.

**Inputs**

- Status (`status`, text): Only browsers in this state. Leave blank for all. One of: `active`, `stopped`.
- Session ID (`agent_session_id`, text): Only the browser of this agent session (a run's 'session_id'). Leave blank for all browsers.
- Page size (`page_size`, number): How many to return per page (1-100, default 10). From 1 to 100.
- Page number (`page_number`, number): Which page to return, starting at 1. At least 1.

**Outputs**

- `browsers` (list): The browsers on this page.
- `page_number` (number): The page returned.
- `page_size` (number): Browsers per page.
- `total` (number): How many browsers match in all.

**Example output**

```json
{
  "browsers": [
    {
      "agent_session_id": "9c0d1f77-2b53-4a6e-9d09-1c7f2a8e5b31",
      "browser_cost_usd": "0.02",
      "cdp_url": "wss://cdp.browser-use.com/e2a8f0c4",
      "finished_at": null,
      "id": "e2a8f0c4-51d7-4b6e-8f19-7c3a9d0b2e65",
      "is_active": true,
      "live_url": "https://live.browser-use.com/session/e2a8f0c4",
      "proxy_cost_usd": "0",
      "proxy_used_mb": "0",
      "recording_available": null,
      "recording_url": null,
      "started_at": "2026-07-27T18:10:00.000Z",
      "status": "active",
      "timeout_at": "2026-07-27T19:10:00.000Z"
    }
  ],
  "page_number": 1,
  "page_size": 10,
  "total": 1
}
```

### List profiles

List your browser profiles: saved cookies and logins a run or browser can start with. Search by name or your user ID.

**Inputs**

- Search (`query`, text): Only profiles whose name or user ID matches this. Leave blank for all.
- Page size (`page_size`, number): How many to return per page (1-100, default 10). From 1 to 100.
- Page number (`page_number`, number): Which page to return, starting at 1. At least 1.

**Outputs**

- `page_number` (number): The page returned.
- `page_size` (number): Profiles per page.
- `profiles` (list): The profiles on this page.
- `total` (number): How many profiles match in all.

**Example output**

```json
{
  "page_number": 1,
  "page_size": 10,
  "profiles": [
    {
      "cookie_domains": [
        "acme.example.com"
      ],
      "created_at": "2026-07-20T09:15:00.000Z",
      "external_user_id": "customer-1042",
      "id": "b7e4c1d2-8a90-4f3e-9c55-0d2f6a1e7b34",
      "last_used_at": "2026-07-27T18:04:12.000Z",
      "name": "Acme admin login",
      "updated_at": "2026-07-27T18:06:49.000Z"
    }
  ],
  "total": 1
}
```

### List run attachments

List the files attached to a run, with their names, types, and sizes.

**Inputs**

- Run ID (`run_id`, text, required): The ID of the Browser Use run (the 'id' returned by 'Start a browser task' or 'List runs').

**Outputs**

- `attachments` (list): The files attached to the run.

**Example output**

```json
{
  "attachments": [
    {
      "content_type": "text/csv",
      "id": "7a2f9d61-0b48-4f5c-8f0a-3d6e5b1c7a90",
      "name": "trending.csv",
      "size_bytes": 2048,
      "status": "uploaded"
    }
  ]
}
```

### List runs

List your Browser Use runs, newest first, optionally only the runs belonging to one session.

**Inputs**

- Limit (`limit`, number): Maximum number of runs to return per page (default 50). At least 1. Default: `50`.
- Continue from cursor (`cursor`, text): For pagination: the 'next_cursor' from the previous page. Leave blank for the first page.
- Session ID (`session_id`, text): Only return runs from this session. Leave blank for all runs.

**Outputs**

- `has_more` (true/false): Whether another page of runs is available.
- `next_cursor` (text): Cursor for the next page, or null when there are no more runs.
- `runs` (list): The runs, newest first.

**Example output**

```json
{
  "has_more": false,
  "next_cursor": null,
  "runs": [
    {
      "attached_file_ids": [],
      "context_limit": 200000,
      "created_at": "2026-07-27T18:04:11.512Z",
      "error": null,
      "id": "3f1c8a52-6f47-4f1a-9d2f-27b0c5d9a1e4",
      "is_terminal": true,
      "judgement": null,
      "model": "gpt-6-luna",
      "result": "The top 3 trending repositories today are browser-use/browser-use, openai/whisper, and vercel/next.js.",
      "session_id": "9c0d1f77-2b53-4a6e-9d09-1c7f2a8e5b31",
      "status": "completed",
      "task": "Find the top 3 trending repos on GitHub today",
      "title": "GitHub trending repos",
      "total_cost_usd": "0.0421",
      "total_input_tokens": 48213,
      "total_output_tokens": 3120,
      "updated_at": "2026-07-27T18:06:48.902Z",
      "workspace_id": "51b0f8a3-9a3d-4f7c-bb2e-6e1d0c4a9f22"
    }
  ]
}
```

### List sessions

List your Browser Use sessions (conversations), most recent first: one row per session, showing its latest run.

**Inputs**

- Limit (`limit`, number): How many sessions to return per page (1-100). From 1 to 100. Default: `20`.
- Continue from cursor (`cursor`, text): For pagination: the 'next_cursor' from the previous page. Leave blank for the first page.

**Outputs**

- `has_more` (true/false): Whether another page is available.
- `next_cursor` (text): Cursor for the next page, or null when there are no more sessions.
- `sessions` (list): The sessions, most recent first.

**Example output**

```json
{
  "has_more": false,
  "next_cursor": null,
  "sessions": [
    {
      "created_at": "2026-07-27T18:04:11.512Z",
      "is_terminal": true,
      "latest_run_id": "3f1c8a52-6f47-4f1a-9d2f-27b0c5d9a1e4",
      "session_id": "9c0d1f77-2b53-4a6e-9d09-1c7f2a8e5b31",
      "status": "completed",
      "task": "Find the top 3 trending repos on GitHub today",
      "title": "GitHub trending repos",
      "updated_at": "2026-07-27T18:06:48.902Z",
      "workspace_id": "51b0f8a3-9a3d-4f7c-bb2e-6e1d0c4a9f22"
    }
  ]
}
```

### List workspace files

List the files in a workspace: those you uploaded (under 'uploads/') and those the agent saved. Wait for a run to finish before listing what it made.

**Inputs**

- Workspace ID (`workspace_id`, text, required): The workspace holding the files: the 'workspace_id' a run returns, or the 'id' from 'Create workspace'.
- Path starts with (`prefix`, text): Only list files whose path starts with this, such as 'uploads/' or 'reports/'. Leave blank for every file.
- Limit (`limit`, number): How many files to return per page (1-100). From 1 to 100. Default: `50`.
- Continue from cursor (`cursor`, text): For pagination: the 'next_cursor' from the previous page. Leave blank for the first page.

**Outputs**

- `files` (list): The files.
- `has_more` (true/false): Whether another page is available.
- `next_cursor` (text): Cursor for the next page, or null when there are no more files.
- `workspace_id` (text): The workspace that was listed.

**Example output**

```json
{
  "files": [
    {
      "last_modified": "2026-07-27T18:06:40.000Z",
      "path": "desks.csv",
      "size_bytes": 1832
    },
    {
      "last_modified": "2026-07-27T17:59:12.000Z",
      "path": "uploads/brief.pdf",
      "size_bytes": 48211
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "workspace_id": "51b0f8a3-9a3d-4f7c-bb2e-6e1d0c4a9f22"
}
```

### Rename session

Give a session a title of your own.

**Inputs**

- Session ID (`session_id`, text, required): The session (conversation) to use: the 'session_id' returned by 'Start a browser task', 'Get run' or 'List sessions'.
- Title (`title`, text, required): The session's new title (up to 255 characters).

**Outputs**

- `created_at` (text): When the latest run was created (ISO 8601).
- `is_terminal` (true/false): True once the latest run has finished, so the session is idle.
- `latest_run_id` (text): ID of the session's most recent run.
- `session_id` (text): The session's ID.
- `status` (text): The latest run's status: queued, dispatching, running, completed, failed, or cancelled.
- `task` (text): The instruction the latest run was given.
- `title` (text): The session's title, or null if it has none.
- `updated_at` (text): When the latest run was last updated (ISO 8601).
- `workspace_id` (text): ID of the workspace the session's files live in.

**Example output**

```json
{
  "created_at": "2026-07-27T18:04:11.512Z",
  "is_terminal": true,
  "latest_run_id": "3f1c8a52-6f47-4f1a-9d2f-27b0c5d9a1e4",
  "session_id": "9c0d1f77-2b53-4a6e-9d09-1c7f2a8e5b31",
  "status": "completed",
  "task": "Find the top 3 trending repos on GitHub today",
  "title": "Weekly GitHub trends",
  "updated_at": "2026-07-27T18:06:48.902Z",
  "workspace_id": "51b0f8a3-9a3d-4f7c-bb2e-6e1d0c4a9f22"
}
```

### Send follow-up message

Send another instruction to a session the agent is already working in; it runs as the next turn, keeping the same browser and conversation. Optionally interrupt the current run instead of queueing behind it. This returns the queued message, not a run: poll 'Get follow-up message' with its 'message_id' until it names the run it started.

**Inputs**

- Session ID (`session_id`, text, required): The session to message (the 'session_id' returned by 'Start a browser task').
- Message (`text`, text, required): What the agent should do next, for example 'Now open the top result and summarize it.'
- Interrupt the current run (`interrupt`, true/false): Run this message right away, cancelling the agent's current turn, instead of waiting for it to finish. Default: `false`.

**Outputs**

- `created_at` (text): When the message was sent (ISO 8601).
- `interrupt` (true/false): Whether the message interrupted the current turn.
- `is_waiting` (true/false): True while the message is still pending or dispatching; once false it has either started 'run_id' or never will.
- `message_id` (number): The message's ID. Pass it to 'Get follow-up message' to find the run it starts, or to 'Cancel follow-up message'.
- `mode` (text): 'queue' (runs after the current turn) or 'interrupt' (cancels the current turn).
- `queued` (true/false): Always true once the message is accepted.
- `response` (object): The queued message as Browser Use returned it.
- `run_id` (text): The run the message started, or null until Browser Use starts it. Pass it to 'Get run status' and 'Get run'.
- `session_id` (text): The session the message was sent to.
- `status` (text): One of pending, dispatching, consumed (it started its run), cancelled, superseded, or failed.
- `text` (text): The message itself.

**Example output**

```json
{
  "created_at": "2026-07-27T18:07:02.118Z",
  "interrupt": false,
  "is_waiting": true,
  "message_id": 42,
  "mode": "queue",
  "queued": true,
  "response": {
    "createdAt": "2026-07-27T18:07:02.118Z",
    "id": 42,
    "mode": "queue",
    "runId": null,
    "sessionId": "9c0d1f77-2b53-4a6e-9d09-1c7f2a8e5b31",
    "status": "pending",
    "text": "Now open the top result and summarize it"
  },
  "run_id": null,
  "session_id": "9c0d1f77-2b53-4a6e-9d09-1c7f2a8e5b31",
  "status": "pending",
  "text": "Now open the top result and summarize it"
}
```

### Share session

Turn on a public link to a session so anyone with it can watch what the agent did. Sharing a session again returns the same link.

**Inputs**

- Session ID (`session_id`, text, required): The session (conversation) to use: the 'session_id' returned by 'Start a browser task', 'Get run' or 'List sessions'.

**Outputs**

- `created_at` (text): When the session was first shared (ISO 8601).
- `is_active` (true/false): Whether the link currently works.
- `session_id` (text): The shared session's ID.
- `share_token` (text): The token at the end of the link.
- `share_url` (text): Public link anyone can open to view the session.
- `view_count` (number): How many times the link has been opened.

**Example output**

```json
{
  "created_at": "2026-07-27T18:08:30.004Z",
  "is_active": true,
  "session_id": "9c0d1f77-2b53-4a6e-9d09-1c7f2a8e5b31",
  "share_token": "k3Zp9QvT",
  "share_url": "https://cloud.browser-use.com/share/k3Zp9QvT",
  "view_count": 0
}
```

### Start a browser

Start a cloud browser with no agent, and get a live view link a person can open to use it, for example to sign in to a site so a profile keeps the login. Billed by the hour from the start (unused time is refunded): stop it with 'Stop browser' when done.

**Inputs**

- Browser profile ID (`profile_id`, text): ID of a Browser Use browser profile to load, so the browser starts with its saved cookies and logins. Leave blank for a clean browser.
- Proxy country (`proxy_country_code`, text): Two-letter ISO country code to route the browser through, such as 'us', 'de', or 'jp'. Defaults to the United States. Enter 'none' to run without a proxy.
- Stop after (minutes) (`timeout_minutes`, number): Stop the browser on its own after this many minutes (1-240). From 1 to 240. Default: `60`.
- Screen width (px) (`screen_width`, number): Browser window width in pixels (320-6144). Leave blank for the default. From 320 to 6144.
- Screen height (px) (`screen_height`, number): Browser window height in pixels (320-3456). Leave blank for the default. From 320 to 3456.
- Record the browser (`record`, true/false): Record the browser to a video, which 'Get browser' links to once it has stopped. Default: `false`.
- Solve CAPTCHAs (`solve_captchas`, true/false): Let the browser detect and solve CAPTCHAs on its own. Turn off to handle them yourself. Default: `true`.

**Outputs**

- `agent_session_id` (text): The agent session that started the browser, or null for one started with 'Start a browser'.
- `browser_cost_usd` (text): What the browser's running time cost, in US dollars.
- `cdp_url` (text): Chrome DevTools Protocol URL, for automation tools.
- `finished_at` (text): When the browser stopped (ISO 8601), or null.
- `id` (text): The browser's ID.
- `is_active` (true/false): True while the browser is running (and billing).
- `live_url` (text): Link to watch and control the browser live. Treat it like a password: anyone with it can use the browser.
- `proxy_cost_usd` (text): What its proxy traffic cost, in US dollars.
- `proxy_used_mb` (text): Proxy traffic used, in megabytes.
- `recording_available` (true/false): False when no recording will ever appear (recording was off). Null in lists.
- `recording_url` (text): Download link for the recording, once a recorded browser has stopped and the video is processed. Only 'Get browser' fills it in.
- `started_at` (text): When the browser started (ISO 8601).
- `status` (text): Either 'active' or 'stopped'.
- `timeout_at` (text): When the browser stops on its own (ISO 8601).

**Example output**

```json
{
  "agent_session_id": null,
  "browser_cost_usd": "0.02",
  "cdp_url": "wss://cdp.browser-use.com/e2a8f0c4",
  "finished_at": null,
  "id": "e2a8f0c4-51d7-4b6e-8f19-7c3a9d0b2e65",
  "is_active": true,
  "live_url": "https://live.browser-use.com/session/e2a8f0c4",
  "proxy_cost_usd": "0",
  "proxy_used_mb": "0",
  "recording_available": null,
  "recording_url": null,
  "started_at": "2026-07-27T18:10:00.000Z",
  "status": "active",
  "timeout_at": "2026-07-27T19:10:00.000Z"
}
```

### Start a browser task

Describe a task in plain English and a Browser Use cloud agent drives a real browser to do it: navigating, clicking, typing, and reading pages. The agent works in the background: this action returns a run ID straight away, so follow it with 'Get run status' until the run finishes, then 'Get run' to read what the agent found. Give it a workspace to hand it files and keep what it saves, a profile to start signed in, or secrets it can type into a login form without seeing them.

**Inputs**

- Task (`task`, text, required): What the agent should do, in plain English. Be specific about where to go and what to bring back, for example: 'Go to news.ycombinator.com and return the titles and links of the top 5 stories.'
- Model (`model`, text): Which model drives the agent. Defaults to GPT-6 Luna, Browser Use's recommended model. One of: `gpt-6-luna` (GPT-6 Luna (default)), `gpt-6-astra` (GPT-6 Astra), `gpt-6-sol` (GPT-6 Sol), `gpt-6.1-sol` (GPT-6.1 Sol), `gpt-5.6-luna` (GPT-5.6 Luna), `gpt-5.6-sol` (GPT-5.6 Sol), `gpt-5.6-terra` (GPT-5.6 Terra), `gpt-5.6`, `gpt-5.5`, `claude-opus-5-5` (Claude Opus 5.5), and 22 more. Default: `gpt-6-luna`.
- Reasoning effort (`reasoning_effort`, text): How hard the model thinks before each step: more is slower and costs more, less is faster. Leave blank for the model's own default (High for GPT-6 Luna). Only OpenAI, Claude and Gemini models have this setting. Only when Model is Claude Opus 4.7, Claude Opus 4.8, Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5, Claude Sonnet 5.5, GPT-5.5, GPT-5.6, GPT-6 Astra, GPT-6 Sol, GPT-6.1 Sol, GPT-6 Luna (default), GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.6 Luna, Gemini 3.6 Flash, Gemini 3.5 Flash, Gemini 3.1 Pro or Gemini 3 Flash. One of: `none` (None (thinking off)), `minimal`, `low`, `medium`, `high`, `xhigh` (Extra high), `max` (Maximum).
- Session ID (`session_id`, text): Continue an existing session so the agent keeps the earlier conversation and browser state. Leave blank to start a fresh session.
- Workspace ID (`workspace_id`, text): A workspace from 'Create workspace' (or an earlier run's 'workspace_id'). The agent gets the files uploaded to it, and whatever it saves stays there for 'Download workspace file'. Leave blank for a new, empty workspace.
- Cost limit (USD) (`max_cost_usd`, number): Stop the run once it has cost this much, in US dollars. Leave blank for no limit. At least 0.01.
- Browser profile ID (`profile_id`, text): ID of a Browser Use browser profile to load, so the agent reuses saved cookies and logins. Leave blank for a clean browser.
- Proxy country (`proxy_country_code`, text): Two-letter ISO country code to route the browser through, such as 'us', 'de', or 'jp'. Defaults to the United States. Enter 'none' to run without a proxy.
- Screen width (px) (`screen_width`, number): Browser window width in pixels (320-6144). Leave blank for the default. From 320 to 6144.
- Screen height (px) (`screen_height`, number): Browser window height in pixels (320-3456). Leave blank for the default. From 320 to 3456.
- Record the session (`record`, true/false): Record the browser session to a video. It is ready once the browser stops: stop it with 'Stop browser', then 'Get browser' returns the recording link. Default: `false`.
- Give the agent an email inbox (`agentmail`, true/false): Give the agent its own temporary email address it can send, receive and read mail with, such as to sign up for a site or receive a verification code. Default: `false`.
- Secrets (`secret_bindings`, list): Credentials the agent can have typed into a field without ever seeing them. Give each an alias, refer to the alias in the task (for example 'sign in with acme_password'), and list the sites it may be typed into. They apply to this run only; a follow-up run that needs them must be given them again.
- Grade the run (`judge`, true/false): Have Browser Use grade the finished run with an LLM judge. The verdict shows up in the run's 'judgement' field a little after the run ends, and its cost is billed to the run. Default: `false`.
- Grading notes (`judge_context`, text): Extra context for the judge, such as what a successful outcome looks like. Filling this in turns grading on.

**Outputs**: The run that was just started. It has no result yet; poll 'Get run status' with the returned ID, then 'Get run'.

- `events_url` (text): URL of the run's live event stream.
- `id` (text): The new run's ID. Pass it to 'Get run status' and 'Get run'.
- `is_terminal` (true/false): False for a run that has just started; poll 'Get run status' until it turns true.
- `missing_file_ids` (list): Any attached file IDs Browser Use could not find.
- `model` (text): Model that ran the task.
- `session_id` (text): ID of the session (conversation) the run belongs to. Pass it to 'Send follow-up message' or to a later run to continue.
- `status` (text): Where the run starts out: queued, dispatching, or running. The agent has not finished yet.
- `task` (text): The instruction the agent was given.
- `workspace_id` (text): ID of the workspace the run's files live in. Pass it to 'List workspace files' to see what the agent saved.

**Example output**

```json
{
  "events_url": "https://api.browser-use.com/api/v4/runs/3f1c8a52-6f47-4f1a-9d2f-27b0c5d9a1e4/events",
  "id": "3f1c8a52-6f47-4f1a-9d2f-27b0c5d9a1e4",
  "is_terminal": false,
  "missing_file_ids": [],
  "model": "gpt-6-luna",
  "session_id": "9c0d1f77-2b53-4a6e-9d09-1c7f2a8e5b31",
  "status": "queued",
  "task": "Find the top 3 trending repos on GitHub today",
  "workspace_id": "51b0f8a3-9a3d-4f7c-bb2e-6e1d0c4a9f22"
}
```

### Stop browser

Stop a cloud browser and get its unused time refunded. Use it once a run's browser is no longer needed for follow-ups, so it stops billing and frees a concurrency slot. It cannot be restarted.

**Inputs**

- Browser ID (`browser_id`, text, required): The cloud browser's ID, from 'List browsers' (filter it by a run's session to find the browser that run used) or 'Start a browser'.

**Outputs**

- `agent_session_id` (text): The agent session that started the browser, or null for one started with 'Start a browser'.
- `browser_cost_usd` (text): What the browser's running time cost, in US dollars.
- `cdp_url` (text): Chrome DevTools Protocol URL, for automation tools.
- `finished_at` (text): When the browser stopped (ISO 8601), or null.
- `id` (text): The browser's ID.
- `is_active` (true/false): True while the browser is running (and billing).
- `live_url` (text): Link to watch and control the browser live. Treat it like a password: anyone with it can use the browser.
- `proxy_cost_usd` (text): What its proxy traffic cost, in US dollars.
- `proxy_used_mb` (text): Proxy traffic used, in megabytes.
- `recording_available` (true/false): False when no recording will ever appear (recording was off). Null in lists.
- `recording_url` (text): Download link for the recording, once a recorded browser has stopped and the video is processed. Only 'Get browser' fills it in.
- `started_at` (text): When the browser started (ISO 8601).
- `status` (text): Either 'active' or 'stopped'.
- `timeout_at` (text): When the browser stops on its own (ISO 8601).

**Example output**

```json
{
  "agent_session_id": null,
  "browser_cost_usd": "0.02",
  "cdp_url": "wss://cdp.browser-use.com/e2a8f0c4",
  "finished_at": "2026-07-27T18:25:00.000Z",
  "id": "e2a8f0c4-51d7-4b6e-8f19-7c3a9d0b2e65",
  "is_active": false,
  "live_url": null,
  "proxy_cost_usd": "0",
  "proxy_used_mb": "0",
  "recording_available": true,
  "recording_url": null,
  "started_at": "2026-07-27T18:10:00.000Z",
  "status": "stopped",
  "timeout_at": "2026-07-27T19:10:00.000Z"
}
```

### Stop sharing session

Turn a session's public link off. Sharing the session again brings the same link back.

**Inputs**

- Session ID (`session_id`, text, required): The session (conversation) to use: the 'session_id' returned by 'Start a browser task', 'Get run' or 'List sessions'.

**Outputs**

- `created_at` (text): When the session was first shared (ISO 8601).
- `is_active` (true/false): Whether the link currently works.
- `session_id` (text): The shared session's ID.
- `share_token` (text): The token at the end of the link.
- `share_url` (text): Public link anyone can open to view the session.
- `view_count` (number): How many times the link has been opened.

**Example output**

```json
{
  "created_at": "2026-07-27T18:08:30.004Z",
  "is_active": false,
  "session_id": "9c0d1f77-2b53-4a6e-9d09-1c7f2a8e5b31",
  "share_token": "k3Zp9QvT",
  "share_url": "https://cloud.browser-use.com/share/k3Zp9QvT",
  "view_count": 0
}
```

### Update profile

Rename a browser profile or change the user ID it is filed under.

**Inputs**

- Profile ID (`profile_id`, text, required): The browser profile's ID, from 'List profiles' or 'Create profile'.
- Name (`name`, text): The profile's new name. Leave blank to keep it.
- Your user ID (`external_user_id`, text): The profile's new user identifier. Leave blank to keep it.

**Outputs**

- `cookie_domains` (list): Sites the profile holds cookies (logins) for.
- `created_at` (text): When the profile was created (ISO 8601).
- `external_user_id` (text): Your own user identifier for the profile, or null.
- `id` (text): The profile's ID. Pass it as 'Browser profile ID' to start a browser that is already signed in.
- `last_used_at` (text): When a browser last used the profile (ISO 8601).
- `name` (text): The profile's name, or null.
- `updated_at` (text): When the profile was last updated (ISO 8601).

**Example output**

```json
{
  "cookie_domains": [
    "acme.example.com"
  ],
  "created_at": "2026-07-20T09:15:00.000Z",
  "external_user_id": "customer-1042",
  "id": "b7e4c1d2-8a90-4f3e-9c55-0d2f6a1e7b34",
  "last_used_at": "2026-07-27T18:04:12.000Z",
  "name": "Acme billing login",
  "updated_at": "2026-07-27T18:06:49.000Z"
}
```

### Upload workspace file

Put a file in a workspace, under 'uploads/', for the agent to work with: every run given the workspace gets the file at the start. Up to 50 MB per file.

**Inputs**

- Workspace ID (`workspace_id`, text, required): The workspace holding the files: the 'workspace_id' a run returns, or the 'id' from 'Create workspace'.
- File (`file`, text, required): The file to upload: upload one, pick a file from an earlier step, or paste a public https:// link to it.
- Save as (`filename`, text): The file's name in the workspace, such as 'leads.csv'. Leave blank to keep its own name. Browser Use stores it in lower case, with spaces and symbols as underscores, so use the 'path' this step returns.
- Replace a file with the same name (`overwrite`, true/false): Replace a file of the same name already in the workspace. Turn off to fail instead. Default: `true`.

**Outputs**

- `content_type` (text): The file's MIME type.
- `id` (text): The upload's ID.
- `name` (text): The file's name.
- `path` (text): Its path in the workspace, e.g. 'uploads/leads.csv'.
- `replaced` (true/false): Whether it replaced a file of the same name.
- `size_bytes` (number): The file's size in bytes.
- `stored_name` (text): The name it is stored under, made safe.
- `workspace_id` (text): The workspace the file went to.

**Example output**

```json
{
  "content_type": "application/pdf",
  "id": "c41e9a07-6b25-4d8f-a3e0-2f7b51d9c684",
  "name": "brief.pdf",
  "path": "uploads/brief.pdf",
  "replaced": false,
  "size_bytes": 48211,
  "stored_name": "brief.pdf",
  "workspace_id": "51b0f8a3-9a3d-4f7c-bb2e-6e1d0c4a9f22"
}
```