PhantomBuster API: Versions, Keys and What It Does Not Change

The PhantomBuster API's authentication header is X-Phantombuster-Key-1, the key is displayed exactly once when you create it, and the documentation says so directly: "your key will only be shown once, on creation. You better copy it in a safe place before refreshing or leaving the page." Fetched from the vendor's documentation hub on 16 August 2026.

That is the tone of the whole API reference, which is unusually plain-spoken for vendor documentation, and it is the reason this surface is worth writing about separately from the product. The docs tell you what the API does. What they do not tell you, because no vendor can, is what the platforms underneath will tolerate.

What the API controls

The API gives programmatic control over a PhantomBuster workspace rather than over LinkedIn directly, which is an important distinction. You are driving the automations; the automations are what touch the platform.

The documented capabilities: launch and abort agents, read console output including a real-time stream, read status, progress and messages from a running agent, retrieve user account, agent and script records, create and update scripts, retrieve a Phantom's result files as CSV or JSON, and create and update lead lists using filters through a documented POST /api/v2/org-storage/lists/save endpoint.

There is also a documented MCP server for giving AI tools scoped access to automations and data, and webhook support for reacting to runs rather than polling them.

The mechanics, exactly as published

Versioning and formatTwo live versions

• Endpoints formed as https://phantombuster.com/api/<version>/<path>
• Both v1 and v2 are live; v2 is current
• Date and time fields are Unix timestamps
• Seconds on v1 endpoints, milliseconds on v2
• v1 responses follow the JSend specification
• Successful v1 responses are 2XX with a status and data envelope

AuthenticationOne key, one header

• API key created in Workspace settings
• Key shown once on creation and not retrievable afterwards
• Sent in the X-Phantombuster-Key-1 header
• A key query-string parameter also works
• The docs discourage the query string because keys reach logs and caches
• The docs advise regenerating and deleting a key if it may be compromised

ErrorsDocumented codes

• 400 for a missing or wrong parameter
• 401 for a missing or wrong API key
• 404 for an object that was not found
• 500 for a server-side failure
• Error responses carry a status and message, sometimes a code and data field
• Payloads may go in the query string or a POST body

Two practical notes follow from that table. The seconds-against-milliseconds split between v1 and v2 is the kind of detail that produces timestamps a thousand times wrong in a chart, and it is worth pinning down at the start of any integration. And the once-only key display means key rotation is a deliberate operation with a small window, so it belongs in your secret store before it belongs in a script.

The plain-text documentation trick worth knowing

PhantomBuster's documentation hub is served by a platform that publishes Markdown twins of every page. Appending .md to a docs path returns clean text rather than a JavaScript-rendered page, and the site advertises an llms.txt index at the hub root listing every page with its description.

That matters practically. The rendered documentation is heavy; the Markdown twins are small and greppable, which makes them the right surface for anyone assembling an integration or checking what an endpoint actually does. It is also a general pattern rather than a quirk of this vendor, and it is worth trying on any documentation site that returns a JavaScript shell.

The vendor's own support centre, by contrast, sits on a help-desk platform that refuses scripted requests outright and returns HTTP 403. Both hosts belong to the same company, and only one of them is readable without a browser, which is a reminder that a block is a property of the host rather than of the vendor. That asymmetry is worth remembering before concluding that a vendor documents nothing.

What the API does not change

This is the section that matters most, and it is short.

Driving automations through an API rather than through a user interface does not alter the relationship with the platforms those automations touch. The same actions, from the same accounts, produce the same exposure.

LinkedIn's User Agreement, effective 3 November 2025, prohibits members from developing, supporting or using "software, devices, scripts, robots or any other means or processes (such as crawlers, browser plugins and add-ons or any other technology) to scrape or copy the Services, including profiles and other data from the Services", from copying or distributing information obtained from the service without the content owner's consent, and from overriding or circumventing "any access controls or use limits of the Services (such as search results, profiles, or videos)".

LinkedIn's help page on prohibited software and extensions states that it does not permit third-party software that scrapes or automates activity on the site, that members using such tools are in violation of the User Agreement, and that they "risk having their accounts restricted or shut down" while the tools may become non-functional without notice.

