browser-use-sdk 3.4.1 → 3.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/v3.d.cts ADDED
@@ -0,0 +1,1406 @@
1
+ import { z } from 'zod';
2
+ import { H as HttpClient } from './errors-BtB79l7x.cjs';
3
+ export { B as BrowserUseError } from './errors-BtB79l7x.cjs';
4
+
5
+ interface components {
6
+ schemas: {
7
+ /**
8
+ * AccountNotFoundError
9
+ * @description Error response when an account is not found
10
+ */
11
+ AccountNotFoundError: {
12
+ /**
13
+ * Detail
14
+ * @default Account not found
15
+ */
16
+ detail: string;
17
+ };
18
+ /**
19
+ * AccountView
20
+ * @description View model for account information.
21
+ */
22
+ AccountView: {
23
+ /**
24
+ * Name
25
+ * @description The name of the user
26
+ */
27
+ name?: string | null;
28
+ /**
29
+ * Credits Balance USD
30
+ * @description The total credits balance in USD
31
+ */
32
+ totalCreditsBalanceUsd: number;
33
+ /**
34
+ * Monthly Credits Balance USD
35
+ * @description Monthly subscription credits balance in USD
36
+ */
37
+ monthlyCreditsBalanceUsd: number;
38
+ /**
39
+ * Additional Credits Balance USD
40
+ * @description Additional top-up credits balance in USD
41
+ */
42
+ additionalCreditsBalanceUsd: number;
43
+ /**
44
+ * Rate Limit
45
+ * @description The rate limit for the account
46
+ */
47
+ rateLimit: number;
48
+ /**
49
+ * Plan Info
50
+ * @description The plan information
51
+ */
52
+ planInfo: components["schemas"]["PlanInfo"];
53
+ /**
54
+ * Project ID
55
+ * Format: uuid
56
+ * @description The ID of the project
57
+ */
58
+ projectId: string;
59
+ };
60
+ /**
61
+ * BrowserSessionItemView
62
+ * @description View model for representing a browser session in list views.
63
+ */
64
+ BrowserSessionItemView: {
65
+ /**
66
+ * ID
67
+ * Format: uuid
68
+ * @description Unique identifier for the session
69
+ */
70
+ id: string;
71
+ /**
72
+ * Status
73
+ * @description Current status of the session (active/stopped)
74
+ */
75
+ status: components["schemas"]["BrowserSessionStatus"];
76
+ /**
77
+ * Live URL
78
+ * @description URL where the browser can be viewed live in real-time
79
+ */
80
+ liveUrl?: string | null;
81
+ /**
82
+ * CDP URL
83
+ * @description Chrome DevTools Protocol URL for browser automation
84
+ */
85
+ cdpUrl?: string | null;
86
+ /**
87
+ * Timeout At
88
+ * Format: date-time
89
+ * @description Timestamp when the session will timeout
90
+ */
91
+ timeoutAt: string;
92
+ /**
93
+ * Started At
94
+ * Format: date-time
95
+ * @description Timestamp when the session was created and started
96
+ */
97
+ startedAt: string;
98
+ /**
99
+ * Finished At
100
+ * @description Timestamp when the session was stopped (None if still active)
101
+ */
102
+ finishedAt?: string | null;
103
+ /**
104
+ * Proxy Used MB
105
+ * @description Amount of proxy data used in MB
106
+ * @default 0
107
+ */
108
+ proxyUsedMb: string;
109
+ /**
110
+ * Proxy Cost
111
+ * @description Cost of proxy usage in USD
112
+ * @default 0
113
+ */
114
+ proxyCost: string;
115
+ /**
116
+ * Browser Cost
117
+ * @description Cost of browser session hosting in USD
118
+ * @default 0
119
+ */
120
+ browserCost: string;
121
+ /**
122
+ * Agent Session ID
123
+ * @description ID of the agent session that created this browser (None for standalone BaaS sessions)
124
+ */
125
+ agentSessionId?: string | null;
126
+ /**
127
+ * Recording URL
128
+ * @description Presigned URL to download the session recording (available after session ends, if recording was enabled)
129
+ */
130
+ recordingUrl?: string | null;
131
+ };
132
+ /**
133
+ * BrowserSessionListResponse
134
+ * @description Response model for paginated browser session list requests.
135
+ */
136
+ BrowserSessionListResponse: {
137
+ /**
138
+ * Items
139
+ * @description List of browser session views for the current page
140
+ */
141
+ items: components["schemas"]["BrowserSessionItemView"][];
142
+ /**
143
+ * Total Items
144
+ * @description Total number of items in the list
145
+ */
146
+ totalItems: number;
147
+ /**
148
+ * Page Number
149
+ * @description Page number
150
+ */
151
+ pageNumber: number;
152
+ /**
153
+ * Page Size
154
+ * @description Number of items per page
155
+ */
156
+ pageSize: number;
157
+ };
158
+ /**
159
+ * BrowserSessionStatus
160
+ * @description Enumeration of possible browser session states
161
+ *
162
+ * Attributes:
163
+ * ACTIVE: Session is currently active and running (browser is running)
164
+ * STOPPED: Session has been stopped and is no longer active (browser is stopped)
165
+ * @enum {string}
166
+ */
167
+ BrowserSessionStatus: "active" | "stopped";
168
+ /**
169
+ * BrowserSessionUpdateAction
170
+ * @description Available actions that can be performed on a browser session
171
+ *
172
+ * Attributes:
173
+ * STOP: Stop the browser session (cannot be undone)
174
+ * @enum {string}
175
+ */
176
+ BrowserSessionUpdateAction: "stop";
177
+ /**
178
+ * BrowserSessionView
179
+ * @description View model for representing a browser session.
180
+ */
181
+ BrowserSessionView: {
182
+ /**
183
+ * ID
184
+ * Format: uuid
185
+ * @description Unique identifier for the session
186
+ */
187
+ id: string;
188
+ /**
189
+ * Status
190
+ * @description Current status of the session (active/stopped)
191
+ */
192
+ status: components["schemas"]["BrowserSessionStatus"];
193
+ /**
194
+ * Live URL
195
+ * @description URL where the browser can be viewed live in real-time
196
+ */
197
+ liveUrl?: string | null;
198
+ /**
199
+ * CDP URL
200
+ * @description Chrome DevTools Protocol URL for browser automation
201
+ */
202
+ cdpUrl?: string | null;
203
+ /**
204
+ * Timeout At
205
+ * Format: date-time
206
+ * @description Timestamp when the session will timeout
207
+ */
208
+ timeoutAt: string;
209
+ /**
210
+ * Started At
211
+ * Format: date-time
212
+ * @description Timestamp when the session was created and started
213
+ */
214
+ startedAt: string;
215
+ /**
216
+ * Finished At
217
+ * @description Timestamp when the session was stopped (None if still active)
218
+ */
219
+ finishedAt?: string | null;
220
+ /**
221
+ * Proxy Used MB
222
+ * @description Amount of proxy data used in MB
223
+ * @default 0
224
+ */
225
+ proxyUsedMb: string;
226
+ /**
227
+ * Proxy Cost
228
+ * @description Cost of proxy usage in USD
229
+ * @default 0
230
+ */
231
+ proxyCost: string;
232
+ /**
233
+ * Browser Cost
234
+ * @description Cost of browser session hosting in USD
235
+ * @default 0
236
+ */
237
+ browserCost: string;
238
+ /**
239
+ * Agent Session ID
240
+ * @description ID of the agent session that created this browser (None for standalone BaaS sessions)
241
+ */
242
+ agentSessionId?: string | null;
243
+ /**
244
+ * Recording URL
245
+ * @description Presigned URL to download the session recording (available after session ends, if recording was enabled)
246
+ */
247
+ recordingUrl?: string | null;
248
+ };
249
+ /**
250
+ * BuAgentSessionStatus
251
+ * @description Session lifecycle status. Progresses through: created → idle → running → idle → ... → stopped / timed_out / error.
252
+ *
253
+ * - `created`: Sandbox is starting up. The session is not yet ready to accept tasks.
254
+ * - `idle`: Sandbox is healthy and waiting for a task. You can dispatch a task or upload files.
255
+ * - `running`: A task is currently being executed by the agent.
256
+ * - `stopped`: Session was stopped — either explicitly via the stop endpoint, or automatically after task completion (when `keepAlive` is false).
257
+ * - `timed_out`: Session was cleaned up due to inactivity timeout.
258
+ * - `error`: Sandbox failed to start or encountered an unrecoverable error.
259
+ * @enum {string}
260
+ */
261
+ BuAgentSessionStatus: "created" | "idle" | "running" | "stopped" | "timed_out" | "error";
262
+ /**
263
+ * BuModel
264
+ * @description The model to use for the agent. Each model has different capabilities and pricing.
265
+ *
266
+ * - `bu-mini` / `gemini-3-flash`: Gemini 3 Flash — fast and cost-effective. Best for simple, well-defined tasks like form filling or data extraction.
267
+ * - `bu-max` / `claude-sonnet-4.6`: Claude Sonnet 4.6 — balanced performance. Best for multi-step workflows that require reasoning and decision-making.
268
+ * - `bu-ultra` / `claude-opus-4.6`: Claude Opus 4.6 — most capable. Best for complex tasks that require advanced reasoning, long-horizon planning, or handling ambiguous instructions.
269
+ * - `gpt-5.4-mini`: GPT-5.4 mini — OpenAI's fast and efficient model. Best for tasks that benefit from OpenAI's capabilities.
270
+ * @enum {string}
271
+ */
272
+ BuModel: "bu-mini" | "bu-max" | "bu-ultra" | "gemini-3-flash" | "claude-sonnet-4.6" | "claude-opus-4.6" | "gpt-5.4-mini";
273
+ /**
274
+ * CreateBrowserSessionRequest
275
+ * @description Request model for creating a browser session.
276
+ */
277
+ CreateBrowserSessionRequest: {
278
+ /**
279
+ * Profile ID
280
+ * @description The ID of the profile to use for the session
281
+ */
282
+ profileId?: string | null;
283
+ /**
284
+ * Proxy Country Code
285
+ * @description Country code for proxy location. Defaults to US. Set to null to disable proxy.
286
+ * @default us
287
+ */
288
+ proxyCountryCode: components["schemas"]["ProxyCountryCode"] | null;
289
+ /**
290
+ * Timeout
291
+ * @description The timeout for the session in minutes. All users can use up to 240 minutes (4 hours). Pay As You Go users are charged $0.06/hour, subscribers get 50% off.
292
+ * @default 60
293
+ */
294
+ timeout: number;
295
+ /**
296
+ * Browser Screen Width
297
+ * @description Custom screen width in pixels for the browser.
298
+ */
299
+ browserScreenWidth?: number | null;
300
+ /**
301
+ * Browser Screen Height
302
+ * @description Custom screen height in pixels for the browser.
303
+ */
304
+ browserScreenHeight?: number | null;
305
+ /**
306
+ * Allow Resizing
307
+ * @description Whether to allow the browser to be resized during the session (not recommended since it reduces stealthiness).
308
+ * @default false
309
+ */
310
+ allowResizing: boolean;
311
+ /**
312
+ * Custom Proxy
313
+ * @description Custom proxy settings to use for the session. If not provided, our proxies will be used. Custom proxies are available on any active subscription.
314
+ */
315
+ customProxy?: components["schemas"]["CustomProxy"] | null;
316
+ /**
317
+ * Enable Recording
318
+ * @description If True, enables session recording. Defaults to False.
319
+ * @default false
320
+ */
321
+ enableRecording: boolean;
322
+ };
323
+ /**
324
+ * CustomProxy
325
+ * @description Request model for creating a custom proxy.
326
+ */
327
+ CustomProxy: {
328
+ /**
329
+ * Host
330
+ * @description Host of the proxy.
331
+ */
332
+ host: string;
333
+ /**
334
+ * Port
335
+ * @description Port of the proxy.
336
+ */
337
+ port: number;
338
+ /**
339
+ * Username
340
+ * @description Username for proxy authentication.
341
+ */
342
+ username?: string | null;
343
+ /**
344
+ * Password
345
+ * @description Password for proxy authentication.
346
+ */
347
+ password?: string | null;
348
+ };
349
+ /**
350
+ * FileInfo
351
+ * @description A file in a session's workspace.
352
+ */
353
+ FileInfo: {
354
+ /**
355
+ * Path
356
+ * @description File path relative to the session workspace root.
357
+ */
358
+ path: string;
359
+ /**
360
+ * Size
361
+ * @description File size in bytes.
362
+ */
363
+ size: number;
364
+ /**
365
+ * Lastmodified
366
+ * Format: date-time
367
+ * @description When the file was last modified.
368
+ */
369
+ lastModified: string;
370
+ /**
371
+ * Url
372
+ * @description Presigned download URL (60s expiry). Only included when `includeUrls=true`.
373
+ */
374
+ url?: string | null;
375
+ };
376
+ /**
377
+ * FileListResponse
378
+ * @description Paginated file listing with optional presigned download URLs.
379
+ */
380
+ FileListResponse: {
381
+ /** Files */
382
+ files: components["schemas"]["FileInfo"][];
383
+ /**
384
+ * Folders
385
+ * @description Immediate sub-folder names at this prefix level
386
+ */
387
+ folders?: string[];
388
+ /**
389
+ * Nextcursor
390
+ * @description Cursor for the next page. Pass as the `cursor` query parameter to fetch the next page.
391
+ */
392
+ nextCursor?: string | null;
393
+ /**
394
+ * Hasmore
395
+ * @description Whether there are more files beyond this page.
396
+ * @default false
397
+ */
398
+ hasMore: boolean;
399
+ };
400
+ /**
401
+ * FileUploadItem
402
+ * @description A single file to upload.
403
+ */
404
+ FileUploadItem: {
405
+ /**
406
+ * Name
407
+ * @description Filename, e.g. "data.csv"
408
+ */
409
+ name: string;
410
+ /**
411
+ * Contenttype
412
+ * @description MIME type, e.g. "text/csv"
413
+ * @default application/octet-stream
414
+ */
415
+ contentType: string;
416
+ /**
417
+ * Size
418
+ * @description File size in bytes (required for workspace uploads)
419
+ */
420
+ size?: number | null;
421
+ };
422
+ /**
423
+ * FileUploadRequest
424
+ * @description Request body for generating presigned upload URLs.
425
+ */
426
+ FileUploadRequest: {
427
+ /** Files */
428
+ files: components["schemas"]["FileUploadItem"][];
429
+ };
430
+ /**
431
+ * FileUploadResponse
432
+ * @description Presigned upload URLs for the requested files.
433
+ */
434
+ FileUploadResponse: {
435
+ /** Files */
436
+ files: components["schemas"]["FileUploadResponseItem"][];
437
+ };
438
+ /**
439
+ * FileUploadResponseItem
440
+ * @description Presigned upload URL for a single file.
441
+ */
442
+ FileUploadResponseItem: {
443
+ /**
444
+ * Name
445
+ * @description Original filename as requested.
446
+ */
447
+ name: string;
448
+ /**
449
+ * Uploadurl
450
+ * @description Presigned PUT URL. Upload the file by sending a PUT request to this URL with the file content and matching Content-Type header. Expires after 5 minutes.
451
+ */
452
+ uploadUrl: string;
453
+ /**
454
+ * Path
455
+ * @description Path where the file will be stored in the workspace, e.g. "uploads/data.csv".
456
+ */
457
+ path: string;
458
+ };
459
+ /** HTTPValidationError */
460
+ HTTPValidationError: {
461
+ /** Detail */
462
+ detail?: components["schemas"]["ValidationError"][];
463
+ };
464
+ /**
465
+ * InsufficientCreditsError
466
+ * @description Error response when there are insufficient credits
467
+ */
468
+ InsufficientCreditsError: {
469
+ /**
470
+ * Detail
471
+ * @default Insufficient credits
472
+ */
473
+ detail: string;
474
+ };
475
+ /** MessageListResponse */
476
+ MessageListResponse: {
477
+ /**
478
+ * Messages
479
+ * @description List of messages in chronological order.
480
+ */
481
+ messages: components["schemas"]["MessageResponse"][];
482
+ /**
483
+ * Hasmore
484
+ * @description Whether there are more messages available beyond this page. Use cursor-based pagination with the `after` or `before` query parameters to fetch more.
485
+ */
486
+ hasMore: boolean;
487
+ };
488
+ /**
489
+ * MessageResponse
490
+ * @description A single message from the session's message stream.
491
+ *
492
+ * Messages represent the agent's actions, observations, and decisions as it executes a task.
493
+ */
494
+ MessageResponse: {
495
+ /**
496
+ * Id
497
+ * Format: uuid
498
+ * @description Unique message identifier.
499
+ */
500
+ id: string;
501
+ /**
502
+ * Sessionid
503
+ * Format: uuid
504
+ * @description ID of the session this message belongs to.
505
+ */
506
+ sessionId: string;
507
+ /**
508
+ * Role
509
+ * @description Message role: "human" for user-submitted tasks, "ai" for agent actions and responses.
510
+ */
511
+ role: string;
512
+ /**
513
+ * Data
514
+ * @description Raw message content. Format depends on the message type — may be plain text, JSON, or structured action data.
515
+ */
516
+ data: string;
517
+ /**
518
+ * Type
519
+ * @description Message category. Common values: `user_message`, `assistant_message`, `browser_action`, `file_operation`, `code_execution`, `integration`, `planning`, `completion`, `browser_action_result`, `browser_action_error`.
520
+ * @default
521
+ */
522
+ type: string;
523
+ /**
524
+ * Summary
525
+ * @description One-liner human-readable description of the message (e.g. "Navigating to google.com", "Clicking element #5"). Useful for building activity feeds.
526
+ * @default
527
+ */
528
+ summary: string;
529
+ /**
530
+ * Screenshoturl
531
+ * @description Browser screenshot captured at the time of this message. Presigned URL, expires after 5 minutes.
532
+ */
533
+ screenshotUrl?: string | null;
534
+ /**
535
+ * Hidden
536
+ * @description Whether this message should be hidden from the user in a chat UI.
537
+ * @default false
538
+ */
539
+ hidden: boolean;
540
+ /**
541
+ * Createdat
542
+ * Format: date-time
543
+ * @description When this message was created.
544
+ */
545
+ createdAt: string;
546
+ };
547
+ /**
548
+ * PlanInfo
549
+ * @description View model for plan information
550
+ */
551
+ PlanInfo: {
552
+ /**
553
+ * Plan Name
554
+ * @description The name of the plan
555
+ */
556
+ planName: string;
557
+ /**
558
+ * Subscription Status
559
+ * @description The status of the subscription
560
+ */
561
+ subscriptionStatus: string | null;
562
+ /**
563
+ * Subscription ID
564
+ * @description The ID of the subscription
565
+ */
566
+ subscriptionId: string | null;
567
+ /**
568
+ * Subscription Current Period End
569
+ * @description The end of the current period
570
+ */
571
+ subscriptionCurrentPeriodEnd: string | null;
572
+ /**
573
+ * Subscription Canceled At
574
+ * @description The date the subscription was canceled
575
+ */
576
+ subscriptionCanceledAt: string | null;
577
+ };
578
+ /**
579
+ * ProfileCreateRequest
580
+ * @description Request model for creating a new profile.
581
+ */
582
+ ProfileCreateRequest: {
583
+ /**
584
+ * Name
585
+ * @description Optional name for the profile
586
+ */
587
+ name?: string | null;
588
+ /**
589
+ * User ID
590
+ * @description Your internal user identifier for this profile. Use this to associate a profile with a user in your system.
591
+ */
592
+ userId?: string | null;
593
+ };
594
+ /**
595
+ * ProfileListResponse
596
+ * @description Response model for paginated profile list requests.
597
+ */
598
+ ProfileListResponse: {
599
+ /**
600
+ * Items
601
+ * @description List of profile views for the current page
602
+ */
603
+ items: components["schemas"]["ProfileView"][];
604
+ /**
605
+ * Total Items
606
+ * @description Total number of items in the list
607
+ */
608
+ totalItems: number;
609
+ /**
610
+ * Page Number
611
+ * @description Page number
612
+ */
613
+ pageNumber: number;
614
+ /**
615
+ * Page Size
616
+ * @description Number of items per page
617
+ */
618
+ pageSize: number;
619
+ };
620
+ /**
621
+ * ProfileNotFoundError
622
+ * @description Error response when a profile is not found
623
+ */
624
+ ProfileNotFoundError: {
625
+ /**
626
+ * Detail
627
+ * @default Profile not found
628
+ */
629
+ detail: string;
630
+ };
631
+ /**
632
+ * ProfileUpdateRequest
633
+ * @description Request model for updating a profile.
634
+ */
635
+ ProfileUpdateRequest: {
636
+ /**
637
+ * Name
638
+ * @description Optional name for the profile
639
+ */
640
+ name?: string | null;
641
+ /**
642
+ * User ID
643
+ * @description Your internal user identifier for this profile. Use this to associate a profile with a user in your system.
644
+ */
645
+ userId?: string | null;
646
+ };
647
+ /**
648
+ * ProfileView
649
+ * @description View model for representing a profile. A profile lets you preserve the login state between sessions.
650
+ *
651
+ * We recommend that you create a separate profile for each user of your app.
652
+ * You can assign a user_id to each profile to easily identify which user the profile belongs to.
653
+ */
654
+ ProfileView: {
655
+ /**
656
+ * ID
657
+ * Format: uuid
658
+ * @description Unique identifier for the profile
659
+ */
660
+ id: string;
661
+ /**
662
+ * User ID
663
+ * @description Your internal user identifier for this profile. Use this to associate a profile with a user in your system.
664
+ */
665
+ userId?: string | null;
666
+ /**
667
+ * Name
668
+ * @description Optional name for the profile
669
+ */
670
+ name?: string | null;
671
+ /**
672
+ * Last Used At
673
+ * @description Timestamp when the profile was last used
674
+ */
675
+ lastUsedAt?: string | null;
676
+ /**
677
+ * Created At
678
+ * Format: date-time
679
+ * @description Timestamp when the profile was created
680
+ */
681
+ createdAt: string;
682
+ /**
683
+ * Updated At
684
+ * Format: date-time
685
+ * @description Timestamp when the profile was last updated
686
+ */
687
+ updatedAt: string;
688
+ /**
689
+ * Cookie Domains
690
+ * @description List of domain URLs that have cookies stored for this profile
691
+ */
692
+ cookieDomains?: string[] | null;
693
+ };
694
+ /**
695
+ * ProxyCountryCode
696
+ * @enum {string}
697
+ */
698
+ ProxyCountryCode: "ad" | "ae" | "af" | "ag" | "ai" | "al" | "am" | "an" | "ao" | "aq" | "ar" | "as" | "at" | "au" | "aw" | "az" | "ba" | "bb" | "bd" | "be" | "bf" | "bg" | "bh" | "bi" | "bj" | "bl" | "bm" | "bn" | "bo" | "bq" | "br" | "bs" | "bt" | "bv" | "bw" | "by" | "bz" | "ca" | "cc" | "cd" | "cf" | "cg" | "ch" | "ck" | "cl" | "cm" | "co" | "cr" | "cs" | "cu" | "cv" | "cw" | "cx" | "cy" | "cz" | "de" | "dj" | "dk" | "dm" | "do" | "dz" | "ec" | "ee" | "eg" | "eh" | "er" | "es" | "et" | "fi" | "fj" | "fk" | "fm" | "fo" | "fr" | "ga" | "gd" | "ge" | "gf" | "gg" | "gh" | "gi" | "gl" | "gm" | "gn" | "gp" | "gq" | "gr" | "gs" | "gt" | "gu" | "gw" | "gy" | "hk" | "hm" | "hn" | "hr" | "ht" | "hu" | "id" | "ie" | "il" | "im" | "in" | "iq" | "ir" | "is" | "it" | "je" | "jm" | "jo" | "jp" | "ke" | "kg" | "kh" | "ki" | "km" | "kn" | "kp" | "kr" | "kw" | "ky" | "kz" | "la" | "lb" | "lc" | "li" | "lk" | "lr" | "ls" | "lt" | "lu" | "lv" | "ly" | "ma" | "mc" | "md" | "me" | "mf" | "mg" | "mh" | "mk" | "ml" | "mm" | "mn" | "mo" | "mp" | "mq" | "mr" | "ms" | "mt" | "mu" | "mv" | "mw" | "mx" | "my" | "mz" | "na" | "nc" | "ne" | "nf" | "ng" | "ni" | "nl" | "no" | "np" | "nr" | "nu" | "nz" | "om" | "pa" | "pe" | "pf" | "pg" | "ph" | "pk" | "pl" | "pm" | "pn" | "pr" | "ps" | "pt" | "pw" | "py" | "qa" | "re" | "ro" | "rs" | "ru" | "rw" | "sa" | "sb" | "sc" | "sd" | "se" | "sg" | "sh" | "si" | "sj" | "sk" | "sl" | "sm" | "sn" | "so" | "sr" | "ss" | "st" | "sv" | "sx" | "sy" | "sz" | "tc" | "td" | "tf" | "tg" | "th" | "tj" | "tk" | "tl" | "tm" | "tn" | "to" | "tr" | "tt" | "tv" | "tw" | "tz" | "ua" | "ug" | "uk" | "us" | "uy" | "uz" | "va" | "vc" | "ve" | "vg" | "vi" | "vn" | "vu" | "wf" | "ws" | "xk" | "ye" | "yt" | "za" | "zm" | "zw";
699
+ /**
700
+ * RunTaskRequest
701
+ * @description Create a new session, dispatch a task, or both.
702
+ *
703
+ * - **No `sessionId` + no `task`**: creates an idle session (useful for uploading files before running a task).
704
+ * - **No `sessionId` + `task`**: creates a new session and immediately runs the task.
705
+ * - **`sessionId` + `task`**: dispatches the task to an existing idle session.
706
+ * - **`sessionId` + no `task`**: returns 422 — a task is required when targeting an existing session.
707
+ */
708
+ RunTaskRequest: {
709
+ /**
710
+ * Task
711
+ * @description The natural-language instruction for the agent to execute (e.g. "Go to amazon.com and find the best-rated wireless mouse under $50"). Required when dispatching to an existing session.
712
+ */
713
+ task?: string | null;
714
+ /**
715
+ * @description The model to use. "gemini-3-flash" is fast and cheap, "claude-sonnet-4.6" is balanced, "claude-opus-4.6" is most capable. See BuModel for details.
716
+ * @default claude-sonnet-4.6
717
+ */
718
+ model: components["schemas"]["BuModel"];
719
+ /**
720
+ * Sessionid
721
+ * @description ID of an existing idle session to dispatch the task to. If omitted, a new session is created.
722
+ */
723
+ sessionId?: string | null;
724
+ /**
725
+ * Keepalive
726
+ * @description If true, the session stays alive in idle state after the task completes instead of automatically stopping. This lets you dispatch follow-up tasks to the same session, preserving browser state and files.
727
+ * @default false
728
+ */
729
+ keepAlive: boolean;
730
+ /**
731
+ * Maxcostusd
732
+ * @description Maximum total cost in USD allowed for this session. The task will be stopped if this limit is reached. If omitted, a default limit applies (capped by your available balance).
733
+ */
734
+ maxCostUsd?: number | string | null;
735
+ /**
736
+ * Profileid
737
+ * @description ID of a browser profile to load into the session. Profiles persist cookies, local storage, and other browser state across sessions. Create profiles via the Profiles API.
738
+ */
739
+ profileId?: string | null;
740
+ /**
741
+ * Workspaceid
742
+ * @description ID of a workspace to attach to the session. Workspaces provide persistent file storage that carries across sessions. Create workspaces via the Workspaces API.
743
+ */
744
+ workspaceId?: string | null;
745
+ /**
746
+ * @description Country code for the browser proxy (e.g. "US", "DE", "JP"). Set to null to disable the proxy. The proxy routes browser traffic through the specified country, useful for accessing geo-restricted content.
747
+ * @default us
748
+ */
749
+ proxyCountryCode: components["schemas"]["ProxyCountryCode"] | null;
750
+ /**
751
+ * Outputschema
752
+ * @description A JSON Schema that the agent's final output must conform to. When set, the agent will return structured data matching this schema in the `output` field of the response. Example: {"type": "object", "properties": {"price": {"type": "number"}, "title": {"type": "string"}}}.
753
+ */
754
+ outputSchema?: {
755
+ [key: string]: unknown;
756
+ } | null;
757
+ /**
758
+ * Enablescheduledtasks
759
+ * @description If true, the agent can create scheduled tasks that run on a recurring basis (e.g. "every Monday morning, check my inbox and summarize new emails"). Scheduled tasks are tied to your project and persist beyond the session. Note: all scheduled tasks are visible project-wide, so avoid enabling this in multi-user setups where task isolation is needed.
760
+ * @default false
761
+ */
762
+ enableScheduledTasks: boolean;
763
+ /**
764
+ * Enablerecording
765
+ * @description If true, records a video of the browser session. The recording URLs will be available in the `recordingUrls` field of the session response after the task completes.
766
+ * @default false
767
+ */
768
+ enableRecording: boolean;
769
+ /**
770
+ * Skills
771
+ * @description If true, enables built-in agent skills like Google Sheets integration and file management. Set to false to restrict the agent to browser-only actions.
772
+ * @default true
773
+ */
774
+ skills: boolean;
775
+ /**
776
+ * Agentmail
777
+ * @description If true, provisions a temporary email inbox (via AgentMail) for the session. The email address is available in the `agentmailEmail` field of the session response. Useful for tasks that require email verification or sign-ups.
778
+ * @default true
779
+ */
780
+ agentmail: boolean;
781
+ /**
782
+ * Cachescript
783
+ * @description Controls deterministic script caching. `null` (default): auto-detected — enabled when the task contains `@{{value}}` brackets and a workspace is attached. `true`: force-enable script caching even without brackets (caches the exact task). `false`: force-disable, even if brackets are present. When active, the first call runs the full agent and saves a reusable script. Subsequent calls with the same task template execute the cached script with $0 LLM cost. Requires workspace_id when enabled. Example: "Get prices from @{{https://example.com}} for @{{electronics}}".
784
+ */
785
+ cacheScript?: boolean | null;
786
+ /**
787
+ * Autoheal
788
+ * @description When cache_script is active, controls whether a lightweight LLM validates the cached script output. If the output looks incorrect (empty, error, wrong structure), the system automatically re-triggers the full agent to generate a new version of the script. Set to false to disable validation and always return the raw script output.
789
+ * @default true
790
+ */
791
+ autoHeal: boolean;
792
+ };
793
+ /** SessionListResponse */
794
+ SessionListResponse: {
795
+ /**
796
+ * Sessions
797
+ * @description List of sessions.
798
+ */
799
+ sessions: components["schemas"]["SessionResponse"][];
800
+ /**
801
+ * Total
802
+ * @description Total number of sessions matching the query.
803
+ */
804
+ total: number;
805
+ /**
806
+ * Page
807
+ * @description Current page number (1-indexed).
808
+ */
809
+ page: number;
810
+ /**
811
+ * Pagesize
812
+ * @description Number of sessions per page.
813
+ */
814
+ pageSize: number;
815
+ };
816
+ /**
817
+ * SessionNotFoundError
818
+ * @description Error response when a session is not found
819
+ */
820
+ SessionNotFoundError: {
821
+ /**
822
+ * Detail
823
+ * @default Session not found
824
+ */
825
+ detail: string;
826
+ };
827
+ /**
828
+ * SessionResponse
829
+ * @description Represents a session and its current state.
830
+ *
831
+ * Poll this endpoint to track task progress. The `status` field indicates the session lifecycle stage,
832
+ * and `output` contains the agent's structured result once the task completes.
833
+ */
834
+ SessionResponse: {
835
+ /**
836
+ * Id
837
+ * Format: uuid
838
+ * @description Unique session identifier.
839
+ */
840
+ id: string;
841
+ /** @description Current session lifecycle status. Progresses through: `created` (sandbox starting) → `idle` (ready, waiting for task) → `running` (task executing) → `stopped` / `timed_out` / `error`. Poll this field to track progress. */
842
+ status: components["schemas"]["BuAgentSessionStatus"];
843
+ /** @description The model tier used for this session. */
844
+ model: components["schemas"]["BuModel"];
845
+ /**
846
+ * Title
847
+ * @description Auto-generated short title summarizing the task. Available after the task starts running.
848
+ */
849
+ title?: string | null;
850
+ /**
851
+ * Output
852
+ * @description The agent's final output. If `outputSchema` was provided, this will be structured data conforming to that schema. Otherwise it may be a free-form string or null. Populated once the task completes, regardless of whether `isTaskSuccessful` is true or false.
853
+ */
854
+ output?: unknown | null;
855
+ /**
856
+ * Outputschema
857
+ * @description The JSON Schema that was requested for structured output, if any.
858
+ */
859
+ outputSchema?: {
860
+ [key: string]: unknown;
861
+ } | null;
862
+ /**
863
+ * Stepcount
864
+ * @description Number of steps the agent has executed so far.
865
+ * @default 0
866
+ */
867
+ stepCount: number;
868
+ /**
869
+ * Laststepsummary
870
+ * @description Human-readable summary of the most recent agent step (e.g. "Clicking the Submit button"). Useful for showing real-time progress.
871
+ */
872
+ lastStepSummary?: string | null;
873
+ /**
874
+ * Istasksuccessful
875
+ * @description Whether the task completed successfully. `true` if the agent achieved the goal, `false` if it failed or gave up, `null` if the task is still running or no task was dispatched.
876
+ */
877
+ isTaskSuccessful?: boolean | null;
878
+ /**
879
+ * Liveurl
880
+ * @description URL to view the live browser session. Available immediately on session creation — can be embedded in an iframe to show the browser in real time.
881
+ */
882
+ liveUrl?: string | null;
883
+ /**
884
+ * Recordingurls
885
+ * @description URLs to download session recordings. Only populated if `enableRecording` was set to true and the task has completed.
886
+ * @default []
887
+ */
888
+ recordingUrls: string[];
889
+ /**
890
+ * Profileid
891
+ * @description ID of the browser profile loaded in this session, if any.
892
+ */
893
+ profileId?: string | null;
894
+ /**
895
+ * Workspaceid
896
+ * @description ID of the workspace attached to this session, if any.
897
+ */
898
+ workspaceId?: string | null;
899
+ /** @description Country code of the proxy used for this session, or null if no proxy. */
900
+ proxyCountryCode?: components["schemas"]["ProxyCountryCode"] | null;
901
+ /**
902
+ * Maxcostusd
903
+ * @description Maximum cost limit in USD set for this session.
904
+ */
905
+ maxCostUsd?: string | null;
906
+ /**
907
+ * Totalinputtokens
908
+ * @description Total LLM input tokens consumed by this session.
909
+ * @default 0
910
+ */
911
+ totalInputTokens: number;
912
+ /**
913
+ * Totaloutputtokens
914
+ * @description Total LLM output tokens consumed by this session.
915
+ * @default 0
916
+ */
917
+ totalOutputTokens: number;
918
+ /**
919
+ * Proxyusedmb
920
+ * @description Proxy bandwidth used in megabytes.
921
+ * @default 0
922
+ */
923
+ proxyUsedMb: string;
924
+ /**
925
+ * Llmcostusd
926
+ * @description Cost of LLM usage in USD.
927
+ * @default 0
928
+ */
929
+ llmCostUsd: string;
930
+ /**
931
+ * Proxycostusd
932
+ * @description Cost of proxy bandwidth in USD.
933
+ * @default 0
934
+ */
935
+ proxyCostUsd: string;
936
+ /**
937
+ * Browsercostusd
938
+ * @description Cost of browser compute time in USD.
939
+ * @default 0
940
+ */
941
+ browserCostUsd: string;
942
+ /**
943
+ * Totalcostusd
944
+ * @description Total session cost in USD (LLM + proxy + browser).
945
+ * @default 0
946
+ */
947
+ totalCostUsd: string;
948
+ /**
949
+ * Screenshoturl
950
+ * @description URL of the latest browser screenshot. This is a presigned URL that expires after 5 minutes. A new URL is generated each time you fetch the session.
951
+ */
952
+ screenshotUrl?: string | null;
953
+ /**
954
+ * Agentmailemail
955
+ * @description Temporary email address provisioned for this session (via AgentMail). Only present if `agentmail` was enabled.
956
+ */
957
+ agentmailEmail?: string | null;
958
+ /**
959
+ * Createdat
960
+ * Format: date-time
961
+ * @description When the session was created.
962
+ */
963
+ createdAt: string;
964
+ /**
965
+ * Updatedat
966
+ * Format: date-time
967
+ * @description When the session was last updated.
968
+ */
969
+ updatedAt: string;
970
+ };
971
+ /**
972
+ * SessionTimeoutLimitExceededError
973
+ * @description Error response when session timeout exceeds the maximum allowed limit
974
+ */
975
+ SessionTimeoutLimitExceededError: {
976
+ /**
977
+ * Detail
978
+ * @default Maximum session timeout is 4 hours (240 minutes).
979
+ */
980
+ detail: string;
981
+ };
982
+ /** StopSessionRequest */
983
+ StopSessionRequest: {
984
+ /**
985
+ * @description How to stop the session. Use "task" to stop only the current task and keep the session alive, or "session" to destroy the sandbox entirely.
986
+ * @default session
987
+ */
988
+ strategy: components["schemas"]["StopStrategy"];
989
+ };
990
+ /**
991
+ * StopStrategy
992
+ * @description Strategy for stopping a session.
993
+ *
994
+ * - `task`: Stop the currently running task but keep the session alive in idle state. You can dispatch another task to the same session afterwards.
995
+ * - `session`: Stop the session entirely and destroy the sandbox. The session cannot be reused after this.
996
+ * @enum {string}
997
+ */
998
+ StopStrategy: "task" | "session";
999
+ /**
1000
+ * TooManyConcurrentActiveSessionsError
1001
+ * @description Error response when user has too many concurrent active sessions
1002
+ */
1003
+ TooManyConcurrentActiveSessionsError: {
1004
+ /**
1005
+ * Detail
1006
+ * @default Too many concurrent active sessions. Please wait for one to finish, kill one, or upgrade your plan.
1007
+ */
1008
+ detail: string;
1009
+ };
1010
+ /**
1011
+ * UpdateBrowserSessionRequest
1012
+ * @description Request model for updating browser session state.
1013
+ */
1014
+ UpdateBrowserSessionRequest: {
1015
+ /**
1016
+ * Action
1017
+ * @description The action to perform on the session
1018
+ */
1019
+ action: components["schemas"]["BrowserSessionUpdateAction"];
1020
+ };
1021
+ /** ValidationError */
1022
+ ValidationError: {
1023
+ /** Location */
1024
+ loc: (string | number)[];
1025
+ /** Message */
1026
+ msg: string;
1027
+ /** Error Type */
1028
+ type: string;
1029
+ };
1030
+ /**
1031
+ * WorkspaceCreateRequest
1032
+ * @description Request model for creating a new workspace.
1033
+ */
1034
+ WorkspaceCreateRequest: {
1035
+ /**
1036
+ * Name
1037
+ * @description Optional name for the workspace
1038
+ */
1039
+ name?: string | null;
1040
+ };
1041
+ /**
1042
+ * WorkspaceListResponse
1043
+ * @description Response model for paginated workspace list requests.
1044
+ */
1045
+ WorkspaceListResponse: {
1046
+ /**
1047
+ * Items
1048
+ * @description List of workspace views for the current page
1049
+ */
1050
+ items: components["schemas"]["WorkspaceView"][];
1051
+ /**
1052
+ * Total Items
1053
+ * @description Total number of items in the list
1054
+ */
1055
+ totalItems: number;
1056
+ /**
1057
+ * Page Number
1058
+ * @description Page number
1059
+ */
1060
+ pageNumber: number;
1061
+ /**
1062
+ * Page Size
1063
+ * @description Number of items per page
1064
+ */
1065
+ pageSize: number;
1066
+ };
1067
+ /**
1068
+ * WorkspaceUpdateRequest
1069
+ * @description Request model for updating a workspace.
1070
+ */
1071
+ WorkspaceUpdateRequest: {
1072
+ /**
1073
+ * Name
1074
+ * @description Optional name for the workspace
1075
+ */
1076
+ name?: string | null;
1077
+ };
1078
+ /**
1079
+ * WorkspaceView
1080
+ * @description View model for a workspace — persistent shared storage across sessions.
1081
+ */
1082
+ WorkspaceView: {
1083
+ /**
1084
+ * ID
1085
+ * Format: uuid
1086
+ * @description Unique identifier for the workspace
1087
+ */
1088
+ id: string;
1089
+ /**
1090
+ * Name
1091
+ * @description Optional name for the workspace
1092
+ */
1093
+ name?: string | null;
1094
+ /**
1095
+ * Created At
1096
+ * Format: date-time
1097
+ * @description Timestamp when the workspace was created
1098
+ */
1099
+ createdAt: string;
1100
+ /**
1101
+ * Updated At
1102
+ * Format: date-time
1103
+ * @description Timestamp when the workspace was last updated
1104
+ */
1105
+ updatedAt: string;
1106
+ };
1107
+ };
1108
+ responses: never;
1109
+ parameters: never;
1110
+ requestBodies: never;
1111
+ headers: never;
1112
+ pathItems: never;
1113
+ }
1114
+
1115
+ type AccountView$1 = components["schemas"]["AccountView"];
1116
+ declare class Billing {
1117
+ private readonly http;
1118
+ constructor(http: HttpClient);
1119
+ /** Get account billing information. */
1120
+ account(): Promise<AccountView$1>;
1121
+ }
1122
+
1123
+ type CreateBrowserSessionRequest$1 = components["schemas"]["CreateBrowserSessionRequest"];
1124
+ type BrowserSessionItemView$1 = components["schemas"]["BrowserSessionItemView"];
1125
+ type BrowserSessionView$1 = components["schemas"]["BrowserSessionView"];
1126
+ type BrowserSessionListResponse$1 = components["schemas"]["BrowserSessionListResponse"];
1127
+ type UpdateBrowserSessionRequest$1 = components["schemas"]["UpdateBrowserSessionRequest"];
1128
+ interface BrowserListParams {
1129
+ page?: number;
1130
+ page_size?: number;
1131
+ }
1132
+ declare class Browsers {
1133
+ private readonly http;
1134
+ constructor(http: HttpClient);
1135
+ /** Create a standalone browser session. */
1136
+ create(body?: Partial<CreateBrowserSessionRequest$1>): Promise<BrowserSessionItemView$1>;
1137
+ /** List browser sessions for the authenticated project. */
1138
+ list(params?: BrowserListParams): Promise<BrowserSessionListResponse$1>;
1139
+ /** Get browser session details. */
1140
+ get(sessionId: string): Promise<BrowserSessionView$1>;
1141
+ /** Update a browser session (e.g. stop it). */
1142
+ update(sessionId: string, body: UpdateBrowserSessionRequest$1): Promise<BrowserSessionView$1>;
1143
+ /** Stop a browser session. Convenience wrapper around update. */
1144
+ stop(sessionId: string): Promise<BrowserSessionView$1>;
1145
+ }
1146
+
1147
+ type ProfileView$1 = components["schemas"]["ProfileView"];
1148
+ type ProfileListResponse$1 = components["schemas"]["ProfileListResponse"];
1149
+ type ProfileCreateRequest$1 = components["schemas"]["ProfileCreateRequest"];
1150
+ type ProfileUpdateRequest$1 = components["schemas"]["ProfileUpdateRequest"];
1151
+ interface ProfileListParams {
1152
+ query?: string;
1153
+ page?: number;
1154
+ page_size?: number;
1155
+ }
1156
+ declare class Profiles {
1157
+ private readonly http;
1158
+ constructor(http: HttpClient);
1159
+ /** Create a browser profile. */
1160
+ create(body?: ProfileCreateRequest$1): Promise<ProfileView$1>;
1161
+ /** List profiles for the authenticated project. */
1162
+ list(params?: ProfileListParams): Promise<ProfileListResponse$1>;
1163
+ /** Get profile details. */
1164
+ get(profileId: string): Promise<ProfileView$1>;
1165
+ /** Update a profile. */
1166
+ update(profileId: string, body: ProfileUpdateRequest$1): Promise<ProfileView$1>;
1167
+ /** Delete a profile. */
1168
+ delete(profileId: string): Promise<void>;
1169
+ }
1170
+
1171
+ type RunTaskRequest$2 = components["schemas"]["RunTaskRequest"];
1172
+ /** All fields optional — omit `task` to create an idle session. */
1173
+ type CreateSessionBody = Partial<RunTaskRequest$2>;
1174
+ type SessionResponse$2 = components["schemas"]["SessionResponse"];
1175
+ type SessionListResponse$1 = components["schemas"]["SessionListResponse"];
1176
+ type StopSessionRequest$1 = components["schemas"]["StopSessionRequest"];
1177
+ type MessageListResponse$1 = components["schemas"]["MessageListResponse"];
1178
+ interface SessionListParams {
1179
+ page?: number;
1180
+ page_size?: number;
1181
+ }
1182
+ interface SessionMessagesParams {
1183
+ after?: string | null;
1184
+ before?: string | null;
1185
+ limit?: number;
1186
+ }
1187
+ declare class Sessions {
1188
+ private readonly http;
1189
+ constructor(http: HttpClient);
1190
+ /** Create a session and optionally dispatch a task. */
1191
+ create(body?: CreateSessionBody): Promise<SessionResponse$2>;
1192
+ /** List sessions for the authenticated project. */
1193
+ list(params?: SessionListParams): Promise<SessionListResponse$1>;
1194
+ /** Get session details. */
1195
+ get(sessionId: string): Promise<SessionResponse$2>;
1196
+ /** Stop a session or the running task. */
1197
+ stop(sessionId: string, body?: StopSessionRequest$1): Promise<SessionResponse$2>;
1198
+ /** Soft-delete a session. */
1199
+ delete(sessionId: string): Promise<void>;
1200
+ /** List messages for a session with cursor-based pagination. */
1201
+ messages(sessionId: string, params?: SessionMessagesParams): Promise<MessageListResponse$1>;
1202
+ /**
1203
+ * Poll until recording URLs are available. Returns presigned MP4 URLs.
1204
+ *
1205
+ * Returns an empty array if no recording was produced (e.g. the agent
1206
+ * answered without opening a browser, or recording was not enabled).
1207
+ */
1208
+ waitForRecording(sessionId: string, options?: {
1209
+ timeout?: number;
1210
+ interval?: number;
1211
+ }): Promise<string[]>;
1212
+ }
1213
+
1214
+ type WorkspaceView$1 = components["schemas"]["WorkspaceView"];
1215
+ type WorkspaceListResponse$1 = components["schemas"]["WorkspaceListResponse"];
1216
+ type WorkspaceCreateRequest$1 = components["schemas"]["WorkspaceCreateRequest"];
1217
+ type WorkspaceUpdateRequest$1 = components["schemas"]["WorkspaceUpdateRequest"];
1218
+ type FileListResponse$1 = components["schemas"]["FileListResponse"];
1219
+ type FileUploadRequest$1 = components["schemas"]["FileUploadRequest"];
1220
+ type FileUploadResponse$1 = components["schemas"]["FileUploadResponse"];
1221
+ interface WorkspaceListParams {
1222
+ pageSize?: number;
1223
+ pageNumber?: number;
1224
+ }
1225
+ interface WorkspaceFilesParams {
1226
+ prefix?: string;
1227
+ limit?: number;
1228
+ cursor?: string | null;
1229
+ includeUrls?: boolean;
1230
+ shallow?: boolean;
1231
+ }
1232
+ declare class Workspaces {
1233
+ private readonly http;
1234
+ constructor(http: HttpClient);
1235
+ /** List workspaces for the authenticated project. */
1236
+ list(params?: WorkspaceListParams): Promise<WorkspaceListResponse$1>;
1237
+ /** Create a new workspace. */
1238
+ create(body?: WorkspaceCreateRequest$1): Promise<WorkspaceView$1>;
1239
+ /** Get workspace details. */
1240
+ get(workspaceId: string): Promise<WorkspaceView$1>;
1241
+ /** Update a workspace. */
1242
+ update(workspaceId: string, body: WorkspaceUpdateRequest$1): Promise<WorkspaceView$1>;
1243
+ /** Delete a workspace and its data. */
1244
+ delete(workspaceId: string): Promise<void>;
1245
+ /** List files in a workspace. */
1246
+ files(workspaceId: string, params?: WorkspaceFilesParams): Promise<FileListResponse$1>;
1247
+ /** Get presigned upload URLs for workspace files. */
1248
+ uploadFiles(workspaceId: string, body: FileUploadRequest$1, query?: {
1249
+ prefix?: string;
1250
+ }): Promise<FileUploadResponse$1>;
1251
+ /** Delete a file from a workspace. */
1252
+ deleteFile(workspaceId: string, path: string): Promise<void>;
1253
+ /** Get storage usage for a workspace. */
1254
+ size(workspaceId: string): Promise<unknown>;
1255
+ /**
1256
+ * Upload local files to a workspace. Returns the list of remote paths.
1257
+ *
1258
+ * ```ts
1259
+ * await client.workspaces.upload(wsId, "data.csv", "config.json");
1260
+ * await client.workspaces.upload(wsId, "data.csv", { prefix: "uploads/" });
1261
+ * ```
1262
+ */
1263
+ upload(workspaceId: string, ...args: (string | {
1264
+ prefix?: string;
1265
+ })[]): Promise<string[]>;
1266
+ /**
1267
+ * Download a single file from a workspace. Returns the local path.
1268
+ *
1269
+ * ```ts
1270
+ * const local = await client.workspaces.download(wsId, "uploads/data.csv", { to: "./data.csv" });
1271
+ * ```
1272
+ */
1273
+ download(workspaceId: string, path: string, options?: {
1274
+ to?: string;
1275
+ }): Promise<string>;
1276
+ /**
1277
+ * Download all files from a workspace. Returns list of local paths.
1278
+ *
1279
+ * ```ts
1280
+ * const paths = await client.workspaces.downloadAll(wsId, { to: "./output" });
1281
+ * ```
1282
+ */
1283
+ downloadAll(workspaceId: string, options?: {
1284
+ to?: string;
1285
+ prefix?: string;
1286
+ }): Promise<string[]>;
1287
+ }
1288
+
1289
+ type SessionResponse$1 = components["schemas"]["SessionResponse"];
1290
+ type MessageResponse$1 = components["schemas"]["MessageResponse"];
1291
+ interface RunOptions {
1292
+ /** Maximum time to wait in milliseconds. Default: 14_400_000 (4 hours). */
1293
+ timeout?: number;
1294
+ /** Polling interval in milliseconds. Default: 2_000. */
1295
+ interval?: number;
1296
+ /** @internal Starting message cursor for follow-up runs on an existing session. */
1297
+ _startCursor?: string;
1298
+ }
1299
+ /** Session result with typed output. All SessionResponse fields are directly accessible. */
1300
+ type SessionResult<T = string | null> = Omit<SessionResponse$1, "output"> & {
1301
+ output: T;
1302
+ };
1303
+ /**
1304
+ * Dual-purpose session handle: `await` it for a typed SessionResult,
1305
+ * or access `.result` for the full SessionResult after resolution.
1306
+ */
1307
+ declare class SessionRun<T = string> implements PromiseLike<SessionResult<T>> {
1308
+ private readonly _createPromise;
1309
+ private readonly _sessions;
1310
+ private readonly _schema?;
1311
+ private readonly _timeout;
1312
+ private readonly _interval;
1313
+ private readonly _options?;
1314
+ private _sessionId;
1315
+ private _result;
1316
+ constructor(createPromise: Promise<SessionResponse$1>, sessions: Sessions, schema?: z.ZodType<T>, options?: RunOptions);
1317
+ /** The session ID, available after task creation resolves. */
1318
+ get sessionId(): string | null;
1319
+ /** The full SessionResult, available after polling completes. */
1320
+ get result(): SessionResult<T> | null;
1321
+ /** Enable `await client.run(...)` — polls until terminal, returns SessionResult. */
1322
+ then<R1 = SessionResult<T>, R2 = never>(onFulfilled?: ((value: SessionResult<T>) => R1 | PromiseLike<R1>) | null, onRejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null): Promise<R1 | R2>;
1323
+ private _ensureSessionId;
1324
+ /** Poll session until terminal, return SessionResult. */
1325
+ private _waitForOutput;
1326
+ /**
1327
+ * Enable `for await (const msg of client.run(...))` — yields messages as they appear.
1328
+ * After iteration, `.result` contains the final SessionResult.
1329
+ */
1330
+ [Symbol.asyncIterator](): AsyncGenerator<MessageResponse$1>;
1331
+ private _parseOutput;
1332
+ }
1333
+
1334
+ type RunTaskRequest$1 = components["schemas"]["RunTaskRequest"];
1335
+ interface BrowserUseOptions {
1336
+ apiKey?: string;
1337
+ baseUrl?: string;
1338
+ maxRetries?: number;
1339
+ timeout?: number;
1340
+ }
1341
+ type RunSessionOptions = Partial<Omit<RunTaskRequest$1, "task">> & RunOptions & {
1342
+ schema?: z.ZodType;
1343
+ };
1344
+ declare class BrowserUse {
1345
+ readonly billing: Billing;
1346
+ readonly browsers: Browsers;
1347
+ readonly profiles: Profiles;
1348
+ readonly sessions: Sessions;
1349
+ readonly workspaces: Workspaces;
1350
+ private readonly http;
1351
+ constructor(options?: BrowserUseOptions);
1352
+ /**
1353
+ * Create a session and run a task. `await` the result for a typed SessionResult.
1354
+ *
1355
+ * ```ts
1356
+ * // Simple — just get the output
1357
+ * const result = await client.run("Find the top HN post");
1358
+ * console.log(result.output);
1359
+ *
1360
+ * // Structured output (Zod)
1361
+ * const result = await client.run("Find product info", { schema: ProductSchema });
1362
+ * console.log(result.output.name); // fully typed
1363
+ * ```
1364
+ */
1365
+ run(task: string, options?: Omit<RunSessionOptions, "schema">): SessionRun<string>;
1366
+ run<T extends z.ZodType>(task: string, options: RunSessionOptions & {
1367
+ schema: T;
1368
+ }): SessionRun<z.output<T>>;
1369
+ }
1370
+
1371
+ type S = components["schemas"];
1372
+ type SessionResponse = S["SessionResponse"];
1373
+ type SessionListResponse = S["SessionListResponse"];
1374
+ type FileListResponse = S["FileListResponse"];
1375
+ type FileInfo = S["FileInfo"];
1376
+ type FileUploadResponse = S["FileUploadResponse"];
1377
+ type FileUploadResponseItem = S["FileUploadResponseItem"];
1378
+ type MessageListResponse = S["MessageListResponse"];
1379
+ type MessageResponse = S["MessageResponse"];
1380
+ type WorkspaceView = S["WorkspaceView"];
1381
+ type WorkspaceListResponse = S["WorkspaceListResponse"];
1382
+ type RunTaskRequest = S["RunTaskRequest"];
1383
+ type StopSessionRequest = S["StopSessionRequest"];
1384
+ type FileUploadRequest = S["FileUploadRequest"];
1385
+ type FileUploadItem = S["FileUploadItem"];
1386
+ type WorkspaceCreateRequest = S["WorkspaceCreateRequest"];
1387
+ type WorkspaceUpdateRequest = S["WorkspaceUpdateRequest"];
1388
+ type BrowserSessionItemView = S["BrowserSessionItemView"];
1389
+ type BrowserSessionView = S["BrowserSessionView"];
1390
+ type BrowserSessionListResponse = S["BrowserSessionListResponse"];
1391
+ type CreateBrowserSessionRequest = S["CreateBrowserSessionRequest"];
1392
+ type UpdateBrowserSessionRequest = S["UpdateBrowserSessionRequest"];
1393
+ type BrowserSessionStatus = S["BrowserSessionStatus"];
1394
+ type BrowserSessionUpdateAction = S["BrowserSessionUpdateAction"];
1395
+ type ProfileView = S["ProfileView"];
1396
+ type ProfileListResponse = S["ProfileListResponse"];
1397
+ type ProfileCreateRequest = S["ProfileCreateRequest"];
1398
+ type ProfileUpdateRequest = S["ProfileUpdateRequest"];
1399
+ type AccountView = S["AccountView"];
1400
+ type PlanInfo = S["PlanInfo"];
1401
+ type BuAgentSessionStatus = S["BuAgentSessionStatus"];
1402
+ type BuModel = S["BuModel"];
1403
+ type ProxyCountryCode = S["ProxyCountryCode"];
1404
+ type StopStrategy = S["StopStrategy"];
1405
+
1406
+ export { type AccountView, Billing, type BrowserListParams, type BrowserSessionItemView, type BrowserSessionListResponse, type BrowserSessionStatus, type BrowserSessionUpdateAction, type BrowserSessionView, BrowserUse, type BrowserUseOptions, Browsers, type BuAgentSessionStatus, type BuModel, type CreateBrowserSessionRequest, type CreateSessionBody, type FileInfo, type FileListResponse, type FileUploadItem, type FileUploadRequest, type FileUploadResponse, type FileUploadResponseItem, type MessageListResponse, type MessageResponse, type PlanInfo, type ProfileCreateRequest, type ProfileListParams, type ProfileListResponse, type ProfileUpdateRequest, type ProfileView, Profiles, type ProxyCountryCode, type RunOptions, type RunSessionOptions, type RunTaskRequest, type SessionListParams, type SessionListResponse, type SessionMessagesParams, type SessionResponse, type SessionResult, SessionRun, Sessions, type StopSessionRequest, type StopStrategy, type UpdateBrowserSessionRequest, type components as V3Types, type WorkspaceCreateRequest, type WorkspaceFilesParams, type WorkspaceListParams, type WorkspaceListResponse, type WorkspaceUpdateRequest, type WorkspaceView, Workspaces };