RUN

Separate logins for every client.

A browser profile is a named set of saved logins with its own exit location. A run on a profile signs in with that profile's logins only, and saves any new sign-in back into it. Free on every plan.

Create a profile Create API key

Isolated

A profile run never sees your other logins, and its sign-ins never leak into Default.

No extension needed

Add logins by signing in inside a cloud run, or import a cookie file.

Same place, every run

Each profile keeps an exit location, pinned from its first sign-in if you set none.

Two kinds

Profiles and Default

Every account has Default. Named profiles are the ones you create.

In the Cloud app, the Logins chip under the composer switches profiles: create, rename, delete, and set the account default there. The pick is remembered in that browser. Picking a profile with a location moves the location chip to it.

REST

Profiles API

Base URL https://mcp.rtrvr.ai/v1/profiles. Use the same API key as /agent and /scrape (or an MCP OAuth token). Responses list names only: cookie values are never returned, and there is no export.

Request	Body	Returns
`POST /v1/profiles`	`{ name, location?, proxyId?, makeDefault? }`	`201 { profile }`
`GET /v1/profiles`	`—`	`{ profiles, defaultProfileId }`
`GET /v1/profiles/{id}`	`—`	`{ profile, sites } (names only)`
`PATCH /v1/profiles/{id}`	`{ name?, location?, proxyId?, makeDefault? }`	`{ profile }`
`DELETE /v1/profiles/{id}`	`—`	`{ deleted, sitesDeleted }`
`PUT /v1/profiles/{id}/state`	`a login file (see Import)`	`{ imported, sites, skipped, ignored }`
`DELETE /v1/profiles/{id}/sites/{site}`	`—`	`{ site, deleted, domains }`

namestringrequired

1 to 60 characters, unique on the account (case-insensitive). "Default" is reserved.

locationobject | null

Where runs on this profile exit: {country, region?, city?} in the same shape as settings.proxyConfig.location. null clears it.

proxyIdstring | null

The id of a proxy saved in Cloud Settings → Proxy Config. Runs on the profile use it instead of the managed proxy, so they keep the same IP.

makeDefaultboolean

true makes this the account default: API and MCP runs that name no profile use it. false on the current default goes back to Default.

Create a profile

curl -X POST https://mcp.rtrvr.ai/v1/profiles \
  -H "Authorization: Bearer rtrvr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Client A", "location": {"country": "US", "region": "NY", "city": "New York"}}'

Use it

Run on a profile

Pass profile (an id or the exact name, or "default") to POST /agent, POST /scrape, or the MCP cloud_agent and cloud_scrape tools.

Agent API on a profile

curl -X POST https://api.rtrvr.ai/agent \
  -H "Authorization: Bearer rtrvr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Download last month's invoices",
    "urls": ["https://billing.example.com/invoices"],
    "profile": "Client A"
  }'

MCP cloud_agent on a profile

{
  "name": "cloud_agent",
  "arguments": {
    "user_input": "Reply to the newest support ticket",
    "urls": ["https://support.example.com"],
    "profile": "Client A"
  }
}

profilestring

Omit it to use the account default profile (Default when none is set). A run that continues an earlier one stays on that run's profile.

session_sourceMCP only

Still works for one device's logins or "none". Pass profile or session_source, not both.

settings.proxyConfigobject

A route the request names wins over the profile's location or saved proxy.

The MCP result's logins names the profile a run used. Schedules run on the profile their saved request names, never on a later account default.

Bring your logins

Import a login file

Send the file to PUT /v1/profiles/{id}/state, or drop it on the Logins chip's Import box in the Cloud app. Each site in the file replaces that site's saved logins in the profile; other sites stay. Add "replace": true to clear every other site first.

Import

# A Playwright storageState file
curl -X PUT https://mcp.rtrvr.ai/v1/profiles/PROFILE_ID/state \
  -H "Authorization: Bearer rtrvr_your_api_key" \
  -H "Content-Type: application/json" \
  --data-binary @state.json

# A cookies.txt file
curl -X PUT https://mcp.rtrvr.ai/v1/profiles/PROFILE_ID/state \
  -H "Authorization: Bearer rtrvr_your_api_key" \
  -H "Content-Type: text/plain" \
  --data-binary @cookies.txt

# A Cookie header: say which page it was sent to
curl -X PUT https://mcp.rtrvr.ai/v1/profiles/PROFILE_ID/state \
  -H "Authorization: Bearer rtrvr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"content": "Cookie: session=...; csrftoken=...", "url": "https://app.example.com/"}'

Format	How to get it
Playwright `storageState` JSON	`await context.storageState({ path: "state.json" })` after signing in (snippet below). Its `localStorage` is not imported; the response says how many origins were left out.
Cookie-Editor or EditThisCookie JSON	Open the extension on the signed-in site and export as JSON.
Netscape `cookies.txt`	A "Get cookies.txt" style exporter, `curl -c`, or `yt-dlp --cookies`. `#HttpOnly_` lines are kept as HttpOnly.
DevTools "Copy as cURL"	Chrome DevTools → Network → reload the signed-in page → right-click its first request → Copy → Copy as cURL (bash or cmd). Paste it into "Paste from DevTools".
A `Cookie:` header + URL	The request's Cookie header from DevTools, with the page URL it was sent to.

Save a Playwright storageState

// After signing in with Playwright:
await context.storageState({ path: "state.json" })

// Or sign in by hand once, then save the state:
const browser = await chromium.launch({ headless: false })
const context = await browser.newContext()
const page = await context.newPage()
await page.goto("https://app.example.com/login")
// … sign in in the window that opened …
await context.storageState({ path: "state.json" })

Limits: 2 MB per file, 100 sites, 300 cookies per site, 30 imports per hour per account. Expired cookies are skipped. Each site gets a sign-in check from its cookie names, so you see right away which sites carry a login.

Look like the same visitor

Location pinning

Sites notice a login that hops between countries. A profile keeps where its runs exit.

Kept apart

How profile logins are stored

Cookie values and saved site logins are encrypted (AES-256-GCM) under a key of the profile's own, which Google Cloud KMS protects.
Names, sites and the sign-in check stay readable, so lists and the Logins chip work without decrypting anything.
Only cloud runs on that profile decrypt them. Lists and the API return names only, and there is no export.

YOUR NEXT RUN

Run the example on a real site.

Use Chrome for the page in front of you. Use Cloud when the run should continue on a schedule or across many pages.