What using the API through code does and does not change

• ✓Yes: Removes the manual step of launching and collecting runs
• ✓Yes: Lets results land in your own systems without a human moving files
• ✓Yes: Makes scheduling and retry logic your responsibility rather than the interface's
• ✕No: Changes how the platform underneath sees the actions
• ✕No: Provides any figure for what LinkedIn tolerates
• ✕No: Removes the rule that extraction and sending belong on different accounts

The API also removes the friction that was doing some safety work. A person clicking launch and waiting for a run to finish is naturally rate-limited by attention. A scheduled job is not, and the first thing most teams do with an API is run things more often. That is the failure mode to design against rather than discover.

The mitigation is to put the pacing in the scheduler rather than in the automation. A job that runs a fixed number of times a day at spread intervals is a decision made once and enforced by infrastructure. A rate limit that lives inside a script is a decision that survives until someone edits the script.

The custom-script layer, and when it is worth it

Below the API sits a second developer surface that gets less attention: PhantomBuster's own scripting environment. Its documentation covers managing custom scripts, coding one, script directives, packages and modules, an agent module, external Node dependencies, TypeScript support, and how-tos for logging into a website, taking screenshots and injecting client-side JavaScript.

That is a meaningful capability and it changes what the product is. A team using only prebuilt automations is buying a catalogue. A team writing scripts is buying a hosted browser-automation runtime with a scheduler and a results store attached, and the alternative to that is running headless browsers on infrastructure they maintain themselves.

The case for using it is that the boring parts are solved. Scheduling, retries, result storage, console output and a place for credentials all exist already, and those are exactly the parts that make a homegrown scraper a maintenance burden six months later.

The case against is lock-in of a specific kind. A script written against the agent module and the platform's directives does not lift out cleanly, so the migration cost is real even though the language is ordinary. Whether that matters depends on how central the workflow is, and the honest test is whether you would rebuild it or abandon it if the platform changed its terms.

The middle path most teams take is to use prebuilt automations for the common jobs and write scripts only for the one or two workflows that genuinely have no equivalent. That keeps the maintenance surface small enough to actually maintain.

What to build with it

The genuinely good uses are the unglamorous ones. Pushing results into a warehouse or CRM without a human downloading a CSV. Triggering an enrichment run when a record changes rather than on a schedule. Reading status and console output so a failed run raises an alert rather than silently producing an empty file, which is the most common way a data pipeline lies to its owner.

Lead-list management through the filters endpoint is the piece worth planning around, because it moves list state into the platform and out of the spreadsheet where it usually rots. That is a workflow improvement rather than a capability one, and it is what most teams actually get value from.

The webhook support deserves the same framing. Polling a run until it finishes is the obvious first implementation and it is the one that produces surprise API usage, duplicated results and a job that hangs when a run does. Reacting to a completion event instead is less code and fails more honestly, and it is documented rather than something to work out.

The MCP server is a reasonable addition for assistant-driven work, with the same caveat that applies everywhere: scoped access to automations that touch a platform account is scoped access to your account's exposure, so the scope is worth setting narrowly.

What to settle before integrating

Pin the version, because v1 and v2 are both live, they disagree about timestamp units, and the docs describe v2 as current.

Store the key on creation, since it is shown once, and keep it out of query strings so it does not reach logs and caches, exactly as the documentation advises.

Handle failure as a normal state. Automations built against platform interfaces break when those interfaces change, and the vendor's own docs say prohibited tools may stop working without notice. A pipeline that treats an empty result as success will report zero rather than failure.

And keep extraction on accounts that do not send. That rule costs nothing to apply in advance and cannot be applied afterwards. The product-level evaluation is in PhantomBuster, the substitutes are in PhantomBuster alternatives, and the sequencer comparison is in LinkedIn automation tools.

If what you actually want is booked meetings rather than a data pipeline you maintain, get a free campaign plan and we will map the channel to your ICP before anything sends.

Pricing and features verified as of August 2026. Verify current terms with the vendor before relying on them.