Computer setup

Wake a user's computer before they need it.

Send Authorization: Bearer vk_test_... on every call. Every route of Computer setup.

POST/v1/users/{user_id}/browser/fetchOpen one page in a background tab of the user's own browser, with no model, and get back the bodies of the page's own data calls that match capture.

Only on sites the user's deployment lists in browser.allowed_domains (403 domain_not_allowed), and never on a page in its browser.blocked_paths, such as a payment page (403 page_blocked). Wakes the computer when it sleeps. Answers as soon as every required capture has its responses, with timings; 409 browser_in_use while a person drives the browser, 409 browser_busy past four at once; 504 timeout carries what came back in partial. frames returns small pictures of the tab at each milestone. A page_fetch step calls one of the deployment's sites from inside the page, as the page's own script would; keep_open_ms keeps the tab for the next fetch, which sends no url (409 no_open_tab when none is kept).

Your API key, scope runtime or all. On the card: users. Every call here is a checked sample.

Request15 fields

Path

user_idstringrequiredYour own id for the user, as you named them.

Type: string

Body

urlstring (URL)The page to open, http or https, on a site the user's deployment allows (browser.allowed_domains). Absent: the steps run on the tab an earlier fetch kept open (keep_open_ms), as it is; 409 no_open_tab when none is kept.

Limits: At most 4000 characters.
Example: https://www.ixigo.com/search/result/flight?from=DEL&to=GOI&date=06112026&adults=4&class=e

captureobject[]The responses to keep, up to 10. The fetch answers as soon as every step is done and every required capture has its responses. Absent: none, for a fetch made of page_fetch steps.

Limits: At most 10 items.

matchstringrequiredPart of the address of a response to keep, such as /api/v3/search: a finished response whose address contains it is kept. Ending in $, it must end the path instead (the query aside), so /v3/services$ keeps /v3/services and not /v3/services/meta/105.

Limits: 1 to 500 characters.
Example: /flights/v2/search/stream

requiredbooleanWhether the fetch waits for it. Default true: the fetch answers as soon as every required capture has min_count responses. false: kept if it comes before then, never waited for.

Type: boolean

min_countintegerHow many responses a required capture waits for, 1 to 10. Default 1. A page that loads its second page by itself (hotels) needs 2.

Limits: 1 to 10.

max_countintegerThe most responses it keeps, 1 to 10. Default min_count, or 1.

Limits: 1 to 10.

max_bytesintegerThe most bytes of each body to keep, up to 1048576, or up to 4194304 with sse "last". Default 524288; a longer body comes back cut, with truncated true.

Limits: 1 to 4194304.

sse"last"For an event stream (text/event-stream) whose every event is the whole answer so far: "last" keeps only its last complete event, as a stream of that one event, and max_bytes is that event's limit. When the last event is past max_bytes, or the stream ends partway through one, the newest complete event that fits comes back instead, with truncated true. A body that is not an event stream is kept as it is. Absent: the body as it came.

Type: "last"

stepsobject[]What to do on the page after it opens, in order, up to 20. Absent: nothing; the page is only opened.

Limits: At most 20 items.

framesobjectSmall pictures of the tab as it works: when the page first shows, when each required capture arrives, after each step, every 0.7 s, and at the end. At most 6 and about 400 KB in all. Absent: none.

widthintegerHow wide each frame is, in pixels: 160 to 1280. Default 640.

Limits: 160 to 1280.

settle_msintegerOnce every required capture is in, keep taking frames, labelled results, about every 170 ms for this long while the page draws what came, then answer: 0 to 700 ms. A page can blank for a moment as it draws; a run of frames catches the drawn one. Default 0: answer at once, and the last frame may still show the page loading.

Limits: 0 to 700.

timeout_msintegerHow long the page may take, from when it starts opening, in ms: 1000 to 20000. Default 8000. Waking the computer comes on top.

Limits: 1000 to 20000.

grace_msintegerOnce every required capture has its min_count, wait up to this long for every capture to fill to its max_count, optional ones too, then answer with what came: 0 to 3000 ms. Default 0: answer at once.

Limits: 0 to 3000.

keep_open_msintegerKeep this fetch's tab open on its page this long after it answers, with the computer awake, so the next fetch with no url runs there at once: 0 to 600000 ms. Default 0.

Limits: 0 to 600000.

tabstringWhich kept tab: keep_open_ms keeps this tab under the name, and a fetch with no url takes the tab of that name. Up to 4 are kept. Default default.

Example: stays

tagstringYour label for this fetch; the browser watch names its tab with it.

Type: string

frontbooleanA hand-off the person finishes themselves, such as a sign-in: the tab's window opens in front of theirs, maximized, with the keyboard, and with keep_open_ms stays there for them. Default false: behind their window.

Type: boolean

front_device"phone" | "desktop"With front: phone (default) or desktop, the site's desktop page, as the other fetches see it, at a phone's shape (440 wide, as high as the window): a sign-in service's tab it opens draws into the same part of the screen, so a session's screen shows one rectangle whatever is in front.

Type: "phone" | "desktop"

front_cropobjectOn a hand-off (front, or a fetch with no url on its kept tab): a session's screen shows only this element of the page, such as a site's sign-in dialog at a phone's size. From a front fetch's start until the element is on the page, the screen answers crop_pending instead of a crop, for up to 20 seconds; past that it shows the page as before.

rolestringThe element's accessibility role, such as dialog.

Limits: 1 to 40 characters.
Example: dialog

namestringIts accessible name, exactly.

Limits: 1 to 200 characters.

textstringWords its accessible name contains.

Limits: 1 to 200 characters.

