> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Profiles

> Save a browser session's cookies and logins under a name, then open later sessions with them so you stay signed in. Create, list, rename and delete profiles.

A profile keeps a session's cookies and local storage under a name. Open a session with that name and it starts where the last one stopped, signed in. A profile is saved when the session closes.

## Save a login

Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart). Open a session with `profile.name`. If no profile has that name, one is created.

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/browser \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ttl": 300,
    "activityTtl": 60,
    "profile": { "name": "shop-login" }
  }'
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/browser", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ttl: 300,
    activityTtl: 60,
    profile: { name: "shop-login" },
  }),
});
const session = await response.json();
console.log(session.id);
```

```python Python theme={null}
import os

import requests

response = requests.post(
    "https://api.stophy.dev/v1/browser",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={
        "ttl": 300,
        "activityTtl": 60,
        "profile": {"name": "shop-login"},
    },
)
session = response.json()
print(session["id"])
```

Sign in the way you normally would: [run code](https://docs.stophy.dev/browser/execute.md) that fills the form, or drive the session over CDP. This example sets a cookie, which is what a login leaves behind.

```json theme={null}
{
  "code": "await page.goto('https://httpbin.org/cookies/set?session=abc123');\nreturn await page.locator('body').innerText();"
}
```

The real answer had `result` set to `{"cookies": {"session": "abc123"}}`. Now [close the session](https://docs.stophy.dev/browser/overview#close-a-session). The profile is saved as the session closes, so close it before you open another session with the same profile.

## Read the profile

`GET /v1/browser/profiles/{name}` shows what the profile holds. It is free.

```bash theme={null}
curl https://api.stophy.dev/v1/browser/profiles/shop-login \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

```json theme={null}
{
  "success": true,
  "name": "shop-login",
  "cookies": 1,
  "origins": 0,
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "159e0372-43c4-4ed0-8300-ed449b6098bf"
}
```

`cookies` counts the saved cookies. `origins` counts the sites with saved local storage.

## Reuse the profile

Open a session with the same name. Send `saveChanges: false` to use the profile without changing it, for a read-only visit.

```json theme={null}
{
  "ttl": 300,
  "activityTtl": 60,
  "profile": { "name": "shop-login", "saveChanges": false }
}
```

Code that reads the cookies returned the same value in the new session.

```json theme={null}
{
  "code": "await page.goto('https://httpbin.org/cookies');\nreturn await page.locator('body').innerText();"
}
```

The real `result` was `{"cookies": {"session": "abc123"}}`. The profile stays logged in across sessions, and `saveChanges: false` left it as it was.

A profile keeps the country it first used. Send `location.country` with a profile that already has one, and the session opens anyway, in the profile's country, with a `warning`. This real session asked for `DE`:

```json theme={null}
{
  "success": true,
  "id": "b6ef8ac9-e687-49fc-b483-0d66e010161c",
  "warning": "This profile keeps its own exit, so location.country DE was not used; the session exits in US."
}
```

See [Network location](https://docs.stophy.dev/browser/network-location.md). A scrape and a batch take the same `profile` field with the same names, so a login you save in a session also works there. See [Scrape](https://docs.stophy.dev/scrape/overview).

## Manage profiles

| Action | Call | Notes |
| - | - | - |
| Create an empty profile | `POST /v1/browser/profiles` with `{ "name": "shop-login" }` | Free. A session opened with a new name creates one too. |
| List | `GET /v1/browser/profiles` | Free. Most recently used first. |
| Read | `GET /v1/browser/profiles/{name}` | Free. |
| Rename | `PATCH /v1/browser/profiles/{name}` with `{ "name": "shop-login-2026" }` | Free. Keeps cookies and logins. |
| Delete | `DELETE /v1/browser/profiles/{name}` | Free. |

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/browser/profiles \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "shop-login" }'
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/browser/profiles", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "shop-login" }),
});
console.log(await response.json());
```

```python Python theme={null}
import os

import requests

response = requests.post(
    "https://api.stophy.dev/v1/browser/profiles",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={"name": "shop-login"},
)
print(response.json())
```

A new profile is empty.

```json theme={null}
{
  "success": true,
  "name": "shop-login",
  "cookies": 0,
  "origins": 0,
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "c7aad6a9-70e9-4aa1-8bb5-fc4e08edce37"
}
```

The list holds each profile's `name` and when it was `lastUsedAt`. This real list came after a rename.

```json theme={null}
{
  "success": true,
  "data": {
    "profiles": [
      { "name": "shop-login-2026", "lastUsedAt": "2026-11-17T18:17:47.465Z" }
    ]
  },
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "c1eb0aca-9449-4a77-add0-89e3acfc2c25"
}
```

A rename answers with the profile under its new name. A delete answers `{ "success": true }` and the profile is gone, with its cookies. A profile is also removed 30 days after it was last used.

## Options

| Field | Type | Default | Effect |
| - | - | - | - |
| `profile.name` | `string` | none | The profile to load and save, 1 to 200 characters. Required inside `profile`. |
| `profile.saveChanges` | `boolean` | `true` | `false` loads the profile and does not save the session's changes. Chosen per session, not stored on the profile. |

## Limits and errors

* Only one session at a time can save to a profile. A second one returns `409 profileBusy`, which is retryable. Wait for the first to close, or send `saveChanges: false`.
* A profile too large to save returns `413 profileTooLarge`.
* Creating a name that exists returns `409 invalidRequest` with `A browser profile with that name already exists.` Renaming to a taken name, or while a session saves to the profile, returns `409 invalidRequest` too.
* A name that does not exist returns `404 notFound` with `No browser profile with that name.`
* `profile` with `zeroDataRetention` returns `400 invalidRequest`: `zeroDataRetention keeps nothing from the session, and a profile keeps its cookies. Send one of them.`

## Related

* [Browser sessions](https://docs.stophy.dev/browser/overview) opens and closes the session that saves the profile.
* [Network location](https://docs.stophy.dev/browser/network-location.md) explains the country a profile keeps.
* [Extensions](https://docs.stophy.dev/browser/extensions.md) adds a Chrome extension to a session.
* [Profile reference](https://docs.stophy.dev/api-reference/endpoint/browser-profile-create.md) lists every field.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.