API

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).

Versioning

All API endpoints URLs are formated as follow: https://phantombuster.com/api/<version>/<path>.
<version> can be either v1 or v2, the current version being v2,

Date/time fields are Unix/POSIX timestamps, they are in seconds for v1 endpoints, and milliseconds for v2 endpoints.

All v1 endpoints return JSON following the JSend specification. It basically means all successfull v1 responses have HTTP code 2XX and look like this:

{
  "status": "success",
  "data": {
    ...
  }
}

Authentication and request format

How to find my API Key

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

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
Host: phantombuster.com
X-Phantombuster-Key-1: YOUR_API_KEY

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
Host: phantombuster.com

Errors

If something bad happens, the HTTP code will be 4XX or 5XX and the response will look like this:

{
  "status": "error",
  "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.

Reference

All endpoints are listed and documented in our API reference →.