Browser profiles

Use optional sharedParams.profile to scrape pages behind a website login. Subscribing to any paid plan enables browser profiles for your organization.

Create a profile

Set type to new and provide the website’s username or email and password. Context discovers the sign-in flow from your target URL, verifies authentication, and saves the session. Passwords are never stored in the profile. Send this body to POST /web/scrape. See the Quickstart for authentication and SDK setup.

{
  "url": "https://example.com/account",
  "formats": {
    "html": true,
    "markdown": true
  },
  "sharedParams": {
    "profile": {
      "type": "new",
      "identifier": "YOUR_WEBSITE_USERNAME",
      "password": "YOUR_WEBSITE_PASSWORD"
    }
  },
  "timeoutOpts": {
    "milliseconds": 120000
  }
}

Save the returned profile.id:

"profile": { "id": "prof_0123456789abcdef0123456789abcdef" }

The response contains profile: null when you omit sharedParams.profile. New and existing profile requests both return the profile ID.

Reuse a profile

Set type to existing and pass the saved ID as profileId. Credentials are unnecessary for reuse. Send this body to POST /web/scrape. See the Quickstart for authentication and SDK setup.

{
  "url": "https://example.com/account",
  "formats": {
    "markdown": true
  },
  "sharedParams": {
    "profile": {
      "type": "existing",
      "profileId": "prof_0123456789abcdef0123456789abcdef"
    }
  }
}

Profiles belong to your organization and remain usable after API-key rotation. A different organization cannot access them. Use one request at a time per profile; concurrent use returns PROFILE_BUSY.

Handle expiry

When Context confirms that the website session has expired, it deletes the profile and returns HTTP 422:

{
  "message": "The saved login expired and the profile was removed. Submit login credentials again.",
  "error_code": "PROFILE_SESSION_EXPIRED"
}

Create a new profile with credentials, then replace the old ID with the new profile.id. Context cannot sign in again automatically because the password is not saved.

Error	HTTP	Action
`PROFILE_SESSION_EXPIRED`	`422`	Create a new profile. The expired profile was deleted.
`PROFILE_REAUTHENTICATION_REQUIRED`	`422`	Create a new profile. The pinned proxy or browser identity is no longer usable.
`PROFILE_NOT_FOUND`	`410`	Create a new profile or check the ID and organization.
`PROFILE_BUSY`	`409`	Wait for the other request to finish before reusing the profile.
`PROFILE_INVALID_CREDENTIALS`	`422`	Correct the website credentials.
`PROFILE_INTERACTION_REQUIRED`	`422`	The site requires an interactive step, such as MFA or CAPTCHA.
`PROFILE_AUTHENTICATION_UNKNOWN`	`422`	Authentication could not be verified. The saved profile is preserved.
`REQUEST_TIMEOUT`	`408`	Retry with a longer timeout. A timeout preserves the saved profile.

Constraints

Target URLs must use HTTPS and stay within the profile’s permitted origins.
Browser profiles bypass shared caches and use private request logging. They persist session state, so zdr: "enabled" is unsupported.
Custom headers, raw bytes, iframe capture, popup dismissal, image enrichment, visual image deduplication, filtered image outputs, and product image deduplication are unsupported with profiles.
Keep the viewport, theme, and proxy settings compatible with the saved profile. Profile viewports are 320–3840 pixels wide and 240–2160 pixels high.
Residential proxy identities expire after 30 minutes. Static ISP identities remain pinned while their endpoint is available.
MFA, CAPTCHA, passkeys, popup login, and HTTP authentication are unsupported. Cross-origin sign-in discovery is automatic.

You can combine profiles with browser actions and waiting and rendering. See the request and response reference for the complete contract.

Get started

Web data

Company and people data

Automation

Account and billing

Production

Create a profile

Reuse a profile

Handle expiry

Constraints

​Create a profile

​Reuse a profile

​Handle expiry

​Constraints

Create a profile

Reuse a profile

Handle expiry

Constraints