System Verification Output

https://hub.phantombuster.com/reference/
Admin
This file contains a system verification output, indicating a successful verification process and...
Tokens:140,807
Snippets:428
Trust Score:9.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### POST /ai/completions

Source: https://hub.phantombuster.com/reference/ai

Get a completion from the AI.

```APIDOC
## POST https://api.phantombuster.com/api/v2/ai/completions

### Description
Get a completion from the AI.

### Method
POST

### Endpoint
https://api.phantombuster.com/api/v2/ai/completions

### Parameters
#### Request Body
- **messages** (array of objects) - Required - Messages to send for completion generation (length ≥ 1)
- **model** (string) - Optional - The model to use for completion generation (gpt-35-turbo, gpt-4, gpt-4o, gpt-4o-mini, gpt-4.1-mini, gpt-5.1)
- **temperature** (number) - Optional - The temperature of the generated completions (0 to 2)
- **responseSchema** (object) - Optional - A JSON schema to describe the expected structured output as JSON
- **shouldBeFreeForPhantombusterScriptAgent** (boolean) - Optional - Whether the request should deduct AI credits from the user or not (Defaults to false)

### Response
#### Success Response (200)
- **Answer** (string) - Answer from the AI.
```

--------------------------------

### GET /org-storage/lists/fetch-all

Source: https://hub.phantombuster.com/reference/get_org-storage-lists-fetch-all

Retrieves all lists for the organization. This endpoint is marked as beta.

```APIDOC
## GET /org-storage/lists/fetch-all

### Description
Get all the lists - Beta.

### Method
GET

### Endpoint
/org-storage/lists/fetch-all

### Parameters
#### Header Parameters
- **X-Phantombuster-Org** (string) - Optional - ID of the org that is performing the operation (not necessary when using a third party key)

### Response
#### Success Response (200)
- **OK.**
```

--------------------------------

### GET /buyers-personas/fetch-all

Source: https://hub.phantombuster.com/reference/get_buyers-personas-fetch-all

Fetches all buyer personas for an organization.

```APIDOC
## GET /buyers-personas/fetch-all

### Description
Fetch all buyer personas for an org.

### Method
GET

### Endpoint
/buyers-personas/fetch-all

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the persona.
- **orgId** (string) - The organization identifier.
- **icpId** (string) - The ideal customer profile identifier.
- **leadsListId** (string) - Optional identifier for the leads list.
- **sourcingAgentId** (string) - Optional identifier for the sourcing agent.
- **monitoringAgentId** (string) - Optional identifier for the monitoring agent.
- **jd** (object) - Job description details including name, countries, jobs, painPoints, goalsKPI, sourcingLimit, pictureUrl, and jobTitleKeyword.

#### Error Response (403)
- Only web, API-key, intelligence-tool sessions are allowed to fetch ICPs. Agent and MCP sessions are not allowed.
```

--------------------------------

### GET /containers

Source: https://hub.phantombuster.com/reference/get_containers-fetch-all

Fetches a list of containers for a specified agent.

```APIDOC
## GET /containers

### Description
Retrieves the list of containers associated with a specific agent ID.

### Method
GET

### Endpoint
/containers

### Parameters
#### Header Parameters
- **X-Phantombuster-Org** (string) - Optional - ID of the org that is performing the operation (not necessary when using a third party key).

#### Query Parameters
- **agentId** (string) - Required - Id of the agent to fetch containers from.

### Response
#### Success Response (200)
- **maxLimitReached** (boolean) - Indicates if the maximum limit of containers has been reached.
- **containers** (array) - List of container objects.
```

--------------------------------

### GET /scripts/fetch-all

Source: https://hub.phantombuster.com/reference/get_scripts-fetch-all

Retrieves all scripts associated with the current user.

```APIDOC
## GET /scripts/fetch-all

### Description
Gets all the scripts associated with the current user.

### Method
GET

### Endpoint
/scripts/fetch-all

### Response
#### Success Response (200)
- **Array** (array) - A list of script objects associated with the user.
```

--------------------------------

### GET /containers/fetch-all

Source: https://hub.phantombuster.com/reference/get_containers-fetch-all

Retrieves all containers associated to a specified agent.

```APIDOC
## GET /containers/fetch-all

### Description
Gets all containers associated to a specified agent.

### Method
GET

### Endpoint
/containers/fetch-all

### Response
#### Success Response (200)
- **maxLimitReached** (boolean) - Indicates if the maximum limit of containers has been reached.
- **containers** (array) - A list of container objects.

#### Response Example
{
  "maxLimitReached": false,
  "containers": [
    {
      "id": "string",
      "status": "running",
      "createdAt": 1234567890,
      "launchType": "manual",
      "endType": "finished",
      "endedAt": 1234567890,
      "exitCode": 0,
      "retryNumber": 0,
      "runtimeEvents": []
    }
  ]
}
```

