How to launch a Phantom via API

To launch a Phantom via the PhantomBuster API, send a POST request to the /agents/launch endpoint with the Phantom's Agent ID and your API key. The Phantom runs using its saved configuration by default. You can optionally override input arguments at launch time, but arrays aren't supported, use a file-based input or launch once per item instead.

Before you start

Before launching a Phantom via API, make sure:

• The Phantom is fully set up and has been launched successfully at least once from your PhantomBuster Dashboard.
• 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.

→ If any of these are missing, start with Get started with the PhantomBuster API.

How an API launch works

Launching a Phantom via API always works the same way.

• PhantomBuster uses a single launch endpoint to trigger Phantom runs.
• The request can be sent from:
  • The API reference (to test and validate it),
  • An external tool or system (to automate it).

Only the source of the request changes, the Phantom runs the same way in all cases, using the same authentication and input.

API input limitations: arrays are not supported

When launching a Phantom via API, you can't send arrays (for example, a list of LinkedIn URLs) as input parameters.

If you need to process multiple items, you must either:

• Launch the Phantom multiple times (one item per launch), or
• Use a file-based input such as a spreadsheet, if the Phantom supports it.

Launch a Phantom from the API reference (testing)

The API reference is a testing environment used to validate requests before running them from external tools.

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, locate the Credentials section.
2. In the Header, where you see X-Phantombuster-Key, paste your API key.

Step 3: Add the Agent ID and arguments

1. In the center of the page, locate the Body params section.
2. In the id field, paste your Agent ID (How to find your Agent ID for API calls).
   → That’s all you need to trigger a launch, the API automatically reuses the Phantom’s saved setup.

Step 4: 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 response returns:
  • A 200 status.

  • A Container ID, this is the unique ID, for this specific launch.

    

Step 5: 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.

→ If you want to receive notifications for API-triggered launches, make sure notifications are enabled in your workspace settings.

Frequently asked questions

Do I need to provide arguments when launching via API?

No. If you only provide the Agent ID, the Phantom launches with its saved setup. Arguments are only needed if you want to override the existing configuration for that specific run.

Can I send a list of URLs in one API launch?

No. The API doesn't support arrays as input. To process multiple items, either launch the Phantom once per item or use a file-based input like a Google Sheet or CSV.

How do I know if the launch was successful?

A successful request returns a 200 status and a Container ID for that specific run. You can use the Container ID to retrieve logs or results.

Can I launch Workflows via API?

No. Only individual Phantoms can be launched through the API. If you need a multi-step process, chain individual Phantoms and launch each one separately.