Profiles

Returns a page of profile summaries for a project, ordered by sort — alphabetically by name unless you say otherwise. Each row carries its live status, so a separate status call per profile is never needed. Note that the app's own list defaults to most-recently-used instead, so an unsorted call here and the Profiles screen will not be in the same order; pass sort=lastRunAt to match the screen.

Creates a profile with a freshly generated, coherence-checked fingerprint. Anything you leave out is generated or defaulted, so an empty body is valid — POST /profiles with {} is a working call. Passing count creates a batch in one call and numbers the names, because five hundred profiles sharing one name is unusable.

Two things exist so an automation needs no setup calls. projectId is optional and falls back to the system project, so you do not have to look one up. And proxy takes a plain proxy string, attached to this profile alone and saved nowhere — so a script does not have to POST /proxies first, and the Proxies page does not fill up with one row per rotating session. The shortest useful call is {"proxy":"user:pass@gw.example.com:9000"}.

A profile created with a proxy is drawn for that proxy’s exit. The proxy is measured before the identity is generated, and the country, timezone, languages and geolocation come from the address it really leaves by — so you do not pass countryCode, and you should not guess one. Until this existed, the same pasted European gateway produced America/New_York on one call and America/Chicago on the next: two draws from a share-weighted table, which is what no match looks like from outside. The lookup is cached per exact exit for five minutes, so count: 500 costs one request.

Every response carries exitMatch, always. matched: true means a measured exit decided the locale. matched: false names the reason — a gateway that did not answer, matchExit: false, or a countryCode you passed yourself, which still wins. The profiles are created either way: a dead proxy is not a reason to hand back nothing. It is the one field that separates a batch that is right from a batch that is silently wrong, and they were byte-identical before it.

A batch on one proxy is allowed, and said. With count > 1, a pasted line, a ProxyConfig or a proxyId puts every profile in the batch behind one address. That is the operator’s choice and is not refused — but sites can link accounts that share an address, so the response carries a warnings entry { code: "shared-exit", profiles, message } naming how many now share it. A provider ({"providerId": …}) mints one session, and so one exit, per profile, and is the recommended way to put a batch behind proxies. warnings is always present, empty when nothing is worth saying.

The complete profile, including the full fingerprint, privacy flags, companion settings, start options, cookies and extension list. This is what you would edit and send back to PATCH.

Merges the fields you send. Anything touching how the browser launches — fingerprint, proxy, privacy, start options, extensions, extra arguments, cookies — is refused while the profile is running, because those values were baked into the process at launch and changing them would either be ignored or corrupt the session. Stop the profile first. companion is the exception: it is read by the built-in extension, which is rebuilt on every launch, so a change is accepted at any time and applies from the next start. Its fields are autoRetry (default true — reload a page that failed to load), autoRetrySeconds (default 10) and autoRetryLimit (default 3, per address, reset by a successful load).

Stops the profile if it is running, then moves it to the trash with its browser data intact. Nothing is destroyed: it stays restorable for 30 days and is purged on the first start after that. Use the trash endpoints to restore or purge immediately. A browser that will not close is a 400 naming the profile, and the profile stays on the list — a trashed row has no Stop button, so hiding a running window behind one is the worse outcome.

Copies settings, extensions and start pages. By default the copy gets a brand-new identity, because a duplicate is a different machine — two profiles sharing one fingerprint is exactly the correlation an anti-detect browser exists to prevent. Pass newFingerprint: false only when you deliberately want a clone.

Promotes a profile’s pasted, not-yet-saved proxy into the Proxies library and links the profile to it, so the same address can be reused and edited in one place. Refused by name when there is nothing to save: a profile already on a saved proxy, a profile with no proxy, or a provider-minted session — that last one is one launch’s session id, not a reusable address, and saving it would pin many profiles behind one exit.

Writes a shortcut that opens this one profile: a small app bundle on macOS, a .lnk on Windows, a .desktop file on Linux, wearing the project’s colour and glyph. Opening it starts the profile’s browser without the Mosaic window — Mosaic runs in the background for as long as the browser is open (the proxy relay, the cookie key and the clean shutdown live there) and quits when it closes. If Mosaic is already running, the shortcut hands the profile to it instead. Making a shortcut again for the same profile in the same place replaces the earlier one, including after a rename. A file of somebody else’s at the same name is left alone and the new one takes a suffix. The shortcut is removed when the profile is purged — not when it is trashed, because a trashed profile can come back.

Reassigns profiles to one project. Nothing about a profile changes except which project it belongs to — the fingerprint, proxy, cookies, logins and history are untouched, and a running browser keeps running. Tag names travel and are registered in the destination project, because a tag’s colour is a row owned by a project: without that a moved profile keeps its tag words and silently loses their colours. A profile already in the target is not counted as moved, and one whose file cannot be read comes back in missing rather than being silently skipped — this used to answer { moved: ids.length } whatever happened.

Applies tag changes across many profiles. Adds and removals are applied in that order, so a tag in both lists ends up removed.

The general-purpose bulk operation: one change set, applied to every profile in ids. Every field is optional and every list is additive or subtractive against what each profile already has, so this never silently replaces a collection — adding a bookmark that a profile already has is a no-op rather than a duplicate, and omitting a field leaves it untouched. The common mistake is expecting startPages to append: it replaces, because start pages are a short deliberate set. Use addStartPages to add to what is there. A profile that cannot be written is reported in failures and the rest of the batch still runs.

Empties the browser caches — the HTTP cache, code cache, GPU and shader caches, the same directories an export leaves out — and nothing else. Cookies, logins, local storage, IndexedDB, history and extensions stay, so the profile is still signed in everywhere it was. For shrinking a profile and for clearing a stale cached script without logging out. Refused while the profile runs: Chromium holds those files open, and the profile is never stopped on your behalf.

The route above over a list. A running profile is skipped, by name, rather than failing the batch or being stopped; anything that could not be cleared is in failures with its reason. By id: there is no form of this that means all of them.

Stops each profile if running, then moves it to the trash. Reversible, like every other delete. A browser that will not close keeps its profile on the list — a trashed row has no Stop button, so hiding a running window behind one is the worse outcome — and it is named in failures rather than counted away.

Launches each profile in turn with a pause between them. Sequential on purpose, and that is a correctness point rather than politeness. POST /profiles/:id/start refuses when maxConcurrentProfiles is already reached, and it counts sessions that are still starting as well as running — so forty parallel requests would every one read the count before any had registered, all pass the check, and quietly exceed the cap the operator set. Awaiting each launch is what makes that setting mean what it says. The pause matters on its own too: every launch spawns a browser with its own renderer, GPU process and network service, and twenty at once is how a laptop stops responding. A profile that is already up is skipped, not a failure; one that cannot start costs that row and nothing else.

Closes each through Browser.close, so Chromium flushes its cookie jar rather than being killed mid-write. Concurrent, unlike starting: there is no cap on stopping and nothing to protect — every one of these is already holding the resources it is about to release. A profile that is not running is skipped.