--------------------------------

### GET /containers/attach

Source: https://hub.phantombuster.com/reference/get_containers-attach

Attaches to a running container and streams its output in real-time.

```APIDOC
## GET /containers/attach

### Description
Attaches to a running container and streams its output in real-time.

### Method
GET

### Endpoint
/containers/attach

### Parameters
#### Header Parameters
- **X-Phantombuster-Org** (string) - Optional - ID of the org that is performing the operation (not necessary when using a third party key)

#### Query Parameters
- **id** (string) - Required - Id of the container to attach to.

### Response
#### Success Response (200)
- **OK** - Returns a stream of container output

#### Error Response (404)
- **Not Found** - No container exists with the provided id.
```

--------------------------------

### GET /org-storage/lists/fetch

Source: https://hub.phantombuster.com/reference/get_org-storage-lists-fetch

Retrieves a single lead list by its unique identifier.

```APIDOC
## GET /org-storage/lists/fetch

### Description
Get one list by ID - Beta.

### Method
GET

### Endpoint
/org-storage/lists/fetch

### Parameters
#### Query Parameters
- **id** (string) - Required - Id of the lead list to fetch.

#### Header Parameters
- **X-Phantombuster-Org** (string) - Optional - ID of the org that is performing the operation (not necessary when using a third party key).

### Response
#### Success Response (200)
- **OK**
```

--------------------------------

### POST /ai/advice

Source: https://hub.phantombuster.com/reference/post_ai-advice

Get a recommendation from the AI by sending a series of messages.

```APIDOC
## POST /ai/advice

### Description
Get a recommendation from the AI.

### Method
POST

### Endpoint
/ai/advice

### Parameters
#### Request Body
- **messages** (array) - Required - Messages to send for completion generation. Each item must contain 'role' (string: 'assistant' or 'user') and 'content' (string).
- **model** (string) - Optional - The model to use for completion generation (gpt-35-turbo, gpt-4, gpt-4o, gpt-4o-mini, gpt-4.1-mini, gpt-5.1).
- **temperature** (number) - Optional - The temperature of the generated completions (0 to 2).

### Response
#### Success Response (200)
- **choices** (array) - Answer from the AI.
- **creditsCost** (integer) - The cost in credits for the request.

#### Response Example
{
  "choices": ["AI response text"],
  "creditsCost": 1
}
```

--------------------------------

### Define OpenAPI Schema Structure

Source: https://hub.phantombuster.com/reference/post_scripts-save

Schema definitions for API goals, argument forms, and setup steps.

```json
                          },
                          "goals": {
                            "type": "array",
                            "maxItems": 10,
                            "uniqueItems": true,
                            "items": {
                              "type": "string",
                              "maxLength": 100
                            }
                          }
                        },
                        "additionalProperties": false
                      },
                      "defaultArgument": {
                        "type": "object",
                        "additionalProperties": true
                      },
                      "outputDescription": {
                        "type": "object",
                        "additionalProperties": true
                      },
                      "defaultArgumentAllowed": {
                        "type": "boolean"
                      },
                      "argumentForm": {
                        "type": "object",
                        "properties": {
                          "enabled": {
                            "type": "boolean"
                          },
                          "steps": {
                            "title": "ISetupStepList",
                            "type": "array",
                            "minItems": 1,
                            "maxItems": 10,
                            "items": {
                              "title": "ISetupStep",
                              "type": "object",
                              "properties": {
                                "slug": {
                                  "type": "string",
                                  "pattern": "^[\\w-]{1,50}$"
                                },
                                "title": {
                                  "type": "string",
                                  "maxLength": 100
                                },
                                "headerTitle": {
                                  "type": "string",
                                  "maxLength": 100
                                },
                                "fields": {
                                  "type": "object",
                                  "minProperties": 1,
                                  "maxProperties": 50,
                                  "additionalProperties": {
                                    "title": "IArgumentFormAugmentation",
                                    "type": "object",
                                    "properties": {
                                      "label": {
                                        "type": "string",
                                        "maxLength": 100
                                      },
                                      "labelLink": {
                                        "type": "string",
                                        "maxLength": 2000
                                      },
                                      "labelInfo": {
                                        "type": "string",
                                        "maxLength": 1000
                                      },
                                      "placeholder": {
                                        "type": "string",
                                        "maxLength": 250
                                      },
                                      "helper": {
                                        "type": "string",
                                        "maxLength": 1000
                                      },
                                      "helpers": {
                                        "anyOf": [
                                          {
                                            "type": "array",
                                            "maxItems": 50,
                                            "items": {
                                              "type": "string",
                                              "maxLength": 1000
                                            }
                                          },
                                          {
                                            "type": "string",
                                            "maxLength": 1000
                                          }
                                        ]
                                      },
                                      "optionLabels": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 200,
                                        "uniqueItems": true,
                                        "items": {
                                          "type": "string",
                                          "maxLength": 100
                                        }
```

