wThe Phantombuster API gives you control over your account. It is composed of HTTPS endpoints returning JSON data.
Here's a short list of what the API allows:
- Launch and abort agents
- Get console output, status, progress and messages from an agent
- Get real-time console output from an agent
- Get user account, agent and script records
- Create and update scripts
We strive to make the API extremely simple to use. Any developer should be able to get responses in a matter of minutes (if that's not the case, it's our fault, please send us an email telling us what's wrong).
All API endpoints URLs are formated as follow:
<version> can be either
v2, the current version being
Date/time fields are Unix/POSIX timestamps, they are in seconds for
v1 endpoints, and milliseconds for
All v1 endpoints return JSON following the JSend specification. It basically means all successfull v1 responses have HTTP code
2XX and look like this:
Your API key resides in your Workspace settings page. This page is also accessible through your navbar's menu, under the label "Workspace settings". Please notice that for security reasons, your key will only be shown once, on creation. You better copy it in a safe place before refreshing or leaving the page.
Please, protect your API key
Your key is precious as anyone who knows it can launch your agents (and do other mean things).
If you think it has been compromised do not hesitate to generate a new one and to delete the old one.
Authentication is dead simple: put your API key in the
X-Phantombuster-Key-1 HTTP header (or in the
key query string parameter) of every request you make.
Payloads can be put in the query string or in the request body for
POST requests. Here is how a typical request looks like:
POST /api/v1/agent/785/launch HTTP/1.1
You can also put your API key as a query string parameter. This is not recommended because your key might show up in log files or caches:
POST /api/v1/agent/785/launch?&key=YOUR_API_KEY HTTP/1.1
If something bad happens, the HTTP code will be
5XX and the response will look like this:
"message": "Description of what happened"
The error response might also contain a
code field and a
data field describing the error in more details.
Here are some error HTTP codes you might encounter:
400: missing parameter or something else wrong with the given parameters
401: missing API key or wrong API key
404: the requested object was not found (bad ID?)
500: for some reason our servers could not handle your request
How does a particular endpoint works?
If you would like to know what to expect from a particular endpoint, please refer to the API reference of that endpoint.
All endpoints are listed and documented in our API reference →.
Updated 10 months ago