# Profiles

Source: https://docs.scrappey.com/docs/profiles

> Attach a `profileId` to any request to maintain a consistent browser configuration, cookies, proxy, and session data across all future requests using that profile.

## Overview

Persistent profiles solve a common challenge: maintaining a stable, reproducible browser environment across requests. Each profile stores:

- **Browser configuration** - Canvas, WebGL, fonts, screen size, user agent, and 50+ other browser properties
- **Cookies** - All cookies are automatically saved and restored
- **Session data** - localStorage and other session information
- **Proxy & IP** - The proxy and IP address used with this profile (automatically remembered)

Once created, a profile's configuration never changes. This gives you a stable, reproducible browser environment every time you use that profile — useful for consistent QA runs, monitoring, and session continuity. Unlike a [`sessions.create`](/docs/sessions-create) session, which expires after ~200 seconds, a profile persists indefinitely.

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `profileId` | string | Yes | Unique identifier for the profile. Use any string (alphanumeric, hyphens, underscores). |
| `proxy` | string | No | Your proxy URL. If provided, it is saved to the profile and used for all future requests. |
| `forceNewProxy` | boolean | No | When `true`, ignores the stored proxy and assigns a fresh one. The new proxy replaces the old one. |

## Request

Add `profileId` to your request to use a persistent profile:

```bash
curl -X POST "https://publisher.scrappey.com/api/v1?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cmd": "request.get",
    "url": "https://example.com",
    "profileId": "my-profile-123"
  }'
```

If the profile does not exist it is automatically created with a unique browser configuration. All subsequent requests with the same `profileId` will reuse that exact configuration.

### First Request (Profile Creation)

```json
{
  "cmd": "request.get",
  "url": "https://browserleaks.com/canvas",
  "profileId": "account-store-001"
}
```
- A new browser configuration is generated and permanently saved
- A proxy is automatically assigned and saved to the profile
- The browser launches with this configuration and proxy
- Any cookies set by the website are saved when the session ends

### Subsequent Requests (Profile Reuse)

```json
{
  "cmd": "request.get",
  "url": "https://example.com/account",
  "profileId": "account-store-001"
}
```
- The saved configuration is loaded (100% identical to first request)
- The saved proxy is automatically used (same IP address)
- Saved cookies are injected into the browser
- The site sees the same consistent browser environment as before

## Use Cases

### Account Management

Maintain separate, isolated browser environments for different accounts:

```json
{
  "cmd": "request.get",
  "url": "https://example.com",
  "profileId": "email-account-1"
}
```

Give each account its own `profileId` (e.g. `email-account-2`) so their configurations, cookies, and proxies stay fully isolated.

### Session Persistence

Stay logged in across requests without re-authenticating:

```json
{
  "cmd": "request.get",
  "url": "https://mystore.example.com/admin",
  "profileId": "my-store"
}
```

Reuse the same `profileId` on follow-up requests (e.g. `https://mystore.example.com/admin/orders`) to keep the session alive.

### Consistent Environment

Present a stable, returning-visitor environment for sites that expect session continuity:

```json
{
  "cmd": "request.get",
  "url": "https://site-with-fingerprinting.com",
  "profileId": "research-browser"
}
```

## Best Practices

### Profile Naming

Use descriptive, consistent naming:

```
account-{platform}-{identifier}    → account-store-john
session-{purpose}-{id}             → session-scraping-batch42
```

### One Profile Per Identity

Each unique identity should have its own profile.

### Profile Isolation

Two users with the same `profileId` get completely separate profiles and data.

## Configuration Consistency

Every property of the browser environment remains identical across sessions, which makes runs reproducible:

| Component | Consistency |
|-----------|-------------|
| Canvas fingerprint | 100% identical |
| WebGL renderer/vendor | 100% identical |
| Audio fingerprint | 100% identical |
| Font list | 100% identical |
| Screen dimensions | 100% identical |
| User agent | 100% identical |
| Platform/OS | 100% identical |
| Timezone | 100% identical |
| Language | 100% identical |

## Proxy Persistence

Profiles automatically remember the proxy used during their session, so a profile maintains a consistent IP location across requests. This provides session continuity — the same browser environment and the same regional proxy every time.

### With Your Own Proxy