--------------------------------

### Download a file using buster.download()

Source: https://hub.phantombuster.com/reference/buster-download

Examples showing how to download a file using different asynchronous patterns in JavaScript.

```javascript
const url = "https://phantombuster.com"
const saveAs = "phantombuster.html"
const headers = {
  "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
  "User-Agent": "Mozilla/5.0 (X11; Linux x86_64; rv:12.0) Gecko/20100101 Firefox/21.0"
}

try {
  const path = await buster.download(url, saveAs, headers)
  console.log("File successfully download here:", path)
  //The file is saved on the disk at this path, you can only access it inside the script
} catch (err) {
	console.log("Could not download the file:", err)
}
```

```javascript
const url = "https://phantombuster.com"
const saveAs = "phantombuster.html"
const headers = {
  "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
  "User-Agent": "Mozilla/5.0 (X11; Linux x86_64; rv:12.0) Gecko/20100101 Firefox/21.0"
}

await buster.download(url, saveAs, headers)
.then((path) => {
  console.log("File successfully download here:", path)
  //The file is saved on the disk at this path, you can only access it inside the script
})
.catch((err) => {
	console.log("Could not download the file:", err)
})
```

```javascript
var url = "https://phantombuster.com"
var saveAs = "phantombuster.html"
var headers = {
  "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
  "User-Agent": "Mozilla/5.0 (X11; Linux x86_64; rv:12.0) Gecko/20100101 Firefox/21.0"
}

await buster.download(url, saveAs, headers, function(err, path) {
	if (err) {
    console.log("Could not download the file:", err)
  } else {
    console.log("File successfully download here:", path)
    //The file is saved on the disk at this path, you can only access it inside the script
  }
})
```

--------------------------------

### GET /branches/diff

Source: https://hub.phantombuster.com/reference/get_branches-diff

Gets the length difference between the staging and release branch of all scripts.

```APIDOC
## GET /branches/diff

### Description
Gets the length difference between the staging and release branch of all scripts.

### Method
GET

### Endpoint
/branches/diff

### Parameters
#### Header Parameters
- **X-Phantombuster-Org** (string) - Optional - ID of the org that is performing the operation (not necessary when using a third party key)

#### Query Parameters
- **name** (string) - Optional - Name of the script branch to fetch the diff from.

### Response
#### Success Response (200)
- **id** (string) - Script ID
- **name** (string) - Script name
- **diffLength** (number) - Length difference
- **stagingVisibility** (string) - Staging visibility status
- **releaseVisibility** (string) - Optional - Release visibility status
- **stagingAccessList** (array) - Optional - Staging access list
- **releaseAccessList** (array) - Optional - Release access list
```

--------------------------------

### Retrieve Agent Object

Source: https://hub.phantombuster.com/reference/buster-getagentobject

Examples showing how to fetch an agent object using different asynchronous patterns.

```javascript
/*Bot launched with agentObject:
{
  "name": "nick",
  "age": 2 
}
*/

const agentId = buster.agentId //Useless

try {
  const object = await buster.getAgentObject(agentId)
  console.log("The name is", object.name, "and the age is", object.age)
  //This will print "The name is nick and the age is 2"
} catch (err) {
  console.log("Could not get agent object:", err)
}
```

```javascript
/*Bot launched with agentObject:
{
  "name": "nick",
  "age": 2 
}
*/

const agentId = buster.agentId //Useless

buster.getAgentObject(agentId)
.then((object) => {
  console.log("The name is", object.name, "and the age is", object.age)
  //This will print "The name is nick and the age is 2"
})
.catch((err) => {
  console.log("Could not get agent object:", err)
})
```

```javascript
/*Bot launched with agentObject:
{
  "name": "nick",
  "age": 2 
}
*/

var agentId = buster.agentId //Useless

buster.getAgentObject(agentId, function(err, object) {
  if (err) {
    console.log("Could not get agent object:", err)
  } else {
    console.log("The name is", object.name, "and the age is", object.age)
    //This will print "The name is nick and the age is 2"
  }
})
```

