PhantomBuster API: Run Control, Result Handoffs, and Failure Recovery

The PhantomBuster API can launch one saved Phantom, track its run, retrieve its output, and stop or retry it. A safe integration distinguishes the reusable Agent ID from each run's Container ID, treats HTTP 200 as launch acceptance rather than job success, and checks exit codes and runtime events before accepting results. The API does not directly launch a multi-step Workflow.

PhantomBuster API control map

PhantomBuster's API reference uses Agent for a saved Phantom and Container for one execution. The Agent ID is stable across launches. Every execution gets a new Container ID.

The current v2 endpoint reference uses https://api.phantombuster.com/api/v2 and the X-Phantombuster-Key header. Older generic guides contain another host and legacy authentication examples. Use the v2 reference for new work. Store the key only in a server-side secret store because a holder can run Phantoms in the workspace.

Launch one Phantom and record the run

POST /agents/launch adds one Phantom to the launch queue. The request requires the Agent ID. A successful response returns the Container ID for that execution.

The request can use the Agent's saved setup or provide a one-run override through bonusArgument. The saveArgument option persists supplied settings, which creates a configuration change beyond the current run. Keep those paths separate in code and require approval before a job changes saved arguments.

PhantomBuster's help center says arrays are not accepted as launch inputs. Use one launch per item or a file input supported by that Phantom. The API can launch individual Phantoms but cannot directly start a Workflow. A multi-step API process must launch and coordinate the individual Phantoms.

The synchronous launch route returns a line-by-line stream. Its first message contains the Container ID, followed by heartbeats, logs, a final summary, or an error. If the connection drops, use that Container ID with /containers/attach to reconnect to the running job.

Read status and classify failure correctly

GET /containers/fetch returns one run's metadata. Documented statuses include starting, running, finished, unknown, and launch error. End reasons include normal completion, manual stop, timeout, unknown termination, and no-log timeout.

PhantomBuster's failure guide says there is no dependable failed status. Request runtime events and test for a nonzero exitCode or an event whose type is error. Add full output only when the structured evidence is insufficient.

An HTTP 200 from the launch endpoint means that the request was accepted. It does not mean that the Phantom produced records. A finished status also needs the exit code, runtime events, and expected result check.

Classify errors before retrying:

1. Transient service or network interruption can justify a bounded retry.
2. Invalid input needs a corrected payload.
3. Expired credentials or sessions need reauthorization.
4. Exhausted execution time or slot capacity needs a scheduling or plan decision.
5. A target-platform restriction requires a policy review, not faster retries.

Automatic retries can run after nonzero exits, with a published maximum of 10. That is an available setting, not a recommended default. Repeating an invalid payload or restricted action wastes execution time and can repeat unwanted side effects.

Result objects, logs, and files are different

For one run's business output, use GET /containers/fetch-result-object with the Container ID. A normal response returns the data in resultObject; a large result can return file references. An empty successful result can mean that no records matched or that the Phantom produced no output.

For diagnostic console text, use /containers/fetch-output. Raw mode returns text, while JSON mode returns structured output. HTTP 204 means the output is empty. HTTP 404 means the Container ID does not exist.

Accumulated CSV or JSON files belong to the Agent, not one Container. The documented method fetches the Agent record and constructs the storage URL from orgS3Folder and s3Folder. Do not attach an accumulated file to one CRM job without filtering it back to that run.

Result files cannot be deleted through the API according to the current quick-start guide. Deletion is a dashboard task. Add retention and cleanup ownership to the operating procedure.

Webhook handoffs need their own controls

PhantomBuster's webhook guide says a custom webhook runs at the end of execution. Its payload can include Agent ID, Container ID, duration, exit code, message, and result object.

The endpoint must finish within 11 seconds and cannot use more than two redirects. PhantomBuster can unregister a webhook after a 4xx response or invalid redirect behavior. The public guide does not promise exactly-once delivery or publish a durable retry schedule.

Design the receiver to validate a shared secret, acknowledge quickly, and enqueue processing. The docs say custom headers are unavailable and suggest a query parameter for a shared secret. Avoid logging the full URL, and rotate the secret if it appears in logs or monitoring tools.

Slots and execution time limit throughput

PhantomBuster's current pricing page displays Start, Grow, and Scale with 5, 15, and 50 slots and 20, 80, and 300 monthly execution hours. The observed monthly prices were €69, €159, and €439. Annual billing displayed monthly equivalents of €56, €128, and €352, billed annually.

The public pages conflict on whether slots mean concurrent executions, dashboard inventory, or both. They also conflict on the public user allowance and free-plan API access. Confirm those terms in writing for the chosen workspace.

Execution time is a shared monthly pool and is separate from slots. Current help documentation states a maximum run time of 300 minutes. No public API request-per-minute limit was found, but that absence is not proof of unlimited API calls.

Keep target-platform policy separate

A higher PhantomBuster plan does not raise a target platform's limits. PhantomBuster says this directly in its own limits guidance. LinkedIn's User Agreement separately prohibits scraping or copying through scripts and similar technology, bypassing use limits, and unauthorized automated access or actions.

Delays, proxies, retries, and vendor-recommended volumes do not establish LinkedIn permission. Before launch, document the target system, action, account owner, source authority, expected result, and stop condition. Reject any workflow that depends on disguising prohibited behavior.

Our outbound resources can help define the run ledger and acceptance controls. Our outbound services connect approved automation to a client-owned CRM without making a Phantom result the system of record.

Ready to control every automation run?

We can design the PhantomBuster API launch ledger, result handoff, failure classification, and CRM acceptance path around infrastructure your team owns.

Book your free discovery call →