How to use a different session cookie for a single Phantom launch via API

To run a Phantom with a different session cookie for one API launch only, pass the session cookie (and user agent for LinkedIn Phantoms) in the bonusArgument field of the POST /agents/launch endpoint. This overrides the Phantom's saved authentication for that single run without changing its configuration.

Before you start

Before launching a Phantom with a specific session cookie via API, make sure:

• You have a valid API key.
  → If you don't have one, see Create an API key. API keys can only be created by Workspace admins, if you don't see the Add API key button, check with your admin.
• You know the Agent ID of the Phantom you want to launch.
• You already have a valid session cookie.
• For LinkedIn Phantoms only:
  • You also have the matching user agent from the same browser session.

→ If any of these are missing, start with Get started with the PhantomBuster API and Before You Start: How Account Connections Work in PhantomBuster.

How this works

By default, when you launch a Phantom via API, it runs using the input and settings saved in your PhantomBuster Dashboard.

To override authentication for one launch only, you can pass a session cookie (and a user agent for LinkedIn Phantoms) using the bonusArgument field in your API request.

When you do this, PhantomBuster temporarily applies the values provided in bonusArgument only for that API request, while keeping the Phantom’s saved setup unchanged.

• Manual launches always use the Phantom’s saved configuration.
• API launches use whatever is sent in the request.
• If bonusArgument is included again in a future API call, the same override will apply again.

This behavior makes it possible to run the same Phantom with different accounts across API launches, without modifying its saved setup. 
This is done using the standard POST /agents/launch endpoint.

Launch a Phantom with a specific session cookie (and user agent) from the API reference

Step 1: Open the launch endpoint

1. Open the PhantomBuster API reference.
2. In the left menu, go to:
   PhantomBuster API v2 → Agents → POST /agents/launch

Step 2: Add your API key

1. In the top-right corner of the page, locate the Credentials section.
2. Paste your API key into the X-Phantombuster-Key header.

Step 3: Fill in the required fields

In the Body params section:

• id

  → Paste the Agent ID of the Phantom you want to launch

  

• bonusArgument → String:

  → Use this field to pass the session cookie override for this launch only. For LinkedIn Phantoms, the session cookie and user agent must come from the same browser session, or the launch will fail.

  → Make sure the value:

  • Is valid JSON
  • Uses curly brackets

  → How you obtain these values (via the extension or manual connection) is explained in How to update a Phantom’s session cookie via API and in the account connection guides.

Step 4: Send the request

• Click Try it

If the request is successful:

• The API returns a 200 status.
• A Container ID is returned for this launch.
• The run appears in your Phantom’s Activity tab.

→ This confirms the Phantom ran using the specified session cookie.

Frequently asked questions

Does this change the Phantom's saved session cookie? 

No. The override applies only to that specific API launch. Manual launches and future API launches without bonusArgument still use the saved cookie.

Do I need to include a user agent? 

Only for LinkedIn and Sales Navigator Phantoms. The session cookie and user agent must come from the same browser session, or the launch will fail.

Can I reuse the same override across multiple API launches? 

Yes. Include the same bonusArgument in each API request. Each launch applies the override independently.

What if I want to permanently switch the account? 

Use the /agents/save endpoint instead. See How to update a Phantom's session cookie via API.