--------------------------------

### GET /agents/fetch

Source: https://hub.phantombuster.com/reference/get_agents-fetch

Retrieves the details of an agent by its ID.

```APIDOC
## GET /agents/fetch

### Description
Gets an agent by id.

### Method
GET

### Endpoint
/agents/fetch

### Response
#### Success Response (200)
- **id** (string) - The agent ID
- **scriptOrgName** (string) - The organization name of the script
- **scriptId** (string) - The script ID
- **script** (string) - The script filename
- **branch** (string) - The branch name
- **environment** (string) - The environment (staging or release)
- **argument** (string) - The agent argument
- **lastEndType** (string) - The last execution end type
- **manifest** (object) - The script branch manifest
```

--------------------------------

### POST /agent/launch

Source: https://hub.phantombuster.com/reference/launchagent-1

Launches an agent with specified arguments and optional save settings.

```APIDOC
## POST /agent/launch

### Description
Launches an agent. If the save argument is true, the provided arguments will be saved as the default launch options for the agent.

### Method
POST

### Endpoint
https://api.phantombuster.com/api/v1/agent/launch

### Parameters
#### Query Parameters
- **save** (boolean) - Optional - If true, `argument` will be saved as the default launch options for the agent.

### Response
#### Success Response (200)
- **status** (string) - Status of the request.
- **message** (string) - Description of the execution result.
- **data** (object) - Execution details including containerId, executionTime, exitCode, output, and resultObject.

#### Response Example
{
  "status": "success",
  "message": "Agent finished (success)",
  "data": {
    "containerId": 76426,
    "executionTime": 17,
    "exitCode": 0,
    "output": "This is a console output line!\r\nAnd this is another one :)",
    "resultObject": {}
  }
}
```

--------------------------------

### POST /agent/{id}/launch

Source: https://hub.phantombuster.com/reference/launchagent-1

Add an agent to the launch queue. The most important parameter is `output`, which determines the response format and behavior of the agent execution.

```APIDOC
## POST /agent/{id}/launch

### Description
Add an agent to the launch queue. The most important parameters is `output`, carefully choose yours when launching your agent with the API. For agents which take times to end, Phantombuster will send a space character every 10 seconds to prevent any timeout.

### Method
POST

### Endpoint
/agent/{id}/launch

### Parameters
#### Path Parameters
- **id** (integer) - Required - ID of the agent to launch.

#### Query Parameters
- **output** (string) - Optional - This allows you to choose what type of response to receive. Options: `json`, `result-object`, `first-result-object`, `result-object-with-output`, `event-stream`, `raw`.
- **argument** (string) - Optional - JSON argument as a String. The argument can be retrieved with buster.argument in the agent’s script.
- **saveArgument** (boolean) - Optional - Whether to save the argument.
```

--------------------------------

### GET /agent

Source: https://hub.phantombuster.com/reference/get_agents-fetch

Fetches details for a specific agent by its ID.

```APIDOC
## GET /agent

### Description
Fetches the details of a specific agent. You can optionally include additional information such as the manifest, agent object, script code, or slave agents.

### Method
GET

### Endpoint
/agent

### Parameters
#### Header Parameters
- **X-Phantombuster-Org** (string) - Optional - ID of the org that is performing the operation (not necessary when using a third party key)

#### Query Parameters
- **id** (string) - Required - Id of the agent to fetch.
- **withManifest** (string) - Optional - Set to "true" if you want to return the agent's manifest in the response
- **withAgentObject** (string) - Optional - Set to "true" if you want to include the agent_object in the response
- **withCode** (string) - Optional - Set to "true" if you want to include the agent's script code in the response
- **withSlaves** (string) - Optional - Set to "true" if you want to include the agent's slave agents in the response
- **withSubSlaves** (string) - Optional - Set to "true" if you want to include the agent's sub-slave agents in the response (requires withSlaves=true)

### Response
#### Success Response (200)
- **id** (string) - Agent ID
- **launchType** (string) - Launch type
- **nbLaunches** (number) - Number of launches
- **s3Folder** (string) - S3 folder path
- **orgS3Folder** (string) - Organization S3 folder path
- **fileMgmt** (object) - File management configuration
- **updatedAt** (number) - Last update timestamp

#### Error Responses
- **401** - Cannot access targeted manifest.
- **404** - Agent not found.
- **412** - No script targeted by agent.
```

--------------------------------

### Set result object using various JavaScript patterns

Source: https://hub.phantombuster.com/reference/buster-setresultobject

