---
agentTools:
  projectIndex: https://hub.phantombuster.com/llms.txt
---

# API

Programmatically control your Phantombuster account. **[Phantombuster API reference →](/reference)**

The 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](mailto:support@phantombuster.com) 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](https://github.com/omniti-labs/jsend) specification. It basically means all successfull v1 responses have HTTP code `2XX` and look like this:

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

## Authentication and request format

### How to find my API Key

Your API key resides in your  [Workspace settings page](https://phantombuster.com/workspace-settings). 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.

[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/155da41962901bca7a2544025b8afb6d18944dc0e54c086e4b293489c8941080-GIF_API.gif",
        null,
        null
      ],
      "align": "center"
    }
  ]
}
[/block]

> ❗️ 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:

```http
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:

```http
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:

```json
{
  "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](/reference)** of that endpoint.

## Reference

All endpoints are listed and documented in our **[API reference →](/reference)**.