To get started with the PhantomBuster API, create an API key in your workspace settings, enable developer mode for additional API views, and test your first request using the built-in API reference. The API lets you launch Phantoms, retrieve results, and manage workspace data like LinkedIn Leads and lead lists.
Looking to connect PhantomBuster with another tool?
See our integration guides: Clay | n8n | Make | Zapier
This article covers the PhantomBuster developer API for building custom workflows.
How the PhantomBuster API and API reference work
The PhantomBuster API lets you control Phantoms and workspace data, including launches, results, and settings.
The API reference is a built-in interface that lets you explore and test API requests before using them from your own tools.
Think of the API reference as a safe testing environment where you can:
- See available endpoints.
- Understand required parameters.
- Test requests using your API key.
- Copy working requests to reuse elsewhere.
We strongly recommend testing every request in the API reference first, then reusing the same request from your own tool or automation.
How to read the API reference
This section helps you understand how the API reference is organized, so you know where to look depending on what you want to do.
When you open the PhantomBuster API reference, endpoints are grouped by what they act on.
Main endpoint categories
-
Agents → Phantoms
Used to create, launch, update, or fetch a Phantom.
-
Containers → Phantom launches
Used to retrieve logs, execution details, and result information for a specific run.
-
Storage → Workspace data
Used to manage stored data in your workspace, such as:
- LinkedIn Leads
- Lead lists
- Lead and company objects
API tasks involve Agents and Containers. Storage endpoints are mainly used when working with the LinkedIn Leads database, for example to delete leads, manage lists, or sync data with external tools.
What you’ll see on each endpoint page
Every endpoint page in the API reference follows the same general layout:
- The HTTP method (GET or POST)
- Fields you can fill in (query parameters or body parameters)
- A Credentials section (this is where your API key goes)
- A Try it button to test the request
- A request example you can copy and reuse in your own tools
- The API response returned by the request
You don’t need to understand every field to get started. Most guides will tell you which parameters you need to fill in for a given task.
What the PhantomBuster API can’t do
The PhantomBuster API lets you run and control Phantoms, but some actions aren’t supported.
- Workflows can’t be launched using the API:
Workflows are designed to run automatically based on their saved configuration. Because of this, they can’t be reliably triggered or controlled through API calls.
If you need to run a multi-step process via API, the recommended approach is to chain individual Phantoms and launch each one separately using the API.
- Result files can’t be deleted via API:
Result files created by Phantoms can’t be removed through API calls and must be managed from your PhantomBuster Dashboard.
What you need before using the API
Before you start using the PhantomBuster API, make sure:
- The Phantom you want to run is already set up in your PhantomBuster Workspace.
- Developer mode is enabled (optional, but useful to access additional API-related views in your Workspace).
- You have a valid API key.
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.
Enable developer mode
Developer mode unlocks additional API-related views in your PhantomBuster Workspace that help you understand and test API requests.
When developer mode is enabled, you can:
- Access the API view from a Phantom’s console.
- Access the Agent object view for a Phantom.
These views let you inspect API endpoints, parameters, and objects related to that Phantom.
How to enable developer mode
- Open your PhantomBuster Workspace, and hover over your name in the upper right corner of the page. → If you have more than one Workspace, make sure you select the right one.
- Then, under your My Space section, select My personal settings.
- Scroll to the Advanced Settings dropdown, click Enable developer mode, and then on Save settings.
Create an API key
Your API key is used to prove that each API request comes from your PhantomBuster Workspace.
API keys can only be created and managed inside your PhantomBuster Workspace, and only by workspace admins. If you don't see the Add API key button, check with your admin.
- Open your PhantomBuster Workspace, and hover over your name in the upper right corner of the page. → If you have more than one Workspace, make sure you select the right one.
- Then, under your Technical section, select API keys.
- Click Add API key and copy the API key.
→ Store it somewhere secure to use it in the API reference.
Where you’ll see it used
In the API reference, every endpoint includes a Credentials section with the X-Phantombuster-Key field.
→ This header is required for all endpoints, including agent, container, and storage requests.
Treat your API key like a password. Anyone with access to it can run Phantoms in your Workspace.
Understand the IDs used in API calls
When working with the PhantomBuster API, you’ll mainly see two types of IDs.
Agent ID (Phantom ID)
An Agent ID identifies which Phantom the API request applies to.
- It always refers to the Phantom itself.
- It does not change over time.
- It’s required for most endpoints in the Agents section.
→ You’ll use an Agent ID whenever an API request needs to reference a specific Phantom.
To find your Agent ID
Open your PhantomBuster Dashboard, click the Phantom you want to work with, and copy the number that appears after /phantoms in the URL.
→ Learn how to find your Agent ID for API calls.
Container ID (launch ID)
A Container ID identifies a single launch of a Phantom.
- A new Container ID is created every time the Phantom runs
- It refers to one execution, not the Phantom itself
- It’s used when retrieving logs, results, or execution details
→ You’ll see Container IDs mainly in the Containers section of the API reference. There is one exception: the /containers/fetch-all endpoint uses an Agent ID to retrieve all launches for a Phantom, rather than a single Container ID.
To find your Container ID
Open your PhantomBuster Dashboard, click on the Phantom you want to use. Then go to the Activity tab, and click View log for the run you want to inspect. Copy the number that appears at the end of the URL.
→ Learn how to locate your Container ID for API calls.
Frequently asked questions
Do I need a paid plan to use the API?
Yes. The PhantomBuster API is available on all paid plans. You need a valid API key from your PhantomBuster Workspace to authenticate requests.
Can I launch Workflows through the API?
No. Workflows run based on their saved configuration and can't be triggered via API. To run a multi-step process, chain individual Phantoms and launch each one separately.
What's the difference between an Agent ID and a Container ID?
An Agent ID identifies a Phantom and stays the same over time. A Container ID identifies a single launch of that Phantom and changes with every run.
Can I delete result files through the API?
No. Result files must be managed from your PhantomBuster Dashboard.
Where do I find the API reference?
The API reference is at hub.phantombuster.com/reference. It lets you explore endpoints, test requests with your API key, and copy working examples.