Examples showing how to set the agent result object using Async/Await, Promises, and traditional Callbacks.

```javascript
const object = {
  name: "Nick",
  age: 1,
  url: "nickjs.org"
}

try {
  await buster.setResultObject(object)
  //curl -i -H 'X-Phantombuster-Key-1: API_KEY' -X POST -d 'output=first-result-object' https://phantombuster.com/api/v1/agent/AGENT_ID/launch
  //You can get your result object at the url with the API
} catch (err) {
	console.log("Could not set the result object:", err)
}
```

```javascript
const object = {
  name: "Nick",
  age: 1,
  url: "nickjs.org"
}

buster.setResultObject(object)
.then(() => {
  //curl -i -H 'X-Phantombuster-Key-1: API_KEY' -X POST -d 'output=first-result-object' https://phantombuster.com/api/v1/agent/AGENT_ID/launch
  //You can get your result object at the url with the API
})
.catch((err) => {
	console.log("Could not set the result object:", err)
})
```

```javascript
var object = {
  name: "Nick",
  age: 1,
  url: "nickjs.org"
}

buster.setResultObject(object, function(err) {
  if (err) {
    console.log("Could not set the result object:", err)
  } else {
    //curl -i -H 'X-Phantombuster-Key-1: API_KEY' -X POST -d 'output=first-result-object' https://phantombuster.com/api/v1/agent/AGENT_ID/launch
    //You can get your result object at the url with the API
  }
})
```

--------------------------------

### POST /agents/launch-soon

Source: https://hub.phantombuster.com/reference/post_agents-launch-soon

Schedules an agent to launch before a specific time.

```APIDOC
## POST /agents/launch-soon

### Description
Schedules an agent to launch before a specific time. If the agent is launched manually before the expected launch time, the agent will not launch automatically.

### Method
POST

### Endpoint
/agents/launch-soon

### Parameters
#### Header Parameters
- **X-Phantombuster-Org** (string) - Optional - ID of the org that is performing the operation (not necessary when using a third party key)

#### Request Body
- **id** (string) - Required - Id of the agent to schedule for launch.
- **minutes** (integer) - Required - Determines in how many minutes the agent will launch.
- **argument** (string/object) - Optional - Agent argument. Can either be a JSON string or a plain object.
- **arguments** (string/object) - Optional - Agent argument. Can either be a JSON string or a plain object.
- **saveArgument** (boolean) - Optional - If true, argument will be saved as the default launch options for the agent.
- **saveArguments** (boolean) - Optional - If true, argument will be saved as the default launch options for the agent.

### Response
#### Success Response (200)
- **description** (string) - Agent has been scheduled to launch successfully.

#### Error Response (400)
- **description** (string) - A provided parameter is duplicated or the launch argument is too big.
```

--------------------------------

### Override agent time limit

Source: https://hub.phantombuster.com/reference/buster-overridetimelimit

Examples showing how to set a 60-second time limit using different asynchronous patterns.

```javascript
try {
  await buster.overrideTimeLimit(60)
  // Set the time limit at 1 minute
} catch (err) {
  console.log("Could not override the time limit:", err)
}
```

```javascript
buster.overrideTimeLimit(60)
.then(() => {
  // Set the time limit at 1 minute
})
.catch((err) => {
  console.log("Could not override the time limit:", err)
})
```

```javascript
buster.overrideTimeLimit(60, function(err) {
  if (err) {
    console.log("Could not override the time limit:", err)
  } else {
    // Set the time limit at 1 minute
  }
})
```

--------------------------------

### GET /orgs/crm-resources

Source: https://hub.phantombuster.com/reference/get_orgs-fetch-crm-resources

Fetches CRM resources for a specified organization.

```APIDOC
## GET /orgs/crm-resources

### Description
Fetches a specific type of resource from the organization's CRM.

### Method
GET

### Parameters
#### Header Parameters
- **X-Phantombuster-Org** (string) - Optional - ID of the org that is performing the operation (not necessary when using a third party key).

#### Query Parameters
- **resourceType** (string) - Required - Type of the resource to fetch from the organization's CRM. Supported values: account_info, contact_lists, contact_properties.

### Response
#### Error Responses
- **404** - Workspace not found.
- **412** - Organization's CRM integration not found.
```

--------------------------------

### POST /agents/launch-sync

Source: https://hub.phantombuster.com/reference/post_agents-launch-sync

Launches an agent and streams execution status in real-time using NDJSON format. The stream begins with a start message exposing the containerId and includes heartbeat messages, execution summary, and error messages.