```json
{
  "cmd": "request.get",
  "url": "https://example.com",
  "profileId": "my-profile",
  "proxy": "http://user:pass@proxy.example.com:8000"
}
```
- Your proxy is saved to the profile
- All future requests automatically use this proxy
- If the proxy stops working, you'll get an error asking you to provide a new one

### Without a Proxy (Automatic Assignment)

```json
{
  "cmd": "request.get",
  "url": "https://example.com",
  "profileId": "my-profile"
}
```
- A proxy is automatically assigned and saved to the profile
- All future requests use the same proxy (same IP)
- If the proxy stops working, a new one is automatically assigned

### Subsequent Requests

Once a profile has a proxy saved, just use the profile — no proxy needed:

```json
{
  "cmd": "request.get",
  "url": "https://example.com",
  "profileId": "my-profile"
}
```

The saved proxy is automatically used.

### Proxy Use Cases

#### Consistent IP + Environment

```json
{
  "cmd": "request.get",
  "url": "https://example.com",
  "profileId": "account-1"
}
```

Repeat with the same `profileId` to reuse the same IP and browser environment on every request.

#### Stable Sessions

```json
{
  "cmd": "request.get",
  "url": "https://example.com",
  "profileId": "email-main"
}
```

#### Using Your Own Proxy

```json
{
  "cmd": "request.get",
  "url": "https://target.com",
  "profileId": "scraper-1",
  "proxy": "http://user:pass@your-proxy.com:8000"
}
```

Later requests with the same `profileId` (e.g. `https://target.com/page1`) reuse the saved proxy automatically — no need to send it again.

#### Update the Proxy

```json
{
  "cmd": "request.get",
  "url": "https://example.com",
  "profileId": "my-profile",
  "proxy": "http://new-proxy:8000"
}
```

#### Force a New Proxy

```json
{
  "cmd": "request.get",
  "url": "https://example.com",
  "profileId": "my-profile",
  "forceNewProxy": true
}
```

### Why Use Proxy Persistence?

| Benefit | Description |
|---------|-------------|
| IP Consistency | Maintains the same browser environment and regional IP across requests |
| Simpler Requests | Proxy is automatically handled — no need to manage it yourself |
| Stable Sessions | Avoids session resets caused by IP changes mid-workflow |
| Automatic Recovery | If an internal proxy fails, a new one is automatically assigned |

## Limitations

- Profiles are permanent once created — the browser configuration cannot be changed
- Maximum profile storage depends on your plan
- Very large cookie stores (>10MB) may impact performance

## FAQ

**Q: What happens if I don't specify a profileId?**
A: A temporary browser with a randomly generated configuration is used. Nothing is persisted.

**Q: Can I delete a profile?**
A: Yes, contact support or use the profile management API.

**Q: How long are profiles stored?**
A: Indefinitely, unless you delete them.

**Q: Do profiles work with proxies?**
A: Yes. Proxies are automatically saved and reused with profiles. The browser configuration stays the same regardless of which proxy you use.

**Q: Will a site recognize the same profile across requests?**
A: Yes — a profile provides a consistent browser environment, so the site sees a stable returning visitor rather than a brand-new environment on every request. This is the intended behavior for maintaining sessions.

**Q: What happens if my proxy stops working?**
A: If you provided your own proxy, you'll get an error asking you to provide a new one. If you're using an automatically assigned proxy, a new one is automatically assigned.

**Q: Can I use a profile without any proxy?**
A: Profiles always use a proxy to ensure consistent IP addresses. If you don't provide one, one is automatically assigned.

**Q: How do I change the proxy for an existing profile?**
A: Use `forceNewProxy: true` to assign a new proxy, or provide your own `proxy` URL. The new proxy replaces the stored one.

## Related concepts

Go deeper in the [Scrappey knowledge base](https://scrappey.com/qa):

- [Stateful web scraping](https://scrappey.com/qa/web-scraping-apis/what-is-stateful-web-scraping) — reusing state across requests
- [Browser fingerprinting](https://scrappey.com/qa/web-scraping-apis/what-is-browser-fingerprinting) — the client signature a profile pins
- [Browser environment consistency](https://scrappey.com/qa/anti-bot/what-is-browser-fingerprinting-evasion) — why stable profiles matter for repeatable browser workflows