How to change Phantom input for a single API launch

To change a Phantom's input for a single API launch without modifying its saved setup, use the bonusArgument field in the POST /agents/launch endpoint. Set the input field name as the key and the new value as the value. The override applies only to that launch, the Phantom's saved configuration stays unchanged.

While this guide focuses on changing input values (such as URLs or spreadsheets), the same mechanism can technically be used to override other Phantom arguments for a single launch. In practice, we recommend using this method (bonusArgument) primarily for input changes. Overriding other settings is less common and easier to misconfigure.

How changing input for a single launch works

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

To change the input for one launch only (and more generally, to override specific Phantom settings for a single run), you can include an additional field called bonusArgument in your API request.

When you do this:

• PhantomBuster takes the saved setup of the Phantom and temporarily replaces or adds the values provided in bonusArgument for this launch.
• It runs the Phantom with that combined configuration.

On the next manual launch, the Phantom always uses its saved setup.
For API launches, the Phantom uses whatever is sent in the request. If bonusArgument is included again, the same override will apply.

This is done using the standard POST /agents/launch endpoint.

Using bonusArgument to override a session cookie

If your goal is to run the same Phantom with a different account for one launch only, you can also pass a sessionCookie (and userAgent for LinkedIn Phantoms) via bonusArgument.

For step-by-step instructions and best practices, see How to use a different session cookie for a single Phantom launch via API.

Before you start

Before changing Phantom input for a single API launch, make sure:

• The Phantom you want to run is already set up in your PhantomBuster Workspace.
• You know the Agent ID of the Phantom you want to launch.
• 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 which input field you want to override and the new value you want to use for this launch

We also recommend launching the Phantom manually at least once. This helps confirm that the setup is correct before you start triggering it via the API.

→ If any of these are missing, start with How to Get Started with the PhantomBuster API and How to Use Phantom Arguments in the PhantomBuster API.

Step 1: Identify the input field you want to override

Each Phantom expects specific input fields.

When using bonusArgument, you must use the exact same field name the Phantom expects.

To find it:

1. Open your PhantomBuster Workspace and open the Phantom you want to launch.
2. Open its setup and switch to JSON view (Clicking the three-dot menu in the top-right corner).
3. Locate the input field you want to change. For example:
   • LinkedInSearchUrl
   • spreadsheetUrl
   • profileUrl

You’ll reuse this field name exactly in the next step.

Step 2: Add the temporary input in the API reference

To override the input for this launch, you’ll now add a bonusArgument field to the launch request in the API reference.

1. Open the PhantomBuster API reference.

2. In the left menu, go to:

   PhantomBuster API v2 → Agents → POST /agents/launch

3. Add your API Key in the Credentials section.
4. And in the Body params section:
   • Make sure the id field contains the Agent ID of your Phantom.
   • Scroll to the field named bonusArgument.

This field is used to pass temporary input values for this launch only.

How to fill bonusArgument

For most use cases, the Object option is the recommended way to change input for a single launch.

It makes it clear which field is being overridden and avoids modifying the rest of the Phantom’s setup.

Recommended: Object (single-field override)

Use this option when you want to change one specific input value for this launch.

1. Select bonusArgument → Object
2. Click Add field.
3. Enter:
   • newKey → The exact input field name you identified in Step 1.
   • newValue → The new value to use for this launch.

Example:

Step 3: Send the request

• In the Request box on the right-hand side, click Try it to launch the Phantom.
  
• If the request is successful:
  • The API returns a 200 status.
  • The response includes a Container ID, which uniquely identifies this launch.

→ This confirms that:

• The Phantom was launched successfully.
• The temporary input provided in bonusArgument was used for this run.

Step 4: View the API launch in your PhantomBuster dashboard

After triggering a launch via API, the run appears directly in PhantomBuster, just like a manual launch.

You can access it in either of these ways:

Option 1: From your PhantomBuster Dashboard

1. Open the Phantom in your PhantomBuster Dashboard.
   
2. Go to the Activity tab and locate the new API call. 
   

Option 2: Using the Container ID

Use the Container ID returned by the API to open that specific launch directly by pasting it into your browser’s address bar.

On the next manual launch, the Phantom always uses its saved setup.
For API launches, the Phantom uses whatever is sent in the request. If bonusArgument is included again, the same override will apply.

Watch the video tutorial

Frequently asked questions

Does bonusArgument permanently change the Phantom's setup?

No. The override applies only to that specific launch. On the next manual launch, the Phantom uses its saved setup. On the next API launch, it depends on whether bonusArgument is included again.

Can I override multiple fields at once?

Yes, but it's recommended to use bonusArgument primarily for input changes. Overriding other settings is possible but less common and easier to misconfigure.

Can I use bonusArgument to change the session cookie for one launch?

Yes. You can pass a sessionCookie (and userAgent for LinkedIn Phantoms) via bonusArgument to run the Phantom with a different account for one launch.

How do I find the correct field name to override?

Open the Phantom's setup in your PhantomBuster Dashboard, switch to JSON view, and locate the input field name you want to change. Use that exact name as the key in bonusArgument.