```APIDOC
## POST /agents/launch-sync

### Description
Launches an agent and streams execution status in real-time using NDJSON format. The stream begins with a start message exposing the containerId (so clients can reconnect via /containers/attach on disconnect) and then includes heartbeat messages, execution summary, and error messages if any occur. Optionally includes log lines when the includeLogs body parameter is set to true.

### Method
POST

### Endpoint
/agents/launch-sync

### Response
#### Success Response (200)
- **application/x-ndjson** - Agent launched successfully. Response is a stream of NDJSON messages with types - start (sent first, with containerId and agentId), heartbeat (periodic keep-alive), logs (container output), summary (final execution result with containerId, executionTime, and optional exitCode), or error (if something goes wrong).
```

--------------------------------

### GET /container

Source: https://hub.phantombuster.com/reference/get_containers-fetch

Fetches the details of a specific container by its ID.

```APIDOC
## GET /container

### Description
Retrieves information about a specific container. You can optionally request additional data such as the result object, output, or runtime events.

### Method
GET

### Endpoint
/container

### Parameters
#### Query Parameters
- **id** (string) - Required - Id of the container to fetch.
- **withResultObject** (string) - Optional - If set, the container's result object will be returned in the response.
- **withOutput** (string) - Optional - If set, the output of the container will be returned in the response.
- **withRuntimeEvents** (string) - Optional - If set, the runtime events associated with the container will be returned in the response.
- **withNewerAndOlderContainerId** (string) - Optional - If set, returns IDs for newer and older containers.

### Response
#### Success Response (200)
- **id** (string) - The container ID.
- **status** (string) - The current status of the container.
- **createdAt** (string) - Timestamp of creation.
- **launchType** (string) - The type of launch.
- **retryNumber** (number) - The number of retries.

#### Error Response (404)
- No container exists with the provided id.
```

--------------------------------

### POST /api/v2/agents/launch

Source: https://hub.phantombuster.com/reference/agents

Adds an agent to the launch queue.

```APIDOC
## POST https://api.phantombuster.com/api/v2/agents/launch

### Description
Adds an agent to the launch queue.

### Method
POST

### Endpoint
https://api.phantombuster.com/api/v2/agents/launch

### Parameters
#### Request Body
- **id** (string) - Required - Id of the agent to launch.
- **argument** (string | object) - Optional - Agent argument. Can either be a JSON string or a plain object.
- **arguments** (string | object) - Optional - Agent argument. Can either be a JSON string or a plain object.
- **bonusArgument** (string | object) - Optional - Agent bonus argument. This bonus argument is single-use.
- **saveArgument** (boolean) - Optional - If true, argument will be saved as the default launch options.
- **saveArguments** (boolean) - Optional - If true, argument will be saved as the default launch options.
- **manualLaunch** (boolean) - Optional - If set, the agent will be considered as "launched manually".
- **maxInstanceCount** (number) - Optional - If set, the agent will only be launched if the number of already running instances is below the specified number.
- **internalMetadata** (object | null) - Optional - PhantomBuster-managed key-value pairs for internal container tagging.
- **userCustomMetadata** (object | null) - Optional - User-defined key-value pairs for container tagging.
- **persistedVolumeKey** (string | null) - Optional - Key identifying the persisted volume to attach to the launched container.

### Response
#### Success Response (200)
- Agent launched successfully.

#### Error Response (400)
- A provided parameter is duplicated or the launch argument is too big.
```

--------------------------------

### POST /agents/launch

Source: https://hub.phantombuster.com/reference/post_agents-launch

Adds an agent to the launch queue.

```APIDOC
## POST /agents/launch

### Description
Adds an agent to the launch queue.

### Method
POST

### Endpoint
/agents/launch

### Request Body
- **id** (string) - Required - Id of the agent to launch.
- **argument** (string/object) - Optional - Agent argument. Can either be a JSON string or a plain object.
- **arguments** (string/object) - Optional - Agent argument. Can either be a JSON string or a plain object.
- **bonusArgument** (string/object) - Optional - Agent bonus argument. Single-use argument merged with the original argument.
- **saveArgument** (boolean) - Optional - If true, argument will be saved as the default launch options for the agent.
- **saveArguments** (boolean) - Optional - If true, argument will be saved as the default launch options for the agent.
- **manualLaunch** (boolean) - Optional - If set, the agent will be considered as "launched manually".
- **maxInstanceCount** (number) - Optional - If set, the agent will only be launched if the number of already running instances is below the specified number.
- **internalMetadata** (object) - Optional - PhantomBuster-managed key-value pairs for internal container tagging.

### Response
#### Success Response (200)
- **description** (string) - Agent launched successfully.

#### Error Response (400)
- **description** (string) - A provided parameter is duplicated or the launch argument is too big.
```

