Phantom arguments are the JSON key-value pairs that define a Phantom's input data and settings when using the PhantomBuster API. To get the correct arguments for any Phantom, copy them from the JSON view in the Phantom's setup or from the API tab in the Phantom console. Arguments are required when creating, updating, or launching a Phantom through the API.
What arguments are
Arguments define how a Phantom is configured and how it behaves when used through the API.
They represent the input values and settings that a Phantom uses, whether you are:
- Creating or updating a Phantom (/agents/save), or
- Launching a Phantom (/agents/launch)
Arguments contain the same data you configure in the PhantomBuster Dashboard, such as:
- Input data (URLs, spreadsheets, CSV files, lists).
- Connected accounts (LinkedIn, Sales Navigator, Instagram, etc.).
- Phantom-specific settings and options.
When using the API, these values are sent as arguments instead of being entered manually in the UI.
If arguments are missing or incorrect, the Phantom may fail or not behave as expected. That’s why we recommend testing the Phantom manually from your PhantomBuster Workspace first, then reusing the same setup when launching it via the API.
How arguments are structured
Arguments are sent as JSON in API requests. At a technical level, they follow a key–value structure:
- Each key matches a Phantom input field name exactly.
- Each value contains the data or setting the Phantom should process.
Depending on the Phantom, a value can be:
- A single URL (for example, one LinkedIn profile or company URL).
- A Google Sheet or public CSV URL.
- A list of URLs, if the Phantom explicitly supports multiple inputs.
Input field names and accepted formats vary by Phantom. The API doesn’t infer or correct input logic.
Even if you don’t always edit arguments field by field, this is the structure the API expects under the hood. The safest way to get the correct structure is to copy it from the Phantom itself.
How to get the correct arguments for a Phantom
There are two supported ways to get the correct arguments structure, and both reflect the Phantom’s actual expected input.
Option 1: Copy arguments from the JSON view
- Open your Phantom in your PhantomBuster Dashboard.
- Click the three-dot menu to access the Phantom’s setup.
- Click the three-dot menu in the top-right corner and click Switch to JSON.
→ You’ll see the full configuration of your Phantom in JSON format. - Copy the entire JSON block.
→ This JSON block can be reused as-is in API requests.
Option 2: Use the API tab in the Phantom console
This option is available only if developer mode is enabled.
- Open your Phantom in your PhantomBuster Dashboard.
- Click the three-dot menu to access the Phantom’s setup.
- Click the three-dot menu in the top-right corner and select API.
This opens the API call snippets panel, where you can:
- See a ready-to-use API request for launching this Phantom.
- Switch between programming languages (Node, Python, etc.).
- Copy a request that already includes:
- The correct launch endpoint
- The Agent ID for this Phantom
- The required request headers
- Optionally include the current Phantom arguments by enabling Send with current arguments.
→ You can copy this request and reuse it in the API reference or your own tool replacing the API key.
Where to provide arguments in the API reference
In endpoints like /agents/launch or /agents/save, arguments are provided in the Body params section, under the field named argument.
In the API reference UI, this field offers two options:
- String
- Object
Both send arguments to the API, but they are used differently.
Option 1: String (full JSON block)
The String option sends the entire arguments object at once, exactly as JSON.
When to use it
- Reusing a setup that already works.
- Launching or creating a Phantom with multiple inputs.
- Avoiding mistakes with field names.
How to use it
- Select argument → String
- Paste the full JSON block copied earlier.
Option 2: Object (individual fields)
The Object option lets arguments be built field by field.
When to use it
- Sending or overriding one specific input.
- Passing a single URL.
- Injecting dynamic values from another tool.
How to use it
- Select argument → Object
- Click Add field.
- Enter:
- newKey = The exact input field name.
- newValue = The value to process.
Example:
| Type | Description |
|---|---|
| linkedInSearchUrl | https://www.linkedin.com/search/results/people/?keywords=pennylane&origin=FACETED_SEARCH&geoUrn=["105015875"]¤tCompany=["65390433"]&profileLanguage=["fr"] |
Always rely on the JSON view or API tab to confirm the correct structure.
Frequently asked questions
Where do I find the correct arguments for my Phantom?
Open the Phantom in your PhantomBuster Dashboard, click the three-dot menu, then switch to JSON view. The full JSON block can be copied and reused directly in API requests. Alternatively, enable developer mode and use the API tab in the Phantom console.
What happens if I send incorrect or missing arguments?
The Phantom may fail or behave unexpectedly. Always test the Phantom manually in your Workspace first, then reuse the same configuration via the API.
Should I use the String or Object option in the API reference?
Use String when you want to paste a full JSON block with all arguments at once. Use Object when you only need to send or override one specific field, like a single URL or a dynamic value from another tool.
Do all Phantoms use the same arguments?
No. Each Phantom has its own set of input fields. The field names and accepted formats vary by Phantom, so always copy the arguments from the Phantom itself rather than guessing.