stagebooleanIn front, in one kept tab (tab), shown alone in the watch.

Type: boolean

privatebooleanNever shown in the browser watch, and no frames taken: a person's own account page, say.

Type: boolean

Answers 2008 fields

final_urlstring | nullThe page's address when the fetch ended, after any redirects and steps; null if it never opened.

Type: string | null

elapsed_msintegerHow long the whole call took, in ms, waking included.

Type: integer

wokebooleantrue when the computer was asleep and this call woke it.

Type: boolean

timingsobjectWhere the time went, each in ms after the call arrived.

wake_msintegerHow long waking the computer took: 0 when it was up.

Type: integer

nav_msinteger | nullWhen the page started showing (its navigation committed); null if it never did, or when the fetch ran on a kept tab with nothing to open.

Type: integer | null

first_capture_msinteger | nullWhen the first kept response finished; null if none did.

Type: integer | null

done_msintegerWhen the computer finished the fetch.

Type: integer

capturesobject[]Every response kept, in the order they finished.

matchstringThe capture this response answers, or the page_fetch step's capture_as.

Type: string

urlstringThe full address of the response.

Type: string

statusintegerIts HTTP status.

Type: integer

content_typestring | nullIts content type, such as application/json; null when it had none.

Type: string | null

bodystringIts body, as text.

Type: string

truncatedbooleantrue when the body was longer than max_bytes, or the fetch had kept 8000000 bytes in all, and it was cut. With sse "last": true when the event kept is not the stream's last one (the last was too long, or the stream ended partway through it).

Type: boolean

at_msintegerWhen it finished, in ms after the call arrived.

Type: integer

framesobject[]may be absentWith frames asked: the pictures, in the order they were taken. A frame that would have slowed the answer is left out.

labelstringWhich moment: navigated, captured <match>, after <step> or done.

Example: navigated

at_msintegerWhen it was taken, in ms after the call arrived.

Type: integer

page_urlstringThe page's address when it was taken; always on an allowed site.

Type: string

jpeg_base64stringThe picture, a JPEG, as base64.

Type: string

stepstringmay be absentWith a timeout: where the fetch was when the time ran out: navigate, a step by its number and op such as 2 scroll, or captures when every step was done and it was waiting for the required captures.

Example: 2 scroll

challenge"turnstile"may be absentturnstile: the page called Cloudflare's Turnstile check.

Type: "turnstile"

HTTP

# Create a user. Do it before their first ask to set their name and time zone. It is safe to repeat with the# same user_id.curl "$VESTRA_BASE_URL/v1/users" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "user_id": "traveller-42", "name": "Priya Sharma", "timezone": "Asia/Kolkata" }' # Read their spend. Their profile shows what they spent today and this month, against their caps.curl "$VESTRA_BASE_URL/v1/users/traveller-42" \  -H "Authorization: Bearer $VESTRA_API_KEY" # Set a monthly cap. This one is 20 US dollars.curl -X PATCH "$VESTRA_BASE_URL/v1/users/traveller-42" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "monthly_cap_usd": 20 }' # Wake their computer. Do it before they need it.curl -X POST "$VESTRA_BASE_URL/v1/users/traveller-42/warm" \  -H "Authorization: Bearer $VESTRA_API_KEY" # Open a page in their browser with no model, and keep the page's own data calls. The site must be in their# deployment's browser.allowed_domains.curl -X POST "$VESTRA_BASE_URL/v1/users/traveller-42/browser/fetch" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "url": "https://www.ixigo.com/search/result/flight?from=DEL&to=GOI&date=06112026&adults=2&class=e", "capture": [{ "match": "/flights/v2/search/stream" }] }' # Erase a user. It runs as a job: the response is 202 with deleted false and status deleting, and then# user.deleted says it is done.curl -X DELETE "$VESTRA_BASE_URL/v1/users/traveller-42" \  -H "Authorization: Bearer $VESTRA_API_KEY"

MCP

{  "method": "tools/call",  "params": {    "name": "users_get",    "arguments": { "user": "traveller-42" }  }}

HTTP

No sample in your language for this route, so here it is over HTTP.

# Create a user. Do it before their first ask to set their name and time zone. It is safe to repeat with the# same user_id.curl "$VESTRA_BASE_URL/v1/users" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "user_id": "traveller-42", "name": "Priya Sharma", "timezone": "Asia/Kolkata" }' # Read their spend. Their profile shows what they spent today and this month, against their caps.curl "$VESTRA_BASE_URL/v1/users/traveller-42" \  -H "Authorization: Bearer $VESTRA_API_KEY" # Set a monthly cap. This one is 20 US dollars.curl -X PATCH "$VESTRA_BASE_URL/v1/users/traveller-42" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "monthly_cap_usd": 20 }' # Wake their computer. Do it before they need it.curl -X POST "$VESTRA_BASE_URL/v1/users/traveller-42/warm" \  -H "Authorization: Bearer $VESTRA_API_KEY" # Open a page in their browser with no model, and keep the page's own data calls. The site must be in their# deployment's browser.allowed_domains.curl -X POST "$VESTRA_BASE_URL/v1/users/traveller-42/browser/fetch" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "url": "https://www.ixigo.com/search/result/flight?from=DEL&to=GOI&date=06112026&adults=2&class=e", "capture": [{ "match": "/flights/v2/search/stream" }] }' # Erase a user. It runs as a job: the response is 202 with deleted false and status deleting, and then# user.deleted says it is done.curl -X DELETE "$VESTRA_BASE_URL/v1/users/traveller-42" \  -H "Authorization: Bearer $VESTRA_API_KEY"