--------------------------------

### GET /location/ip

Source: https://hub.phantombuster.com/reference/get_location-ip

Retrieves the country of the provided IP address.

```APIDOC
## GET /location/ip

### Description
Retrieves the country of the IP address.

### Method
GET

### Endpoint
/location/ip

### Parameters
#### Query Parameters
- **ip** (string) - Required - IPv4 or IPv6 address to retrieve the country of.

### Response
#### Success Response (200)
- **country** (string) - Country of the IP address

#### Error Responses
- **400** - Invalid IP address format.
- **500** - Unexpected error while fetching IP location.
```

--------------------------------

### Send emails using mail()

Source: https://hub.phantombuster.com/reference/buster-mail

Demonstrates sending an email using different asynchronous patterns available in the Phantombuster environment.

```javascript
const subject = "Mail subject"
const text = "This a sample text for an email."
const to = "me@phantombuster.com"

try {
  await buster.mail(subject, text, to)
  //The mail is send to me@phantombuster.com
} catch (err) {
	console.log("Could not send the mail:", err)
}
```

```javascript
const subject = "Mail subject"
const text = "This a sample text for an email."
const to = "me@phantombuster.com"

buster.mail(subject, text, to)
.then(() => {
  //The mail is send to me@phantombuster.com
})
.catch((err) => {
	console.log("Could not send the mail:", err)
})
```

```javascript
var subject = "Mail subject"
var text = "This a sample text for an email."
var to = "me@phantombuster.com"

buster.mail(subject, text, to, function(err) {
  if (err) {
    console.log("Could not send the mail:", err)
  } else {
    //The mail is send to me@phantombuster.com
  }
})
```

--------------------------------

### GET /containers/fetch-output

Source: https://hub.phantombuster.com/reference/get_containers-fetch-output

Retrieves the output of a container identified by its ID.

```APIDOC
## GET /containers/fetch-output

### Description
Gets the output of a container.

### Method
GET

### Endpoint
/containers/fetch-output

### Parameters
#### Query Parameters
- **id** (string) - Required - Id of the container to fetch output from.
- **mode** (string) - Optional - If set to "raw", the output will be returned as plain text. If omitted or set to "json", the output will be returned as json.

### Response
#### Success Response (200)
- **output** (string) - The output of the container.

#### Success Response (204)
- Container output is empty.

#### Error Response (404)
- No container exists with the provided id.
```

--------------------------------

### GET /api/v2/buyers-personas/fetch-all

Source: https://hub.phantombuster.com/reference/buyerspersonas

Fetches all buyer personas associated with an organization.

```APIDOC
## GET /api/v2/buyers-personas/fetch-all

### Description
Fetch all buyer personas for an org.

### Method
GET

### Endpoint
https://api.phantombuster.com/api/v2/buyers-personas/fetch-all

### Response
#### Success Response (200)
Buyer personas successfully fetched.

#### Error Response (403)
Only web, API-key, intelligence-tool sessions are allowed to fetch ICPs. Agent and MCP sessions are not allowed.
```

--------------------------------

### Retrieve Global Object using Async/Await, Promises, and Callbacks

Source: https://hub.phantombuster.com/reference/buster-getglobalobject

Demonstrates three ways to fetch the global object: using async/await, Promise chains, or a callback function.

```javascript
/*Bot launched with globalObject:
{
  "name": "nick",
  "age": 2 
}
*/

try {
  const object = await buster.getGlobalObject()
  console.log("The name is", object.name, "and the age is", object.age)
  //This will print "The name is nick and the age is 2"
} catch (err) {
  console.log("Could not get the global object:", err)
}
```

```javascript
/*Bot launched with globalObject:
{
  "name": "nick",
  "age": 2 
}
*/

buster.getGlobalObject()
.then((object) => {
  console.log("The name is", object.name, "and the age is", object.age)
  //This will print "The name is nick and the age is 2"
})
.catch((err) => {
  console.log("Could not get the global object:", err)
})
```

```javascript
/*Bot launched with globalObject:
{
  "name": "nick",
  "age": 2 
}
*/

buster.getGlobalObject(function(err, object) {
  if (err) {
    console.log("Could not get the global object:", err)
  } else {
    console.log("The name is", object.name, "and the age is", object.age)
    //This will print "The name is nick and the age is 2"
  }
})
```

--------------------------------

### POST /agents/launch-sync

