Profiles

Profiles allow you to persist user data—such as storage, cookies, cache, and login states—across multiple sessions. This enables smoother automation, simplified authentication, and optimized performance.

Core Advantages

Reuse Browser History: Users can reuse their browsing history across sessions.
Maintain Login Status: Stay logged into certain sites to reduce the need for repeated authentication.
Improve Page Load Speed: Enhance the loading speed of web pages.
Reduce Risk of Bot Detection: Lower the chances of being identified as a bot.

Using Profiles

1. Create a Profile

First, create a new profile using the Profiles API. Take note of the profile_id that is returned; you will use this to assign the profile to a new session.

import { ScrapelessClient } from '@scrapeless-ai/sdk';
 
const client = new ScrapelessClient({ apiKey: 'API Key' });
const createResponse = await client.profiles.create('My Profile');
console.log('Profile created:', createResponse);

2. Use a Profile

Once a profile is created, you can add it to a new session to reuse its data. Assign the profile by including the profile_id in your session configuration.

import { ScrapelessClient } from '@scrapeless-ai/sdk';
 
const client = new ScrapelessClient({ apiKey: 'API Key' });
const { browserWSEndpoint } = client.browser.create({
    session_name: 'My Browser',
    session_ttl: 30000,
    profile_id: 'your-profile-id',
});
 
(async () => {
    const browser = await puppeteer.connect({browserWSEndpoint});
    const page = await browser.newPage();
    await page.goto('https://www.scrapeless.com');
    console.log(await page.title());
    await browser.close();
})();

If you want the new session to update the profile data, you must set profile_persist: true within the profile object. This should be done the first time you use a new profile in a session to ensure that its data can be saved for subsequent use.

const { browserWSEndpoint } = client.browser.create({
    session_name: 'My Browser',
    session_ttl: 30000,
    profile_id: 'your-profile-id',
    profile_persist: true,
});

Why Use persist?

By default, a context will load the data saved from a previous session but will not update it. If you need to store new cookies, authentication tokens, or cached data, you must set profile_persist: true when creating the session. The data will be saved when the session is closed. This ensures that any changes made during the session—such as logging in, saving site preferences, or caching assets—are preserved for future sessions and are not lost when the session ends.

3. Retrieve Profiles

You can fetch a specific profile by its ID or list all the profiles you have created using query parameters. Please refer to the Profile API reference for the complete schema and parameters.

// get a specific profile
const profile = await client.profiles.get('your-profile-id');
 
// get profile list
const profiles = await client.profiles.list({ page: 1, pageSize: 10 });

Note

When profile_persist: true is enabled, only the data from the last session to close will be saved.

If you want multiple sessions to share the same profile, the default setting profile_persist: false allows you to use the previous profile configuration across multiple sessions without making any changes. If you wish to update the profile within these sessions, you will need to enable persistence.

const { browserWSEndpoint } = client.browser.create({
    session_name: 'My Browser',
    session_ttl: 30000,
    profile_id: 'your-profile-id',
});

Note: When profile_persist: true is enabled, only the data from the last session to close will be saved.

5. Delete Profiles

Delete unused profiles to free up resources. Once deleted, a profile can no longer be attached to any session.

const deleteResponse = await client.profiles.delete('your-profile-id');

👉 For examples and code samples related to profiles, please visit Product Updates | New Profile Feature.

Devtools Custom Fingerprint