Source: https://hub.phantombuster.com/reference/post_agents-launch-sync

Triggers the synchronous launch of a specific agent.

```APIDOC
## POST /agents/launch-sync

### Description
Triggers the synchronous launch of a specific agent. This endpoint allows for passing arguments, bonus arguments, and configuring execution parameters.

### Method
POST

### Endpoint
/agents/launch-sync

### Parameters
#### Header Parameters
- **X-Phantombuster-Org** (string) - Optional - ID of the org that is performing the operation (not necessary when using a third party key)

#### Request Body
- **id** (string) - Required - Id of the agent to launch.
- **argument** (string/object) - Optional - Agent argument. Can either be a JSON string or a plain object.
- **arguments** (string/object) - Optional - Agent argument. Can either be a JSON string or a plain object.
- **bonusArgument** (string/object) - Optional - Agent bonus argument. Single-use argument merged with the original argument.
- **saveArgument** (boolean) - Optional - If true, argument will be saved as the default launch options for the agent.
- **saveArguments** (boolean) - Optional - If true, argument will be saved as the default launch options for the agent.
- **manualLaunch** (boolean) - Optional - If set, the agent will be considered as "launched manually".
- **maxInstanceCount** (number) - Optional - If set, the agent will only be launched if the number of already running instances is below the specified number.
- **includeLogs** (boolean) - Optional - If true, agent logs will be included in the stream. Defaults to false.
- **persistedVolumeKey** (string) - Optional - Key identifying the persisted volume to attach to the launched container.

### Response
#### Success Response (200)
- **data** (object) - The result of the agent execution.
```

--------------------------------

### GET /user

Source: https://hub.phantombuster.com/reference/api-user

Retrieves information about your Phantombuster account and your agents.

```APIDOC
## GET https://api.phantombuster.com/api/v1/user

### Description
Get information about your Phantombuster account and your agents.

### Method
GET

### Endpoint
https://api.phantombuster.com/api/v1/user

### Response
#### Success Response (200)
- **Success** - Account and agent information retrieved successfully.
```

--------------------------------

### GET /agents/fetch-all

Source: https://hub.phantombuster.com/reference/get_agents-fetch-all

Retrieves all agents of the current user's organization.

```APIDOC
## GET /agents/fetch-all

### Description
Gets all agents of the current user's organization.

### Method
GET

### Endpoint
/agents/fetch-all

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the agent.
- **name** (string) - The name of the agent.
- **createdAt** (number) - The timestamp when the agent was created.
- **scriptOrgName** (string) - The organization name associated with the script.
- **scriptId** (string) - The unique identifier of the script.
- **script** (string) - The script filename.
- **branch** (string) - The branch name.
- **environment** (string) - The environment (staging or release).
- **argument** (string) - The arguments passed to the agent.
- **lastEndType** (string) - The type of the last execution end.
- **lastEndedAt** (number) - The timestamp of the last execution end.
- **lastExitCode** (number) - The exit code of the last execution.
- **nbContainersRunning** (number) - The number of containers currently running for this agent.
- **runningTime** (number) - The total running time of the agent.
- **manifest** (object) - The script branch manifest details.
```

--------------------------------

### Save a folder to persistent storage

Source: https://hub.phantombuster.com/reference/buster-savefolder

Demonstrates how to save a local directory to persistent storage using different asynchronous patterns.

```javascript
const path = "screenshots"
const saveAs = "agent_screenshots"

try {
  const url = await buster.saveFolder(path, saveAs)
  console.log("Folder successfully at url:", url)
  // The folder is permanently saved at this url you can access
} catch (err) {
  console.log("Could not save folder:", err)
}
```

```javascript
const path = "screenshots"
const saveAs = "agent_screenshots"

buster.saveFolder(path, saveAs)
.then((url) => {
  console.log("Folder successfully at url:", url)
  // The folder is permanently saved at this url you can access
})
.catch((err) => {
  console.log("Could not save folder:", err)
})
```

```javascript
var path = "screenshots"
var saveAs = "agent_screenshots"

buster.saveFolder(path, saveAs, function(err, url) {
  if (err) {
    console.log("Could not save folder:", err)
  } else {
    console.log("Folder successfully at url:", url)
    // The folder is permanently saved at this url you can access
  }
})
```

--------------------------------

### GET /ai/tasks

Source: https://hub.phantombuster.com/reference/post_ai-tasks

Retrieves a specific task run performed by the AI.

```APIDOC
## GET /ai/tasks

### Description
Get a task run by the AI.

### Method
GET

### Endpoint
/ai/tasks
```
Tokens:
Raw