Agent

 

/agent/{id}

Get an agent record.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://phantombuster.com/api/v1/agent/id
curl --request GET \
  --url https://phantombuster.com/api/v1/agent/id
var request = require("request");

var options = { method: 'GET',
  url: 'https://phantombuster.com/api/v1/agent/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://phantombuster.com/api/v1/agent/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://phantombuster.com/api/v1/agent/id");

xhr.send(data);
import requests

url = "https://phantombuster.com/api/v1/agent/id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
integer
required

ID of the agent to retrieve.

Query Params

withScript
boolean

If true, and if the agent has an associated script, also return the script record.

Response

Success

statusstring
dataobject
data.idnumber
data.namestring
data.scriptIdnumber
data.proxystring
data.proxyAddressobject
data.proxyUsernameobject
data.proxyPasswordobject
data.disableWebSecurityboolean
data.ignoreSslErrorsboolean
data.loadImagesboolean
data.launchstring
data.nbLaunchesnumber
data.showDebugboolean
data.awsFolderstring
data.executionTimeLimitnumber
data.fileMgmtstring
data.fileMgmtMaxFoldersnumber
data.lastEndMessagestring
data.lastEndStatusstring
data.maxParallelExecsnumber
data.userAwsFolderstring
data.noncenumber
data.scriptobject
data.script.idnumber
data.script.namestring
data.script.sourcestring
data.script.urlobject
data.script.textstring
data.script.httpHeadersobject

Error

statusstring
messagestring

/agent/{id}/launch

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.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://phantombuster.com/api/v1/agent/id/launch
curl --request POST \
  --url https://phantombuster.com/api/v1/agent/id/launch
var request = require("request");

var options = { method: 'POST',
  url: 'https://phantombuster.com/api/v1/agent/id/launch' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://phantombuster.com/api/v1/agent/id/launch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://phantombuster.com/api/v1/agent/id/launch");

xhr.send(data);
import requests

url = "https://phantombuster.com/api/v1/agent/id/launch"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
integer
required

ID of the agent to launch.

Query Params

output
string

This allows you to choose what type of response to receive.

  • json - Standard JSON output to get back a containerId in JSON. This ID can later be used to track this launch and get console output by calling /api/v1/agent/{agentId}/output.json?containerId={containerId}.
  • result-object - Result object output to get a blocking JSON response which will close when your agent finishes. The response will contain your agent’s exit code (Number) and its result object (PlainObject) if it was set (using setResultObject()). This endpoint is very useful for getting a response from your agents “synchronously” — just make a single HTTP request and wait for your result object/exit code.
  • first-result-object - Use first-result-object instead of result-object to have the request terminate immediately after the first call to setResultObject(). This is the fastest way to get a response from an agent using the API. However you will only get the result object and nothing else (no exit code or console output for example).
  • result-object-with-output - Use result-object-with-output instead of result-object to get the console output of your agent in addition to all the other fields.
  • event-stream - Event stream output to get a text/event-stream HTTP response. Each line of console output is sent as an event stream message starting with data:. When you receive the first message, you know the agent has started. When the agent has finished, the connection is closed. At regular intervals, event stream comments (starting with :) are sent to keep the connection alive. See a demo of this endpoint in action.
  • raw - Raw output to get an HTTP text/plain, chunked, streaming response of the raw console output of the agent. This is not recommended as almost all HTTP clients will timeout at one point or another, especially if your agent stays in queue for a few minutes (in which case the endpoint will send zero bytes for a few minutes, waiting for the agent to start — even cURL and Wget struggle to handle non-transmitting HTTP responses).
argument
string

JSON argument as a String.The argument can be retrieved with buster.argument in the agent’s script.

saveArgument
boolean

If true, argument will be saved as the default launch options for the agent.

Response

Success

statusstring
messagestring
dataobject
data.containerIdnumber
data.executionTimenumber
data.exitCodenumber
data.outputstring
data.resultObjectobject

Call buster.setResultObject() to set this PlainObject.

Error

statusstring
messagestring

/agent/{id}/abort

Abort all running instances of the agent.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://phantombuster.com/api/v1/agent/id/abort
curl --request POST \
  --url https://phantombuster.com/api/v1/agent/id/abort
var request = require("request");

var options = { method: 'POST',
  url: 'https://phantombuster.com/api/v1/agent/id/abort' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://phantombuster.com/api/v1/agent/id/abort")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://phantombuster.com/api/v1/agent/id/abort");

xhr.send(data);
import requests

url = "https://phantombuster.com/api/v1/agent/id/abort"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
integer
required

ID of the agent to stop.

Response

Success

statusstring
dataobject

Error

statusstring
messagestring

/agent/{id}/output

Get data from an agent: console output, status, progress and messages. This API endpoint is specifically designed so that it’s easy to get incremental data from an agent.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://phantombuster.com/api/v1/agent/id/output
curl --request GET \
  --url https://phantombuster.com/api/v1/agent/id/output
var request = require("request");

var options = { method: 'GET',
  url: 'https://phantombuster.com/api/v1/agent/id/output' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://phantombuster.com/api/v1/agent/id/output")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://phantombuster.com/api/v1/agent/id/output");

xhr.send(data);
import requests

url = "https://phantombuster.com/api/v1/agent/id/output"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
integer
required

ID of the agent from which to retrieve the output, status and messages.

Query Params

mode
string

This allows you to choose what type of response to receive.

  • track - the console output from a particular instance is returned, as specified by the containerId parameter.
  • most-recent - the most recent instance is selected each time a request is made.
containerId
number

ID of the instance from which to get console output.

fromMessageId
number

Return the agent’s messages starting from this ID.

fromOutputPos
number

Return the agent’s console output starting from this position.

withoutResultObject
boolean

If true, omit the agent’s result object from the response.

Response

Success

statusstring
dataobject
data.agentStatusstring
data.containerStatusstring
data.runningContainersnumber
data.queuedContainersnumber
data.containerIdnumber
data.progressobject
data.progress.progressnumber
data.progress.labelstring
data.progress.runtimenumber
data.messagesarray
data.outputstring
data.outputPosnumber
data.resultObjectobject

Call buster.setResultObject() to set this PlainObject.

Error

statusstring
messagestring

/agent/{id}/containers

Get a list of ended containers for an agent, ordered by date. Useful for listing the last available output logs from an agent.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://phantombuster.com/api/v1/agent/id/containers
curl --request GET \
  --url https://phantombuster.com/api/v1/agent/id/containers
var request = require("request");

var options = { method: 'GET',
  url: 'https://phantombuster.com/api/v1/agent/id/containers' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://phantombuster.com/api/v1/agent/id/containers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://phantombuster.com/api/v1/agent/id/containers");

xhr.send(data);
import requests

url = "https://phantombuster.com/api/v1/agent/id/containers"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
integer
required

ID of the agent from which to retrieve the containers.

Response

Success

statusstring
dataarray

Error

statusstring
messagestring

Script

 

/script/by-id/{mode}/{id}

Get a script record by its ID.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://phantombuster.com/api/v1/script/by-id/mode/id
curl --request GET \
  --url https://phantombuster.com/api/v1/script/by-id/mode/id
var request = require("request");

var options = { method: 'GET',
  url: 'https://phantombuster.com/api/v1/script/by-id/mode/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://phantombuster.com/api/v1/script/by-id/mode/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://phantombuster.com/api/v1/script/by-id/mode/id");

xhr.send(data);
import requests

url = "https://phantombuster.com/api/v1/script/by-id/mode/id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
integer
required

ID of the script to retrieve.

mode
string
required

JSON or raw text.

Query Params

withoutText
boolean

If true, do not send the script’s contents but only its metadata (only in JSON mode).

Response

Success

statusstring
dataobject
data.idnumber
data.namestring
data.sourcestring
data.urlobject
data.textstring
data.httpHeadersobject
data.lastSaveDatenumber
data.noncenumber

Error

statusstring
messagestring

/script/by-name/{mode}/{name}

Get a script record by its name.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://phantombuster.com/api/v1/script/by-name/mode/name
curl --request GET \
  --url https://phantombuster.com/api/v1/script/by-name/mode/name
var request = require("request");

var options = { method: 'GET',
  url: 'https://phantombuster.com/api/v1/script/by-name/mode/name' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://phantombuster.com/api/v1/script/by-name/mode/name")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://phantombuster.com/api/v1/script/by-name/mode/name");

xhr.send(data);
import requests

url = "https://phantombuster.com/api/v1/script/by-name/mode/name"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

name
string
required

Name of the script to retrieve, with its extension (.js or .coffee).

mode
string
required

JSON or raw text.

Query Params

withoutText
boolean

If true, do not send the script’s contents but only its metadata (only in JSON mode).

Response

Success

statusstring
dataobject
data.idnumber
data.namestring
data.sourcestring
data.urlobject
data.textstring
data.httpHeadersobject
data.lastSaveDatenumber
data.noncenumber

Error

statusstring
messagestring

/scripts

Get the list of all your scripts without text.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://phantombuster.com/api/v1/scripts
curl --request GET \
  --url https://phantombuster.com/api/v1/scripts
var request = require("request");

var options = { method: 'GET',
  url: 'https://phantombuster.com/api/v1/scripts' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://phantombuster.com/api/v1/scripts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://phantombuster.com/api/v1/scripts");

xhr.send(data);
import requests

url = "https://phantombuster.com/api/v1/scripts"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Response

Success

statusstring
dataarray

Error

statusstring
messagestring

/script/delete/{id}

Delete one of your script.

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://phantombuster.com/api/v1/script/delete/id
curl --request DELETE \
  --url https://phantombuster.com/api/v1/script/delete/id
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://phantombuster.com/api/v1/script/delete/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://phantombuster.com/api/v1/script/delete/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://phantombuster.com/api/v1/script/delete/id");

xhr.send(data);
import requests

url = "https://phantombuster.com/api/v1/script/delete/id"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
integer
required

ID of the script to delete.

Response

Success

statusstring
dataobject

Error

statusstring
messagestring

/script/{name}

Update an existing script or create a new one if it does not exist (in this case, the new script ID is returned in the data field).

 

Header Auth

 Authentication is required for this endpoint.
posthttps://phantombuster.com/api/v1/script/name
curl --request POST \
  --url 'https://phantombuster.com/api/v1/script/name?text=text'
var request = require("request");

var options = { method: 'POST',
  url: 'https://phantombuster.com/api/v1/script/name',
  qs: { text: 'text' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://phantombuster.com/api/v1/script/name?text=text")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://phantombuster.com/api/v1/script/name?text=text");

xhr.send(data);
import requests

url = "https://phantombuster.com/api/v1/script/name"

querystring = {"text":"text"}

response = requests.request("POST", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

name
string
required

Name of the script to update or create, with its extension (.js or .coffee).

Query Params

text
string
required

Full text contents of the script. This parameter must be in the request body in x-www-form-urlencoded format.

insertOnly
boolean

If true, make sure that we don’t update an existing script (optional). An error will be returned if a script with the same name already exists.

source
string

Optional String describing from where the script comes from. Reserved sources keywords are phantombuster, web, sdk and bot builder. Only 20 alpha-numeric characters (and space) are allowed.

Response

Success

statusstring
datanumber

Error

statusstring
messagestring

User

 

/user

Get information about your Phantombuster account and your agents.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://phantombuster.com/api/v1/user
curl --request GET \
  --url https://phantombuster.com/api/v1/user
var request = require("request");

var options = { method: 'GET', url: 'https://phantombuster.com/api/v1/user' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://phantombuster.com/api/v1/user")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://phantombuster.com/api/v1/user");

xhr.send(data);
import requests

url = "https://phantombuster.com/api/v1/user"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Response

Success

statusstring
dataobject
data.emailstring
data.timeLeftnumber
data.emailsLeftnumber
data.captchasLeftnumber
data.storageLeftnumber
data.databaseLeftnumber
data.agentsarray

Error

statusstring
dataobject

save()

save(urlOrPath [, saveAs, headers, callback])

 

Saves a distant or local file to your persistent storage.

— urlOrPath (String)

URL or path of the file to be saved.

  • https://www.google.com/images/srpr/logo11w.png (from the web)
  • foo/my_screenshot.jpg (from your agent's disk)
  • http://soundcloud.com/ (you'll get the HTML content of their homepage)

When saving a distant file, the MIME type is taken from the Content-Type HTTP header (if present).
When saving a local file, the MIME type is guessed from the file extension (if this fails, no MIME type is set).

— saveAs (String)

Where to put the file on your persistent storage (optional).
By default, the name will be taken from urlOrPath and the file will be saved at the root of your agent's folder in your persistent storage.
If a file with the same name already exists, it is overwritten.

  • foo/ (saves http://example.com/baz/bar.png as foo/bar.png)
  • null (saves http://example.com/foo/bar.png as bar.png)
  • foo/ (fails on http://example.com/ with could not determine filename)
  • foo/a (saves http://example.com/bar.png as foo/a)

You do not need to create any intermediate directory (a/b/c/d/e.jpg will work).

— headers (Plain Object)

HTTP headers to use when requesting the file (optional).
Cookies are automatically set when using CasperJS or PhantomJS.

— callback (Function(err, url))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong (typically if there was a network error or timeout).
  • url (String): the full URL to the file on your persistent storage.
const urlOrPath = "screenshot.jpg"
const saveAs = "screenshots/"


try {
  const url = await buster.save(urlOrPath, saveAs)
  console.log("File successfully saved at url:", url)
  // The file is permanently saved at this url you can access
} catch (err) {
  console.log("Could not save file:", err)
}
const urlOrPath = "screenshot.jpg"
const saveAs = "screenshots/"

buster.save(urlOrPath, saveAs)
.then((url) => {
  console.log("File successfully save at url:", url)
  // The file is permanently saved at this url you can access
})
.catch((err) => {
  console.log("Could not save file:", err)
})
var urlOrPath = "screenshot.jpg"
var saveAs = "screenshots/"

buster.save(urlOrPath, saveAs, function(err, url) {
  if (err) {
    console.log("Could not save file:", err)
  } else {
    console.log("File successfully save at url:", url)
    // The file is permanently saved at this url you can access
  }
})
const urlOrPath = "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 url = await buster.save(urlOrPath, saveAs, headers)
  console.log("File successfully saved at url:", url)
  // The file is permanently saved at this url you can access
} catch (err) {
  console.log("Could not save file:", err)
}
const urlOrPath = "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"
}

buster.save(urlOrPath, saveAs, headers)
.then((url) => {
  console.log("File successfully saved at url:", url)
  // The file is permanently saved at this url you can access
})
.catch((err) => {
  console.log("Could not save file:", err)
})
var urlOrPath = "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"
}

buster.save(urlOrPath, saveAs, headers, function (err, url) {
  if (err) {
    console.log("Could not save file:", err)
  } else {
    console.log("File successfully saved at url:", url)
    // The file is permanently saved at this url you can access
  }
})

Specify the right url

Since save() can either save local and distant files, you must specify the exact URL if you want to save a distant file.
"phantombuster.com" -bad
"https://phantombuster.com" -good

saveBase64()

saveBase64(base64String, saveAs [, mime, callback])

 

Saves a Base64 encoded file to your persistent storage.

— base64String (String)

Contents of the file to save. Can be pure Base64 or a Data URI Scheme string starting with data:.

— saveAs (String)

Where to put the file on your persistent storage.
If a file with the same name already exists, it is overwritten.

  • file.jpg
  • any/sub/directory/file.png
  • dir/ (fails because no file name was given)

You do not need to create any intermediate directory (a/b/c/d/e.jpg will work).

— mime (String)

MIME type of the file being saved (optional).
By default, it is guessed either from the Data URI Scheme string or from the file extension of the saveAs parameter (if this fails, no MIME type is set).

  • image/jpeg
  • image/png
  • image/svg+xml

— callback (Function(err, url))

Function called when finished.

  • err (String): null or a description of what went wrong if something went wrong (typically if there was a network error or timeout).
  • url (String): the full url to the file on your persistent storage.
const base64String = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAA3XAAAN1wFCKJt4AAAAB3RJTUUH4AoTFC0xuFcAiwAAAgtJREFUOMuVk81rE1EUxX9v5iUzaZKxaWM/UqxV0BZFEUF041ZEBMWFH3t10UX/guIfIHTptijFRaEuXLnrwkWlIii6kGIQ7Efa0urMYJJpk8xcF2PbiRaxZ/O4F95595zzrrrw+ovwBwTQSmGquA4FWiIo/oZOFpFAylAM5ywuFTo4mU0jwEK1wRu3RrnWoBkJRoJJ7UwQCWRMxf3BLu4MdGIb7e/Vw4ipZY+pZZetcI9EJ8ceHerm3kAn+6HDNHh4tItIhMkld7dvQKzvYqGDK4fz/AsKuNF/iOGcRZQkMFGcd2y60yZzbp0HH1d4XN6gJbG0RwvrjH6qMO/WKVmakayFuUNQsjW3BzopWrGap0suT86UOJGzeO8HzLk1zjo2E6f6ma74APTZmuu9DsW0Ro8dKzKSs5j3AgBu9jnMVHxMFOccGwGer3i8XPe52pPfjXXseJHLfoBeDJqcduzfNsK1njyLQZNyrcHE100i4FafQ9Y0OJJJJcxTVFsRenLxB7Pfq9wt7bk/mEmR1wa9dixrKJPGNvdizZoG4wtrfPAD9FYkfKs3YzcTKKRMCilz3zS0Urzz6vGn2olHcTCoZIwASh2UIkEQihCJ/PclQZAkQRAKrzZ+4jUjni25rG23mFn1eevV+VzdZrri4zVDXqz6eK2Q2c0qjUjal0kAEVCq/YzltfeSe/YL9WDOKpeKAEQAAAAASUVORK5CYII="
const saveAs = "img/phantom.png"
const mime = "image/png"

try {
  const url = await buster.saveBase64(base64Image, saveAs, mime)
  console.log("File successfully saved at:", url)
  // The file is permanently saved at this url you can access
} catch (err) {
  console.log("Could not save the file:", err)
}
const base64String = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAA3XAAAN1wFCKJt4AAAAB3RJTUUH4AoTFC0xuFcAiwAAAgtJREFUOMuVk81rE1EUxX9v5iUzaZKxaWM/UqxV0BZFEUF041ZEBMWFH3t10UX/guIfIHTptijFRaEuXLnrwkWlIii6kGIQ7Efa0urMYJJpk8xcF2PbiRaxZ/O4F95595zzrrrw+ovwBwTQSmGquA4FWiIo/oZOFpFAylAM5ywuFTo4mU0jwEK1wRu3RrnWoBkJRoJJ7UwQCWRMxf3BLu4MdGIb7e/Vw4ipZY+pZZetcI9EJ8ceHerm3kAn+6HDNHh4tItIhMkld7dvQKzvYqGDK4fz/AsKuNF/iOGcRZQkMFGcd2y60yZzbp0HH1d4XN6gJbG0RwvrjH6qMO/WKVmakayFuUNQsjW3BzopWrGap0suT86UOJGzeO8HzLk1zjo2E6f6ma74APTZmuu9DsW0Ro8dKzKSs5j3AgBu9jnMVHxMFOccGwGer3i8XPe52pPfjXXseJHLfoBeDJqcduzfNsK1njyLQZNyrcHE100i4FafQ9Y0OJJJJcxTVFsRenLxB7Pfq9wt7bk/mEmR1wa9dixrKJPGNvdizZoG4wtrfPAD9FYkfKs3YzcTKKRMCilz3zS0Urzz6vGn2olHcTCoZIwASh2UIkEQihCJ/PclQZAkQRAKrzZ+4jUjni25rG23mFn1eevV+VzdZrri4zVDXqz6eK2Q2c0qjUjal0kAEVCq/YzltfeSe/YL9WDOKpeKAEQAAAAASUVORK5CYII="
const saveAs = "img/phantom.png"
const mime = "image/png"

await buster.saveBase64(base64Image, saveAs, mime)
.then((url) => {
  console.log("File successfully saved at:", url)
  // The file is permanently saved at this url you can access
})
.catch((err) => {
  console.log("Could not save the file:", err)
})
var base64String = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAA3XAAAN1wFCKJt4AAAAB3RJTUUH4AoTFC0xuFcAiwAAAgtJREFUOMuVk81rE1EUxX9v5iUzaZKxaWM/UqxV0BZFEUF041ZEBMWFH3t10UX/guIfIHTptijFRaEuXLnrwkWlIii6kGIQ7Efa0urMYJJpk8xcF2PbiRaxZ/O4F95595zzrrrw+ovwBwTQSmGquA4FWiIo/oZOFpFAylAM5ywuFTo4mU0jwEK1wRu3RrnWoBkJRoJJ7UwQCWRMxf3BLu4MdGIb7e/Vw4ipZY+pZZetcI9EJ8ceHerm3kAn+6HDNHh4tItIhMkld7dvQKzvYqGDK4fz/AsKuNF/iOGcRZQkMFGcd2y60yZzbp0HH1d4XN6gJbG0RwvrjH6qMO/WKVmakayFuUNQsjW3BzopWrGap0suT86UOJGzeO8HzLk1zjo2E6f6ma74APTZmuu9DsW0Ro8dKzKSs5j3AgBu9jnMVHxMFOccGwGer3i8XPe52pPfjXXseJHLfoBeDJqcduzfNsK1njyLQZNyrcHE100i4FafQ9Y0OJJJJcxTVFsRenLxB7Pfq9wt7bk/mEmR1wa9dixrKJPGNvdizZoG4wtrfPAD9FYkfKs3YzcTKKRMCilz3zS0Urzz6vGn2olHcTCoZIwASh2UIkEQihCJ/PclQZAkQRAKrzZ+4jUjni25rG23mFn1eevV+VzdZrri4zVDXqz6eK2Q2c0qjUjal0kAEVCq/YzltfeSe/YL9WDOKpeKAEQAAAAASUVORK5CYII="
var saveAs = "img/phantom.png"
var mime = "image/png"

await buster.saveBase64(base64Image, saveAs, mime, function (err, url) {
  if (err) {
    console.log("Could not save the file:", err)
  } else {
    console.log("File successfully saved at:", url)
    // The file is permanently saved at this url you can access
  }
})

saveFolder()

saveFolder([path, saveAs, callback])

 

Saves a folder from your agent's disk to your persistent storage.

— path (String)

Path of the folder to save (optional, defaults to .).

  • . (everything from your current working directory)
  • any/sub/../sub/directory

Each file has it MIME type guessed from its extension (if this fails, no MIME type is set).

— saveAs (String)

Where to put the folder on your persistent storage (optional).
By default, the folder will be saved at the root of your agent's folder in your persistent storage.
If files with the same name already exist, they are overwritten.

  • / or empty string (root of your agent's folder in your persistent storage)
  • any/sub/directory
  • dir/foo.txt (this will create a directory named foo.txt, obviously not recommended)

You do not need to create any intermediate directory (a/b/c/d will work).

— callback (Function(err, url))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong (typically if there was a network error or timeout).
  • url (String): the full URL to the folder on your persistent storage.
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)
}
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)
})
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
  }
})

Tips

If you take many screenshots or save many text files with nick rather than calling buster.save() for each file, just do a buster.saveFolder() at the end of your script.

saveText()

saveText(text, saveAs [, mime, callback])

 

Saves a string to a file in your persistent storage.

— text (String)

Contents of the file to save. Can be anything, really.

— saveAs (String)

Where to put the file on your persistent storage.
If a file with the same name already exists, it is overwritten.

  • file.txt
  • any/sub/directory/file.json
  • dir/ (fails because no file name was given)

You do not need to create any intermediate directory (a/b/c/d/e.jpg will work).

— mime (String)

MIME type of the file being saved (optional).
By default, it is guessed either from the Data URI Scheme string or from the file extension of the saveAs parameter (if this fails, no MIME type is set).

  • application/json
  • text/csv
  • text/html

— callback (Function(err, url))

Function called when finished.

  • err (String): null or a description of what went wrong if something went wrong (typically if there was a network error or timeout).
  • url (String): the full url to the file on your persistent storage.
const text   = "This a sample text."
const saveAs = "texts/sample.txt"
const mime   = "text/plain"

try {
  const url = await buster.save(text, saveAs, mime)
  console.log("File successfully saved at:", url)
  // The file is permanently saved at this url you can access
} catch (err) {
  console.log("Could not save file:", err)
}
const text   = "This a sample text."
const saveAs = "texts/sample.txt"
const mime   = "text/plain"

buster.save(text, saveAs, mime)
.then(() => {
  console.log("File successfully saved at:", url)
  // The file is permanently saved at this url you can access
})
.catch((err) =>{
  console.log("Could not save file:", err)
})
var text = "This a sample text."
var saveAs = "texts/sample.txt"
var mime = "text/plain"

buster.save(text, saveAs, mime, function(err, url) {
  if (err) {
    console.log("Could not save file:", err)
  } else {
    console.log("File successfully saved at:", url)
    // The file is permanently saved at this url you can access
  }
})

mail()

mail(subject, text [, to, callback])

 

Sends an email from your agent and substracts 1 to your daily email counter.

— subject (String)

Subject of the email.

— text (String)

Plain text contents of the email.

— to (String)

Where to send the email (optional).
When omitted, the email will be sent to the address associated with your Phantombuster account.

— callback (Function(err))

Function called when finished(optional).

  • err (String): null or a description of what went wrong if something went wrong.
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)
}
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)
})
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
  }
})

pushover()

pushover(message [, options , callback])

 

Sends a push notification to your device(s) using Pushover.

For this call to work, you must have set a Pushover user key in your settings and have installed a Pushover client on at least one of your devices.

— message (String)

Text contents of the notification.

— options (PlainObject)

Additionnal parameters to send to Pushover. Get the full details at the Pushover API documentation.

  • device - your device name to send the message directly to that device, rather than all of your devices (multiple devices may be separated by a comma).
  • title - your message's title, otherwise Phantombuster is used.
  • url - a supplementary URL to show with your message.
  • url_title - a title for your supplementary URL, otherwise just the URL is shown.
  • priority - send as -2 to generate no notification/alert, -1 to always send as a quiet notification or 1 to display as high-priority and bypass your quiet hours.
  • timestamp - a Unix timestamp of your message's date and time to display, rather than the time the message is received by Pushover.
  • sound - the name of one of the sounds supported by device clients to override your default sound choice.

Note: at the moment this method does not support the receipt system of Pushover (priority set to 2).

— callback (Function(err))

Function called when finished(optional).

  • err (String): null or a description of what went wrong if something went wrong.
const message = "This is a sample message for a Pushover notification"
const options = {
  device: "my_device",
  title: "Sample notification",
  url: "https://phantombuster.com",
  url_title: "Phantombuster",
  priority: 1,
  timestamp: 1331249662, //March 8, 2011 17:34:22 CST 
  sound: "magic"
}

try {
  await buster.pushover(message, options)
  //The notification is send with your Pushover settings
} catch (err) {
	console.log("Could not send the notification:", err)
}
const message = "This is a sample message for a Pushover notification"
const options = {
  device: "my_device",
  title: "Sample notification",
  url: "https://phantombuster.com",
  url_title: "Phantombuster",
  priority: 1,
  timestamp: 1331249662, //March 8, 2011 17:34:22 CST 
  sound: "magic"
}

buster.pushover(message, options)
.then(() => {
  //The notification is send with your Pushover settings
})
.catch((err) => {
	console.log("Could not send the notification:", err)
})
var message = "This is a sample message for a Pushover notification"
var options = {
  device: "my_device",
  title: "Sample notification",
  url: "https://phantombuster.com",
  url_title: "Phantombuster",
  priority: 1,
  timestamp: 1331249662, //March 8, 2011 17:34:22 CST 
  sound: "magic"
}

buster.pushover(message, options, function(err) {
  if (err) {
    console.log("Could not send the notification:", err)
  } else {
    //The notification is send with your Pushover settings
  }
})

progressHint()

progressHint(progress [, label])

 

Reports the progress state of the agent.

This affects the width and content of the progress bar displayed in the agent console on Phantombuster.

This is useful for debugging purposes and is not required for the agent to function properly. Sometimes it's just nice to see the progress of your agent in real-time.

— progress (Number)

Progress float value between 0 and 1.

  • 1 means 100% of the work was completed.
  • 0 means 0% of the work was completed.

— label (String)

Optional textual description of the state of your agent (clipped to 50 characters).
This shows up as a text inside the progress bar displayed in the agent console.

buster.progressHint(0.25, "First action") //25% of the work done
buster.progressHint(0.5, "Second action") //50% of the work done
buster.progressHint(0.75, "Third action") //75% of the work done
buster.progressHint(1, "End of the script") //100% of the work done

No callback

This method does not have a callback. Using await is unnecessary.

Tip

When using the standard JSON output from the Phantombuster API to get the console output, the progress object shows up like this:
{
    label: "First action",
    progress: 0.25
}

setResultObject()

setResultObject(object [, callback])

 

Sets (in fact, replaces) the result object of your agent.

Think of the result object as the output value of your agent.
This is useful for returning a small set of JSON fields containing whatever your agent might want to return when it exits.

Use this method in conjunction with the launch <launch-an-agent> API endpoint (with output set to result-object) to launch and get the result of your agent in one single HTTP request.

— object (PlainObject)

Object to set as result object.

— callback (Function(err))

Function called when finished(optional).

  • err (String): null or a description of what went wrong if something went wrong.
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)
}
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)
})
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
  }
})

Tips

Thanks to this function, you can create an endpoint to your bot.
You can integrate this in your own network.

Carefull

Never share your API Key, anyone with this key could change code, call bots and mess with your work.

db.count()

db.count(collection [, options, callback])

 

Returns the number of documents in a collection.

— collection (String)

Name of the collection on which to execute the count operation.

— options (PlainObject)

Additionnal parameters for the request (optional, by default all documents are counted).

  • limit (Number) - limit of documents to count.
  • skip (Boolean) - number of documents to skip for the count.

— callback (Function(err, count))

Function called when finished(optional).

  • err (String): null or a description of what went wrong if something went wrong.
  • count (Number): contains the result of the operation.
const collection = "myCollection"
const options = {
  limit: 100
}

try {
  const count = await buster.db.count(collection, options)
  console.log("Counted the collection", collection, "and the result is:", count)
  // Here the max is 100 because limit is set to 100
} catch (err) {
	console.log("Could not count the collection:", err)
}
const collection = "myCollection"
const options = {
  limit: 100
}

buster.db.count(collection, options)
.then((count) => {
  console.log("Counted the collection", collection, "and the result is:", count)
  // Here the max is 100 because limit is set to 100
})
.catch((err) => {
	console.log("Could not count the collection:", err)
})
var collection = "myCollection"
var options = {
  limit: 100
}

buster.db.count(collection, options, function (err, count) {
	if (err) {
    console.log("Could not count the collection:", err)
  } else {
    console.log("Counted the collection", collection, "and the result is:", count)
    // Here the max is 100 because limit is set to 100
  }
})

db.delete()

db.delete(collection [, options, callback])

 

Deletes documents from a collection.

— collection (String)

Name of the collection from which documents will be deleted.

— options (PlainObject)

Additionnal parameters for the request (optional, by default all documents are deleted).

  • query (PlainObject) - MongoDB query for choosing which documents to delete.
  • extendedJson (Boolean) - enable Extended JSON mode for this query.

— callback (Function(err, res))

Function called when finished(optional).

  • err (String): null or a description of what went wrong if something went wrong.
  • res (PlainObject): contains the result of the operation, res.deletedCount contains the number of deleted document.
const collection = "myCollection"
const options = {
  query: {
    "name": "nick"
  },
  extendedJson: false
}

try {
  const res = await buster.db.delete(collection, options)
  console.log("Deleted", res.deletedCount, "documents in the collection:", collection)
} catch (err) {
	console.log("Could not delete collection:", err)
}
const collection = "myCollection"
const options = {
  query: {
    "name": "nick"
  },
  extendedJson: false
}

buster.db.delete(collection, options)
.then((res) => {
  console.log("Deleted", res.deletedCount, "documents in the collection:", collection)
})
.catch((err) => {
	console.log("Could not delete collection:", err)
})
var collection = "myCollection"
var options = {
  query: {
    "name": "nick"
  },
  extendedJson: false
}

buster.db.delete(collection, options, function(err, res) {
  if (err) {
    console.log("Could not delete collection:", err)
  } else {
    console.log("Deleted", res.deletedCount, "documents in the collection:", collection)
  }
})

db.find()

db.find(collection [, options, callback])

 

Returns documents from a collection.

— collection (String)

Name of the collection in which documents will be searched.

— options (PlainObject)

Additionnal parameters for the request (optional, by default all documents are returned).

  • query (PlainObject) - MongoDB query for choosing which documents to find.
  • limit (Number) - limits the number of documents returned.
  • sort (PlainObject) - how to sort the documents (field names associated with 1 or -1, for example { "name": -1 }).
  • fields (PlainObject) - fields to include 1 or exclude 0, for example: { "name": 1 }.
  • skip (Number) - number of documents to skip (useful for pagination).
  • extendedJson (Boolean) - enable Extended JSON mode for this query.

— callback (Function(err, documents))

Function called when finished(optional).

  • err (String): null or a description of what went wrong if something went wrong.
  • documents (Array): array containing all the documents found.
const collection = "myCollection"
const options = {
  query: {
    "name": "nick"
  },
  limit: 100,
  sort: {
    "age": 1
  },
  fields: {
    "age": 1,
    "name": 1,
    "password": 0
  },
  skip: 0,
  extendedJson: false
}

try {
  const documents = await buster.db.find(collection, options)
  console.log("Found", JSON.stringify(documents, null, 2), "in the collection:", collection)
} catch (err) {
	console.log("Could not find document in the collection:", err)
}
const collection = "myCollection"
const options = {
  query: {
    "name": "nick"
  },
  limit: 100,
  sort: {
    "age": 1
  },
  fields: {
    "age": 1,
    "name": 1,
    "password": 0
  },
  skip: 0,
  extendedJson: false
}

buster.db.find(collection, options)
.then((documents) => {
  console.log("Found", JSON.stringify(documents, null, 2), "in the collection:", collection)
})
.catch((err) => {
	console.log("Could not find document in the collection:", err)
})
var collection = "myCollection"
var options = {
  query: {
    "name": "nick"
  },
  limit: 100,
  sort: {
    "age": 1
  },
  fields: {
    "age": 1,
    "name": 1,
    "password": 0
  },
  skip: 0,
  extendedJson: false
}

buster.db.find(collection, options, function(err, documents) {
	if (err) {
    console.log("Could not find document in the collection:", err)
  } else {
    console.log("Found", JSON.stringify(documents, null, 2), "in the collection:", collection)
  }
})

db.insert()

db.insert(collection, documents [, options, callback])

 

Inserts documents into a collection.

— collection (String)

Name of the collection from which documents will be inserted.

— document (PlainObject/Array)

Document or array of documents to insert into the collection.

— options (PlainObject)

Additionnal parameters for the request (optional).

  • extendedJson (Boolean) - enable Extended JSON mode for this query.

— callback (Function(err, res))

Function called when finished(optional).

  • err (String): null or a description of what went wrong if something went wrong.
  • res (PlainObject): contains the result of the operation, res.insertedCount contains the number of documents inserted by the query and res.insertedIds is an array containing all the newly created MongoDB IDs.
const collection = "myCollection"
const document = {
  "name": "nick",
  "age": 1,
  "password": "pass"
}
const options = {
  extendedJson: false
}

try {
  const res = await buster.db.insert(collection, document, options)
  console.log("Inserted", res.insertedCount, "documents in the collection:", collection, "with the ids:", JSON.stringify(res.insertedIds))
} catch (err) {
	console.log("Could not insert documents in the collection:", err)
}
const collection = "myCollection"
const document = {
  "name": "nick",
  "age": 1,
  "password": "pass"
}
const options = {
  extendedJson: false
}

buster.db.insert(collection, document, options)
.then((res) => {
  console.log("Inserted", res.insertedCount, "documents in the collection:", collection, "with the ids:", JSON.stringify(res.insertedIds))
})
.catch((err) => {
	console.log("Could not insert documents in the collection:", err)
})
var collection = "myCollection"
var document = {
  "name": "nick",
  "age": 1,
  "password": "pass"
}
const options = {
  extendedJson: false
}

buster.db.insert(collection, document, options, function(err, res) {
  if (err) {
    console.log("Could not insert documents in the collection:", err)
  } else {
    console.log("Inserted", res.insertedCount, "documents in the collection:", collection, "with the ids:", JSON.stringify(res.insertedIds))
  }
})

db.setConnectionUrl()

db.setConnectionUrl(url [, callback])

 

Sets the connection string of the MongoDB server you wish to use.

If your Phantombuster account has a database, there is no need to call this method.

— url (String)

Full, canonical MongoDB connection string, for example: mongodb://user:password@host.com:27017/database.

— callback (Function(err))

Function called when finished(optional).

  • err (String): null or a description of what went wrong if something went wrong.

Note

This method must be called prior to any other database methods.

const url = "mongodb://user:password@host.com:27017/database"

try {
  await buster.db.setConnectionUrl(url)
  //Now connected to your DB
} catch (err) {
	console.log("Could not connect to the db:", err)
}
const url = "mongodb://user:password@host.com:27017/database"

buster.db.setConnectionUrl(url)
.then(() => {
  //Now connected to your DB
})
.catch((err) => {
	console.log("Could not connect to the db:", err)
})
var url = "mongodb://user:password@host.com:27017/database"

buster.db.setConnectionUrl(url, function(err) {
  if (err) {
    console.log("Could not connect to the db:", err)
  } else {
    //Now connected to your DB
  }
})

db.update()

db.update(collection, update [, options, callback])

 

Updates documents stored in a collection.

— collection (String)

Name of the collection in which documents will be updated.

— update (PlainObject)

MongoDB update parameter describing what modifications to apply.

— options (PlainObject)

Additionnal parameters for the request (optional, by default all documents are updated).

  • query (PlainObject) - MongoDB filter query for selecting which documents to update.
  • upsert (Boolean) - Do an upsert instead of an update (creates a new document when no document matches the query criteria).
  • extendedJson (Boolean) - enable Extended JSON mode for this query.

— callback (Function(err, res))

Function called when finished(optional).

  • err (String): null or a description of what went wrong if something went wrong.
  • res (PlainObject): contains the result of the operation:
    res.matchedCount contains the number of documents that matched the filter query.
    res. modifiedCount contains the number of documents that were updated by the query.
    res.upsertedCount contains the number of inserted documents in case of an upsert.
    res.upsertedId contains the newly created MongoDB ID in case of an upsert.
const collection = "myCollection"
const update = {
  $set: {
	  "name": "toto"
  },
  $inc: {
    "age": 1
  }
}
const options = {
  query: {
    "name": "nick"
  },
  upsert: false,
  extendedJson: false
}

try {
  const res = await buster.db.update(collection, update, options)
  console.log(res.modifiedCount, "documents modified in the collection:", collection)
} catch (err) {
	console.log("Could not update collection:", err)
}
const collection = "myCollection"
const update = {
  $set: {
	  "name": "toto"
  },
  $inc: {
    "age": 1
  }
}
const options = {
  query: {
    "name": "nick"
  },
  upsert: false,
  extendedJson: false
}

buster.db.update(collection, update, options)
.then((res) => {
  console.log(res.modifiedCount, "documents modified in the collection:", collection)
})
.catch((err) => {
	console.log("Could not update collection:", err)
})
var collection = "myCollection"
var update = {
  $set: {
	  "name": "toto"
  },
  $inc: {
    "age": 1
  }
}
var options = {
  query: {
    "name": "nick"
  },
  upsert: false,
  extendedJson: false
}

buster.db.update(collection, update, options, function(err, res) {
  if (err) {
    console.log("Could not update collection:", err)
  } else {
    console.log(res.modifiedCount, "documents modified in the collection:", collection)
  }
})

agentId

Contains the ID of the currently running agent as a Number.

 

This is useful for making requests to the Phantombuster API from within the agent.

console.log("Bot", buster.agentId, "launched.")
//This will print "Bot XXX launched."

apiKey

Contains your Phantombuster API key as a String.

 

This is useful for making requests to the Phantombuster API from within the agent.

console.log("The API key to launch other agent is:", buster.apiKey)
//This will print "the API key to launch other agent is XXXXXXXXXX"

argument

Contains the agent's argument as a PlainObject.

 

On Phantombuster, each agent receives a JSON object as an argument, which can be set each time they are launched.

/*Bot launched with argument:
{
  "name": "nick",
  "age": 2 
}
*/

const arg = buster.argument

console.log("The name is", arg.name, "and the age is", arg.age)
//This will print "The name is nick and the age is 2"

containerId

Contains the ID of the currently running container as a Number.

 

This is useful for making requests to the Phantombuster API from within the agent.

console.log("Our  container id is", buster.containerId)
//This will print "Our container id is XXXXX"

retryCount

Number indicating on which retry run the bot is currently running.

 

When the agent is configured to retry on failure ("Number of retries" Phantombuster option in the agent settings), this Number indicates on which retry run the bot is. The first run is 0.

if (buster.retryCount > 0) {
  console.log("The previous bot has failed, this is run number", buster.retryCount+1)
} else {
  console.log("This is the first run")
}

maxRetries

Number indicating how many times the agent will automatically restart in case of failure.

 

When the agent is configured to retry on failure ("Number of retries" Phantombuster option in the agent settings), this Number indicates how many times the agent will automatically be restarted in case of failure (exit code different than 0). In case this option is left at its default value (no retries), maxRetries is set to 0.

if (buster.maxRetries === buster.retryCount) {
  console.log("This is the last chance for the bot to work!")
} else {
  console.log("We still have " + (buster.maxRetries - buster.retryCount) + " retries left")
}

proxyAddress

Contains the proxy address currently being used by your agent as a String.

 

Can be an empty string if no proxy is used at the time.
This is useful to know which proxy was selected from a pool.

console.log("The proxy used is:", buster.proxyAddress)
//This will print "The proxy used is: XXX.XXX.XXX.XXX"

download()

download(url [, saveAs, headers, callback])

 

Downloads a distant file to your agent's disk (not to your persistent storage).

If you do not save the file to your persistent storage (see buster.save() or buster.saveFolder()), it will be lost when your agent exits.

— url (String)

URL of the file to be downloaded.

  • https://www.google.com/images/srpr/logo11w.png
  • http://soundcloud.com/ (you'll get the HTML content of their homepage)

— saveAs (String)

Where to put the file on your agent's disk (optional).
By default, the name will be taken from url and the file will be saved in the current working directory on your agent's disk.
If a file with the same name already exists, it is overwritten.

  • foo/ (saves http://example.com/baz/bar.png as foo/bar.png)
  • null (saves http://example.com/foo/bar.png as bar.png)
  • foo/ (fails on http://example.com/ with could not determine filename)
  • foo/a (saves http://example.com/bar.png as foo/a)

Intermediate directories are not created automatically on your agent's disk. When using NodeJS, create directories beforehand with require('fs').mkdirSync().

— headers (Plain Object)

HTTP headers to use when requesting the file (optional).
Cookies are automatically set when using CasperJS or PhantomJS.

— callback (Function(err, path))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong (typically if there was a network error or timeout).
  • path (String): the path to the file on your agent's disk.

Using NodeJS?

When running NodeJS within Phantombuster (the recommended binary), you also have access to common HTTP request modules such as request, needle and fetch. They can come in handy! See packages & modules.

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

Note

This file will be only accessible from your script when it is running. If you want to keep the file in your persistent storage, use buster.save() or buster.saveFolder() or similar.

getAgentObject()

getAgentObject([agentId, callback])

 

Gets the object of an agent. What are agent objects?

— agentId (Number)

ID of the agent from which to get the object (optional).
By default, this is the ID of the currently running agent.

— callback (Function(err, object))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong.
  • object (PlainObject): the content of your agentObject, if the agentObject is not filled then object will be an empty object {}.
/*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)
}
/*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)
})
/*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"
  }
})

Note

The agentId argument should be used just in case you want another agent's object.
To get the current agent object just call buster.getAgentObject().

getGlobalObject()

getGlobalObject([callback])

 

Gets the global object of your account. What is the global object?

— callback (Function(err, object))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong.
  • object (PlainObject): the content of your globalObject, if the globalObject is not filled then object will be an empty object {}.
/*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)
}
/*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)
})
/*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"
  }
})

overrideTimeLimit()

overrideTimeLimit(seconds [, callback])

 

Overrides the execution time limit of the agent.

When the execution time reaches the specified number of seconds, the agent is stopped.

— seconds (Number)

New time limit of the agent in seconds (integer). Setting this parameter to 0 will change the limit to the maximum allowed execution time of an agent.
If the specified number of seconds is already lower than the current execution time, the agent is stopped right away.

— callback (Function(err))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong.
try {
  await buster.overrideTimeLimit(60)
  // Set the time limit at 1 minute
} catch (err) {
  console.log("Could not override the time limit:", err)
}
buster.overrideTimeLimit(60)
.then(() => {
  // Set the time limit at 1 minute
})
.catch((err) => {
  console.log("Could not override the time limit:", err)
})
buster.overrideTimeLimit(60, function(err) {
  if (err) {
    console.log("Could not override the time limit:", err)
  } else {
    // Set the time limit at 1 minute
  }
})

setAgentObject()

setAgentObject([agentId,] object [, callback])

 

Sets (in fact, replaces) the object of an agent. What are agent objects?

— agentId (Number)

ID of the agent from which to get the object (optional).
By default, this is the ID of the currently running agent.

— object (PlainObject)

Object to save.

— callback (Function(err))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong.

Warning

It's recommended to first fetch the object with getAgentObject() (to update it) because this method overwrites the whole object.

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

const agentId = buster.agentId //Useless

try {
  const object = await buster.getAgentObject(agentId)
  object.password = "pass"
  
  await buster.setAgentObject(agentId, object)
  
  const newObject = await buster.getAgentObject(agentId)
  console.log("The name is", newObject.name, ", the age is", newObject.age "and the password is", newObject.password)
  //This will print "The name is nick , the age is 2 and the password is pass"
} catch (err) {
  console.log("Could not change agent object:", err)
}
/*Bot launched with agentObject:
{
  "name": "nick",
  "age": 2 
}
*/

const agentId = buster.agentId //Useless

buster.getAgentObject(agentId)
.then((object) => {
  object.password = "pass"
  return buster.setAgentObject(agentId, object)
})
.then(() => {
  return buster.getAgentObject(agentId)
})
.then((newObject) => {
  console.log("The name is", newObject.name, ", the age is", newObject.age "and the password is", newObject.password)
  //This will print "The name is nick , the age is 2 and the password is pass"
})
.catch((err) => {
  console.log("Could not change agent object:", err)
})
/*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 {
    object.password= "pass"
    buster.setAgentObject(agentId, object, function(err) {
      if (err) {
        console.log("Could not set agent object:", err)
      } else {
        buster.getAgentObject(agentId, function(err, newObject) {
          if (err) {
            console.log("Could not get agent object:", err)
          } else {
            console.log("The name is", newObject.name, ", the age is", newObject.age "and the password is", newObject.password)
            //This will print "The name is nick , the age is 2 and the password is pass"
          }
        })
      }
    })
  }
})

setGlobalObject()

setGlobalObject(object [, callback])

 

Sets (in fact, replaces) the global object of your account. What is the global object?

— object (PlainObject)

Object to save.

— callback (Function(err))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong.

Warning

It's recommended to first fetch the global object with getGlobalObject() (to update it) because this method overwrites the whole object.

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

try {
  const object = await buster.getGlobalObject(agentId)
  object.password = "pass"
  
  await buster.setGlobalObject(agentId, object)
  
  const newObject = await buster.getGlobalObject(agentId)
  console.log("The name is", newObject.name, ", the age is", newObject.age "and the password is", newObject.password)
  //This will print "The name is nick , the age is 2 and the password is pass"
} catch (err) {
  console.log("Could not change global object:", err)
}
/*Bot launched with globalObject:
{
  "name": "nick",
  "age": 2 
}
*/

buster.getGlobalObject(agentId)
.then((object) => {
  object.password = "pass"
  return buster.setGlobalObject(agentId, object)
})
.then(() => {
  return buster.getGlobalObject(agentId)
})
.then((newObject) => {
  console.log("The name is", newObject.name, ", the age is", newObject.age "and the password is", newObject.password)
  //This will print "The name is nick , the age is 2 and the password is pass"
})
.catch((err) => {
  console.log("Could not change global object:", err)
})
/*Bot launched with globalObject:
{
  "name": "nick",
  "age": 2 
}
*/

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

solveCaptcha()

solveCaptcha(selector, casperInstance [, callback])

 

DEPRECATED (see sidebar for details). Solves a CAPTCHA image.

This method takes a screenshot of the area indicated by selector and sends it to one of our partners for solving.

If your CAPTCHA image is trivial, an OCR algorithm will quickly return the text, otherwise a human will solve it. This process generally takes less than 30 seconds and accuracy is >90%.

When a result string is returned, 1 is substracted from your daily CAPTCHA counter. In less than 10% of the cases the result will be incorrect — retry at will.

— selector (String)

CSS path indicating which part of the page to take a screenshot of for solving. Be as precise as possible (sending a large image will fail). Often, a selector for the <img> tag works best.

— casperInstance (CasperJS)

CasperJS instance that will be used for capturing the image. When using NickJS, simply put nick.driver.casper here.

— callback (Function(err, result))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong.
  • result (String): the solved CAPTCHA text.

Deprecation notice

This method is deprecated, please use solveCaptchaBase64() or solveCaptchaImage() instead or solveNoCaptcha() for Google's noCAPTCHA/reCAPTCHA.

Warning

This method is only available when using the CasperJS driver as it uses its screenshot taking capabilities.

const selector = "div.captcha"
const casperInstance = tab.driver.casper

try {
  const result = await buster.solveCaptcha(selector, casperInstance)
  console.log("The captcha text is:", result)
  //You can fill the input with result to access to the protected data
} catch (err) {
  console.log("Could not solve captcha:", err)
}
const selector = "div.captcha"
const casperInstance = tab.driver.casper

buster.solveCaptcha(selector, casperInstance)
.then((result) => {
  console.log("The captcha text is:", result)
  //You can fill the input with result to access to the protected data
})
.catch((err) => {
  console.log("Could not solve captcha:", err)
})
var selector = "div.captcha"
var casperInstance = tab.driver.casper

buster.solveCaptcha(selector, casperInstance, function(err, result) {
  if (err) {
    console.log("Could not solve captcha:", err)
  } else {
    console.log("The captcha text is:", result)
    //You can fill the input with result to access to the protected data
  }
})

solveCaptchaBase64()

solveCaptchaBase64(base64String [, callback])

 

Solves a CAPTCHA image.

This method takes a Base64 encoded image and sends it to one of our partners for solving.

If your CAPTCHA image is trivial, an OCR algorithm will quickly return the text, otherwise a human will solve it. This process generally takes less than 30 seconds and accuracy is >90%.

When a result string is returned, 1 is substracted from your daily CAPTCHA counter. In less than 10% of the cases the result will be incorrect — retry at will.

This method is asynchronous and returns nothing.
Use the callback to know when it has finished.

— base64String (String)

CAPTCHA image to solve.
Can be pure Base64 or a Data URI Scheme string starting with data:.

— callback (Function(err, result))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong.
  • result (String): the solved CAPTCHA text.
const base64String = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAA3XAAAN1wFCKJt4AAAAB3RJTUUH4AoTFC0xuFcAiwAAAgtJREFUOMuVk81rE1EUxX9v5iUzaZKxaWM/UqxV0BZFEUF041ZEBMWFH3t10UX/guIfIHTptijFRaEuXLnrwkWlIii6kGIQ7Efa0urMYJJpk8xcF2PbiRaxZ/O4F95595zzrrrw+ovwBwTQSmGquA4FWiIo/oZOFpFAylAM5ywuFTo4mU0jwEK1wRu3RrnWoBkJRoJJ7UwQCWRMxf3BLu4MdGIb7e/Vw4ipZY+pZZetcI9EJ8ceHerm3kAn+6HDNHh4tItIhMkld7dvQKzvYqGDK4fz/AsKuNF/iOGcRZQkMFGcd2y60yZzbp0HH1d4XN6gJbG0RwvrjH6qMO/WKVmakayFuUNQsjW3BzopWrGap0suT86UOJGzeO8HzLk1zjo2E6f6ma74APTZmuu9DsW0Ro8dKzKSs5j3AgBu9jnMVHxMFOccGwGer3i8XPe52pPfjXXseJHLfoBeDJqcduzfNsK1njyLQZNyrcHE100i4FafQ9Y0OJJJJcxTVFsRenLxB7Pfq9wt7bk/mEmR1wa9dixrKJPGNvdizZoG4wtrfPAD9FYkfKs3YzcTKKRMCilz3zS0Urzz6vGn2olHcTCoZIwASh2UIkEQihCJ/PclQZAkQRAKrzZ+4jUjni25rG23mFn1eevV+VzdZrri4zVDXqz6eK2Q2c0qjUjal0kAEVCq/YzltfeSe/YL9WDOKpeKAEQAAAAASUVORK5CYII="

try {
  const result = await buster.solveCaptchaBase64(base64String)
  console.log("The captcha text is:", result)
  //You can fill the input with result to access to the protected data
} catch (err) {
  console.log("Could not solve the captcha base 64:", err)
}
const base64String = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAA3XAAAN1wFCKJt4AAAAB3RJTUUH4AoTFC0xuFcAiwAAAgtJREFUOMuVk81rE1EUxX9v5iUzaZKxaWM/UqxV0BZFEUF041ZEBMWFH3t10UX/guIfIHTptijFRaEuXLnrwkWlIii6kGIQ7Efa0urMYJJpk8xcF2PbiRaxZ/O4F95595zzrrrw+ovwBwTQSmGquA4FWiIo/oZOFpFAylAM5ywuFTo4mU0jwEK1wRu3RrnWoBkJRoJJ7UwQCWRMxf3BLu4MdGIb7e/Vw4ipZY+pZZetcI9EJ8ceHerm3kAn+6HDNHh4tItIhMkld7dvQKzvYqGDK4fz/AsKuNF/iOGcRZQkMFGcd2y60yZzbp0HH1d4XN6gJbG0RwvrjH6qMO/WKVmakayFuUNQsjW3BzopWrGap0suT86UOJGzeO8HzLk1zjo2E6f6ma74APTZmuu9DsW0Ro8dKzKSs5j3AgBu9jnMVHxMFOccGwGer3i8XPe52pPfjXXseJHLfoBeDJqcduzfNsK1njyLQZNyrcHE100i4FafQ9Y0OJJJJcxTVFsRenLxB7Pfq9wt7bk/mEmR1wa9dixrKJPGNvdizZoG4wtrfPAD9FYkfKs3YzcTKKRMCilz3zS0Urzz6vGn2olHcTCoZIwASh2UIkEQihCJ/PclQZAkQRAKrzZ+4jUjni25rG23mFn1eevV+VzdZrri4zVDXqz6eK2Q2c0qjUjal0kAEVCq/YzltfeSe/YL9WDOKpeKAEQAAAAASUVORK5CYII="

buster.solveCaptchaBase64(base64String)
.then((result) => {
  console.log("The captcha text is:", result)
  //You can fill the input with result to access to the protected data
})
.catch((err) => {
  console.log("Could not solve the captcha base 64:", err)
})
var base64String = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAA3XAAAN1wFCKJt4AAAAB3RJTUUH4AoTFC0xuFcAiwAAAgtJREFUOMuVk81rE1EUxX9v5iUzaZKxaWM/UqxV0BZFEUF041ZEBMWFH3t10UX/guIfIHTptijFRaEuXLnrwkWlIii6kGIQ7Efa0urMYJJpk8xcF2PbiRaxZ/O4F95595zzrrrw+ovwBwTQSmGquA4FWiIo/oZOFpFAylAM5ywuFTo4mU0jwEK1wRu3RrnWoBkJRoJJ7UwQCWRMxf3BLu4MdGIb7e/Vw4ipZY+pZZetcI9EJ8ceHerm3kAn+6HDNHh4tItIhMkld7dvQKzvYqGDK4fz/AsKuNF/iOGcRZQkMFGcd2y60yZzbp0HH1d4XN6gJbG0RwvrjH6qMO/WKVmakayFuUNQsjW3BzopWrGap0suT86UOJGzeO8HzLk1zjo2E6f6ma74APTZmuu9DsW0Ro8dKzKSs5j3AgBu9jnMVHxMFOccGwGer3i8XPe52pPfjXXseJHLfoBeDJqcduzfNsK1njyLQZNyrcHE100i4FafQ9Y0OJJJJcxTVFsRenLxB7Pfq9wt7bk/mEmR1wa9dixrKJPGNvdizZoG4wtrfPAD9FYkfKs3YzcTKKRMCilz3zS0Urzz6vGn2olHcTCoZIwASh2UIkEQihCJ/PclQZAkQRAKrzZ+4jUjni25rG23mFn1eevV+VzdZrri4zVDXqz6eK2Q2c0qjUjal0kAEVCq/YzltfeSe/YL9WDOKpeKAEQAAAAASUVORK5CYII="

buster.solveCaptchaBase64(base64String, function(err, result) {
  if (err) {
    console.log("Could not solve the captcha base 64:", err)
  } else {
    console.log("The captcha text is:", result)
    //You can fill the input with result to access to the protected data
  }
})

solveCaptchaImage()

solveCaptchaImage(urlOrPath [, headers, callback])

 

Solves a CAPTCHA image.

This method takes an URL or a path of an image and sends it to one of our partners for solving.

If your CAPTCHA image is trivial, an OCR algorithm will quickly return the text, otherwise a human will solve it. This process generally takes less than 30 seconds and accuracy is >90%.

When a result string is returned, 1 is substracted from your daily CAPTCHA counter. In less than 10% of the cases the result will be incorrect — retry at will.

This method is asynchronous and returns nothing.
Use the callback to know when it has finished.

— urlOrPath (String)

URL or path of the CAPTCHA image to be solved.

— headers (CasperJS)

HTTP headers to use when fetching the image (optional).
Cookies are automatically set to get the image when using CasperJS or PhantomJS.

— callback (Function(err, result))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong.
  • result (String): the solved CAPTCHA text.
const urlOrPath = "https://phantombuster.com/img/logo3-header.png"
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 result = await buster.solveCaptchaImage(urlOrPath, headers)
  console.log("The captcha text is:", result)
  //You can fill the input with result to access to the protected data
} catch (err) {
  console.log("Could not solve the captcha image:", err)
}
const urlOrPath = "https://phantombuster.com/img/logo3-header.png"
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"
}

buster.solveCaptchaImage(urlOrPath, headers)
.then((result) => {
  console.log("The captcha text is:", result)
  //You can fill the input with result to access to the protected data
})
.catch((err) => {
  console.log("Could not solve the captcha image:", err)
})
var urlOrPath = "https://phantombuster.com/img/logo3-header.png"
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"
}

buster.solveCaptchaImage(urlOrPath, headers, function(err, result) {
  if (err) {
    console.log("Could not solve the captcha image:", err)
  } else {
    console.log("The captcha text is:", result)
    //You can fill the input with result to access to the protected data
  }
})

solveNoCaptcha()

solveNoCaptcha(siteUrl, captchaToken [, secret, callback])

 

Solves a Google noCAPTCHA/reCAPTCHA.

This method sends the required tokens to one of our partners so that a human can solve a Google noCAPTCHA/reCAPTCHA challenge.

buster.solveNoCaptcha() calls will take about 30 to 60+ seconds to return a response token. It mainly depends on the availability of human workers in the queue and their ability to quickly solve the challenges from Google.

When a result token is returned, 2 is substracted from your daily CAPTCHA counter. Contrary to standard image CAPTCHA solving methods, when returned, this token is always valid.

— siteUrl (String)

URL of the page or website where the noCAPTCHA/reCAPTCHA widget is found.
When using NickJS, simply use the return value from tab.getUrl().

— captchaToken (String)

Token of the noCAPTCHA/reCAPTCHA widget. This token is generally found in the data-sitekey attribute of the <div class="g-recaptcha"> element. However, some site administrators use the widget differently and you might have to find this token somewhere else, for example in the &k=<TOKEN> parameter of the URL of the widget's <iframe>.

— secret (String)

Second token from the noCAPTCHA/reCAPTCHA widget (optional).
Almost all websites do not use this token anymore, it is only for deprecated noCAPTCHA/reCAPTCHA versions. If present, it's generally found in the data-stoken attribute of the widget's <div>.

— callback (Function(err, result))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong.
  • result (String): the response token, put this as a value in the <textarea id="g-recaptcha-response"> element and submit the form.

Custom noCAPTCHA/reCAPTCHA installations

Not all websites use this CAPTCHA system the same way. The widget supports custom JavaScript integration, as you can see in its official documentation. If that's the case on your target website (not common), you'll first have to understand how the widget is integrated to get its token and to submit the result.

Also supports "invisible" noCAPTCHA!

The new "invisible" noCAPTCHA is basically the same widget but hidden in the page and automatically activated. Check its official documentation to understand how your target website might integrate it.

const siteUrl = "https://www.google.com/recaptcha/api2/demo"
const captchaToken = await tab.evaluate((args, callback) => {
  const token = document.querySelector(".g-recaptcha[data-sitekey]").dataset.sitekey
  callback(null, token)
}, null)

try {
  const result = await buster.solveNoCaptcha(siteUrl, captchaToken)
  console.log("The reCAPTCHA response token is:", result)
  //You can fill the g-recaptcha-response <textarea> with result to access to the protected data
} catch (err) {
  console.log("Could not solve reCAPTCHA:", err)
}
const siteUrl = "https://www.google.com/recaptcha/api2/demo"
const captchaToken = "reC4PTCH4_token"

buster.solveNoCaptcha(siteUrl, captchaToken)
.then((result) => {
  console.log("The reCAPTCHA text is:", result)
  //You can fill the input with result to access to the protected data
})
.catch((err) => {
  console.log("Could not solve reCAPTCHA:", err)
})
const siteUrl = "https://www.google.com/recaptcha/api2/demo"
const captchaToken = "reC4PTCH4_token"

buster.solveCaptcha(siteUrl, captchaToken, function(err, result) {
  if (err) {
    console.log("Could not solve reCAPTCHA:", err)
  } else {
    console.log("The reCAPTCHA text is:", result)
    //You can fill the input with result to access to the protected data
  }
})

getTimeLeft()

getTimeLeft([callback])

 

Returns the number of seconds left before the agent is killed for time limit reasons.

This is very useful for saving data and exiting properly before being killed by Phantombuster for time limit reasons. Simply call this method and check if you have more than 60 seconds left for example.

Phantombuster has a "soft abort" feature: when the STOP button is shift-clicked (maintain the shift key while clicking on STOP), all subsequent calls to buster.getTimeLeft() will return -1. That way, your agent can save its data and do other specific actions before exiting gracefully instead of being immediately killed as is the case for a regular click on the STOP button.

In addition, Phantombuster will detect when you use buster.getTimeLeft() and show an ABORT button instead of a STOP button. The ABORT button has the same behavior as a shift-clicked STOP button.

Note: This method's result is cached for 10 seconds. You can call this method any number of times but the result will only change every 10 seconds.

Note: This method will find the lowest possible time limit, which can be either the agent's own time limit, your account global time limit (according to your plan) or the maximum allowed Phantombuster agent run time.

— callback (Function(err, timeLeft))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong.
  • timeLeft (Number): the number of seconds left before the agent is killed or -1 if the STOP button was shift-clicked (or if the ABORT button was clicked).
try {
  const timeLeft = await buster.getTimeLeft()
  console.log(`I have ${timeLeft} seconds before being killed`)
} catch (err) {
  console.log("Could not get time left:", err)
}
buster.getTimeLeft()
.then((timeLeft) => {
  console.log(`I have ${timeLeft} seconds before being killed`)
})
.catch((err) => {
  console.log("Could not get time left:", err)
})
buster.getTimeLeft(function(err, timeLeft) {
  if (err) {
    console.log("Could not get time left:", err)
  } else {
    console.log("Number of seconds left before being killed:", timeLeft)
  }
})

Nick

Nick([options])

 

This is Nick's constructor. options is an optional argument that lets you configure your Nick instance.

NickJS must be instantiated only once. Behind the scenes, the headless browser driver is initialized. The next step is to open a tab with newTab().

— [options] (PlainObject)

Optional settings for the Nick instance.

  • printNavigation (Boolean): when true (the default), Nick will log important navigation information like page changes, redirections and form submissions
  • printResourceErrors (Boolean): when true (the default), Nick will log all the errors encountered when loading pages, images and all other resources needed by the pages you visit
  • printPageErrors (Boolean): when true (the default), Nick will log all JavaScript errors and exceptions coming from the scripts executed in the page context
  • printAborts (Boolean): when true (the default), Nick will log requests aborted by the blacklist or whitelist
  • timeout (Number): milliseconds after which Nick will abort loading a resource (page, images and all other resources needed by the pages you visit) — defaults to 10000ms (note: this only works for "page open" timeouts when using Chrome)
  • userAgent (String): sets the User-Agent header — by default NickJS uses an innocuous looking macOS Chrome user agent string
  • loadImages (Boolean): whether or not to load the images embedded in the pages (defaults to true) — can also be configured by setting the environment variable NICKJS_LOAD_IMAGES to 0 or 1 (however, this constructor option takes precedence)
  • blacklist (Array): a list of URLs as strings or regexes (can be a mix of both) that will be blocked from loading (strings will only match the beginning of the URL and the protocol portion can be omitted)
  • whitelist (Array): a list of URLs as strings or regexes (can be a mix of both) that are the only URLs allowed to load (strings will only match the beginning of the URL and the protocol portion can be omitted) — note: the blacklist is applied after the whitelist
  • httpProxy (String): HTTP or HTTPS proxy to use in the form username:password@proxy.com:3128 (NickJS does not yet support other types of proxies) — can also be configured by setting the environment variable NICKJS_PROXY or HTTP_PROXY or http_proxy (however, this constructor option takes precedence)
  • width (Number): Viewport width (defaults to 1280)
  • height (Number): Viewport height (defaults to 800)
  • debug (Boolean): print internal debugging information if available (enable this only if you know what you're doing)
const Nick = require("nickjs")
const nick = new Nick()
var Nick = require('nickjs')
var nick = new Nick()
const Nick = require("nickjs")

const nick = new Nick({
  printNavigation: true,
  printResourceErrors: true,
  printPageErrors: true,
  resourceTimeout: 10000,
  userAgent: "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.143 Safari/537.36",
  blacklist: [
    "sidecar.gitter.Im",
    /^.*\.woff$/
   	]
})
var Nick = require('nickjs')

var nick = new Nick({
  printNavigation: true,
  printResourceErrors: true,
  printPageErrors: true,
  resourceTimeout: 10000,
  userAgent: "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.143 Safari/537.36",
  blacklist: [
    "sidecar.gitter.Im",
    /^.*\.woff$/
  ]
})

newTab()

 

Opens a new tab.

This is the first step in manipulating a website.

To open multiple tabs, call this method multiple times. If your bot opens many tabs to do different tasks, it's a good idea to close() them when their work is finished (to keep memory usage down).

try {
  const tab = await nick.newTab()
  // You can now browse any website using `tab`
} catch (err) {
  console.log("An error occured:", err)
}
nick.newTab()
.then((tab) => {
  // You can now browse any website using `tab`
})
.catch((err) => {
  console.log("An error occured:", err)
})
nick.newTab( function(err, tab) {
  if (err) {
    console.log("An error occured:", err)
  } else {
    // You can now browse any website using `tab`
  }
})

exit()

exit([code])

 

Immediately stops the whole bot and exits the process with code.

— [code] (Number)

Optional exit code that the process should return. 0 by default.

nick.exit() // All is well
nick.exit(1) // Something went horribly wrong

driver

 

nick.driver lets you access the underlying headless browser driver instance that is being used by Nick.

This is useful when doing trickier things in your navigation and for accessing driver-specific methods that are not available in Nick.

// In this case we're using the PhantomJS+CasperJS driver
// This gets the CasperJS instance and clears the cache
nick.driver.casper.page.clearMemoryCache()

setCookie()

setCookie(cookie[, callback])

 

Sets a cookie.

Set the name, the value and the domain of a cookie.
This cookie can be seen with getAllCookies() and deleted with deleteAllCookies() or deleteCookie().

— cookie (PlainObject)

An object containing the attributes of the new cookie.

  • name (String): Name of the cookie you want to set.
  • value (String): Value of the cookie you want to set.
  • domain (String): Domain linked to the cookie set.

— callback (Function)

Function called when finished(optional).

  • err (String): null or a description of what went wrong if something went wrong.
const cookie = {
  name: "cookieName",
  value: "cookieValue",
  domain: "domain.com"
}

try {
  await nick.setCookie(cookie)
  // You can navigate with your cookie set
} catch (err) {
  console.log("Could not create cookie:", err)
}
const cookie = {
  name: "cookieName",
  value: "cookieValue",
  domain: "domain.com"
}

nick.setCookie(cookie)
.then(() => {
  // You can navigate with your cookie set
})
.catch(err => {
  console.log("Could not create cookie:", err)
})
var cookie = {
  name: "cookieName",
  value: "cookieValue",
  domain: "domain.com"
}

nick.setCookie(cookie, function(err) {
  if (err) {
    console.log("Could not create cookie:", err)
  } else {
    // You can navigate with your cookie set
  }
})

deleteCookie()

deleteCookie(cookieName, cookieDomain[, callback])

 

Deletes a specific cookie set in the headless browser.

— callback (Function)

Function called when finished(optional).

  • err (String): null or a description of what went wrong if something went wrong.
const cookieName = "cookieName"
const cookieDomain = "domain.com"

try {
  await nick.deleteCookie(cookieName, cookieDomain)
} catch (err) {
  console.log("Could not delete cookie:", err)
}
const cookieName = "cookieName"
const cookieDomain = "domain.com"

nick.deleteCookie(cookieName, cookieDomain)
.then(() => {
  // Your cookie is deleted
})
.catch(err => {
  console.log("Could not delete cookie:", err)
})
var cookieName = "cookieName"
var cookieDomain = "domain.com"

nick.deleteCookie(cookieName, cookieDomain, function (err) {
  if (err) {
    console.log("Could not delete cookie:", err)
  } else {
    // Your cookie is deleted
  }
})

deleteAllCookies()

deleteAllCookies([callback])

 

Removes all cookies from the headless browser.

— callback (Function)

Function called when finished(optional).

  • err (String): null or a description of what went wrong if something went wrong

Warning

This method will delete all cookies that might be necessary to your bot.

try {
  await nick.deleteAllCookies()
  // All cookies are cleanded up
} catch (err) {
  console.log("Could not delete all cookies:", err)
}
nick.deleteAllCookies()
.then(() => {
  // All cookies are cleanded up
.catch(err => {
  console.log("Could not delete all cookies:", err)
}
nick.deleteAllCookies(function (err) {
  if (err) {
    console.log("Could not delete all cookies:", err)
  } else {
    // All cookies are cleanded up
  }
})

getAllCookies()

getAllCookies([callback])

 

Returns an array containing all the cookies currently in use by the headless browser.

— callback (Function)

Function called when finished(optional).

  • err (String): null or a description of what went wrong if something went wrong.
  • cookies (Array): an array containing all cookies of the headless browser and their properties
try {
  const cookies = await nick.getAllCookies()
  // Cookies contain all your cookies
  console.log(cookies, null, 2)
} catch (err) {
  console.log("Could not get all cookies:", err)
}
nick.getAllCookies()
.then(cookies => {
  // Cookies contain all your cookies
  console.log(cookies, null, 2)
})
.catch(err => {
  console.log("Could not get all cookies:", err)
})
nick.getAllCookies(function(err) {
  if (err) {
    console.log("Could not get all cookies:", err)
  } else {
    // Cookies contain all your cookies
    console.log(cookies, null, 2)
  }
})

open()

open(url [, options, callback])

 

Opens the webpage at url.

Opening a page will time out after 10 seconds. This can be changed with the timeout Nick option (see Nick's options). Note: this time out concerns the initial page but not the resources the page requires thereafter.

— url (String)

URL of the page to open. Should begin with http:// or https:// (or file:// to open a page that was previously downloaded to your agent's disk).

— [options] (PlainObject)

Request configuration (optional). At this time, this object is ignored by the Chrome driver, it only has an effect with the CasperJS driver.

{
  method: "post",
  data:   {
    "some param": "some data",
    "another field":  "this is sent in x-www-form-urlencoded format"
  },
  headers: {
    "Accept-Language": "fr,fr-fr;q=0.8,en-us;q=0.5,en;q=0.3"
  }
}

— callback (Function(err, httpCode, httpStatus, url))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong (typically if there was a network error or timeout)
  • httpCode (Number): the received HTTP code or null if there was a network error
  • httpStatus (String): text equivalent of the received HTTP code or null if there was a network error — can sometimes be an empty string or null even when the request was successful, do not use this value for something critical
  • url (String): the actually opened URL (can be different from the input URL in case of 3xx redirects for example) or null if there was a network error
const url = "https://phantombuster.com/"

try {
  const [httpCode, httpStatus] = await tab.open(url)
  
  if ((httpCode >= 300) || (httpCode < 200)) {
    console.log("The site responded with", httpCode, httpStatus)
  } else {
    console.log("Successfully opened", url, ":", httpCode, httpStatus)
    // Manipulate the page in this branch
    // You should probably do a waitUntilVisible() or waitUntilPresent() here
  }
} catch(err) {
  console.log("Could not open page:", err)
}
const url = "https://phantombuster.com/"

tab.open(url)
.then((httpCode, httpStatus) => {
  if ((httpCode >= 300) || (httpCode < 200)) {
    console.log("The site responded with", httpCode, httpStatus)
  } else {
    console.log("Successfully opened", url,":", httpCode, httpStatus)
    // Manipulate the page in this branch
    // You should probably do a waitUntilVisible() or waitUntilPresent() here
  }
})
.catch((err, httpCode, httpStatus) => {
  console.log("Could not open page:", err)
})
var url = "https://phantombuster.com/"

tab.open(url, function(err, httpCode, httpStatus, url) {
  if (err) {
    console.log("Could not open page:", err)
  } else if ((httpCode >= 300) || (httpCode < 200)) {
    console.log("The site responded with", httpCode, httpStatus)
  } else {
    console.log("Successfully opened", url, ":", httpCode, httpStatus)
    // Manipulate the page in this branch
    // You should probably do a waitUntilVisible() or waitUntilPresent() here
  }
});

Know your errors

This method will NOT return an error when the received HTTP isn't 200. An error is returned only when a network error happens. It's your job to check for 404s or 500s with httpCode if needed.

Always wait for DOM elements

Many pages on the web load slowly and unreliably. Many more make numerous aynchronous queries. For these reasons, you should always wait for the DOM elements that interest you after opening a page with waitUntilVisible()or waitUntilPresent().

waitUntilVisible()

waitUntilVisible(selectors [, timeout, condition, callback])

 

Waits for a list of selectors CSS selectors to be visible.
Aborts with an error if the elements have not become visible after timeout milliseconds.

selectors can be an array of CSS selectors (array of strings) or a single CSS selector (string).

By default, condition is "and" (wait for all CSS selectors) but it can be changed to "or" (wait for any CSS selector).

— selectors (Array or String)

What to wait for. Can be an array of CSS selectors (array of strings) or a single CSS selector (string).

— timeout (Number)

Maximum number of milliseconds to wait for, by default it is set to 5000(optional).
callback will be called with an error if the elements have not become visible after timeout milliseconds.

— [condition] (String)

When selectors is an array, this optional argument lets you choose how to wait for the CSS selectors(optional).
If condition is "and" (the default), the method will wait for all CSS selectors.
On the other hand, if condition is "or", the method will wait for any CSS selector.

— callback (Function(err, selector))

Function called when finished(optional).

  • err (String): null or a description of what went wrong if the CSS selectors were not visible after timeout milliseconds
  • selector (String):
    • In case of success (err is null):
      • If condition was "and" then selector is null because all CSS selectors are visible
      • If condition was "or" then selector is one of the visible CSS selectors of the given array
    • In case of failure (err is not null):
      • If condition was "and" then selector is one of the non-visible CSS selectors of the given array
      • If condition was "or" then selector is null because none of the CSS selectors are visible
const selectors = "#header > h1.big-title"
const pageTimeout = 5000

try {
  await tab.waitUntilVisible(selectors, pageTimeout)
  // Manipulate the element here
  // for example with a click() or evaluate()
} catch(err) {
  console.log("Oh no! Even after 5s, the element was still not visible:", err)
}
const selectors = "#header > h1.big-title"
const pageTimeout = 5000

tab.waitUntilVisible(selectors, pageTimeout)
.then(() => {
  // Manipulate the element here
  // For example with a click() or evaluate()
})
.catch((err, selector) => {
  console.log("Oh no! Even after 5s, the element was still not visible:", err)
  console.log("This element is not visible:", selector)
})
var selectors = "#header > h1.big-title"
var pageTimeout = 5000

tab.waitUntilVisible(selectors, pageTimeout, function(err, selector) {
  if (err) {
    console.log("Oh no! Even after 5s, the element was still not visible:", err)
    console.log("This element is not visible:", selector)
  } else {
    // Manipulate the element here
    // For example with a click() or evaluate()
  }
})
const selectors = ["#header > h1", "img.product-image"]
const pageTimeout = 6000

try {
  await tab.waitUntilVisible(selectors, pageTimeout)
  // Manipulate the element here
  // for example with a click() or evaluate()
} catch(err) {
  console.log("Oh no! Even after 6s, at least one of the element was still not visible:", err)
}
const selectors = ["#header > h1", "img.product-image"]
const pageTimeout = 6000

tab.waitUntilVisible(selectors, pageTimeout)
.then(() => {
  // Manipulate the element here
  // For example with a click() or evaluate()
})
.catch((err, selector) => {
  console.log("Oh no! Even after 6s, at least one of the element was still not visible:", err)
    console.log("This element is not visible:", selector)
})
var selectors = ["#header > h1", "img.product-image"]
var pageTimeout = 6000

tab.waitUntilVisible(selectors, pageTimeout, "and", function(err, selector) {
  if (err) {
    console.log("Oh no! Even after 6s, at least one of the element was still not visible:", err)
    console.log("This element is not visible:", selector)
  } else {
    // Manipulate the element here
    // For example with a click() or evaluate()
  }
})
var selectors = ["section.footer", "section.header"]
var pageTimeout = 7000

try {
  const selector = await tab.waitUntilVisible(selectors, pageTimeout)
  console.log("This element is visible: " + selector)
  // Manipulate the element here
  // For example with a click() or evaluate()
} catch(err) {
  console.log("Oh no! Even after 7s, all the elements were still not visible. " + err)
  // in this case, the callback does not return which element is not visible
  // because ALL the elements are not visible
}
var selectors = ["section.footer", "section.header"]
var pageTimeout = 7000

tab.waitUntilVisible(selectors, pageTimeout)
.then((selector) => {
  console.log("This element is visible: " + selector)
  // Manipulate the element here
  // For example with a click() or evaluate()
})
.catch((err) => {
  console.log("Oh no! Even after 7s, all the elements were still not visible:", err)
  // in this case, the callback does not return which element is not visible
  // because ALL the elements are not visible
})
var selectors = ["section.footer", "section.header"]
var pageTimeout = 7000

tab.waitUntilVisible(selectors, pageTimeout, "or", function(err, selector) {
  if (err) {
    console.log("Oh no! Even after 7s, all the elements were still not visible:", err)
    // in this case, the callback does not return which element is not visible
    // because ALL the elements are not visible
  } else {
    console.log("This element is visible:", selector)
    // Manipulate the element here
    // For example with a click() or evaluate()
  }
})

waitWhileVisible()

waitWhileVisible(selectors [, timeout, condition, callback])

 

Waits for a list of selectors CSS selectors to become non-visible.
Aborts with an error if the elements are still visible after timeout milliseconds.

selectors can be an array of CSS selectors (array of strings) or a single CSS selector (string).

By default, condition is "and" (wait for all CSS selectors) but it can be changed to "or" (wait for any CSS selector).

— selectors (Array or String)

What to wait for. Can be an array of CSS selectors (array of strings) or a single CSS selector (string).

— timeout (Number)

The maximum number of milliseconds to wait for, by default it is set to 5000 (optional).
callback will be called with an error if the elements are still visible after timeout milliseconds.

— [condition] (String)

When selectors is an array, this optional argument lets you choose how to wait for the CSS selectors(optional).
If condition is "and" (the default), the method will wait for all CSS selectors.
On the other hand, if condition is "or", the method will wait for any CSS selector.

— callback (Function(err, selector))

Function called when finished(optional).

  • err (String): null or a description of what went wrong if the CSS selectors were still visible after timeout milliseconds
  • selector (String):
    • In case of success (err is null):
      • If condition was "and" then selector is null because none of the CSS selectors are visible
      • If condition was "or" then selector is one of the non-visible CSS selectors of the given array
    • In case of failure (err is not null):
      • If condition was "and" then selector is one of the still visible CSS selectors of the given array
      • If condition was "or" then selector is null because all of the CSS selectors are still visible
const selectors = "#header > h1.big-title"
const pageTimeout = 5000

try {
  await tab.waitWhileVisible(selectors, pageTimeout)
  // The selector has succesfully become non-visible
} catch(err) {
  console.log("Oh no! Even after 5s, the element was still visible:", err)
}
const selectors = "#header > h1.big-title"
const pageTimeout = 5000

tab.waitUntilVisible(selectors, pageTimeout)
.then(() => {
  // The selector has succesfully become non-visible
})
.catch((err, selector) => {
  console.log("Oh no! Even after 5s, the element was still visible:", err)
  console.log("This element is visible: ", selector)
})
var selectors = "#header > h1.big-title"
var pageTimeout = 5000

tab.waitUntilVisible(selectors, pageTimeout, function(err, selector) {
  if (err) {
    console.log("Oh no! Even after 5s, the element was still visible. ", err)
    console.log("This element is visible: ", selector)
  } else {
    // The selector has succesfully become non-visible
  }
})

waitUntilPresent()

waitUntilPresent(selectors [, timeout, condition, callback])

 

Waits for a list of selectors CSS selectors to be present in the DOM.
Aborts with an error if the elements have not become present in the DOM after timeout milliseconds.

const selectors = "#header > h1.big-title"
const pageTimeout = 5000

try {
  await tab.waitUntilPresent(selectors, pageTimeout)
  // The element is present in the DOM
} catch(err) {
  console.log("Oh no! Even after 5s, the element was still not present. ", err)
}
const selectors = "#header > h1.big-title"
const pageTimeout = 5000

tab.waitUntilVisible(selectors, pageTimeout)
.then(() => {
  // The element is present in the DOM
})
.catch((err, selector) => {
  console.log("Oh no! Even after 5s, the element was still not present:", err)
  console.log("This element is not present: ", selector)
})
var selectors = "#header > h1.big-title"
var pageTimeout = 5000

tab.waitUntilVisible(selectors, pageTimeout, function(err, selector) {
  if (err) {
    console.log("Oh no! Even after 5s, the element was still not present:", err)
    console.log("This element is not visible:", selector)
  } else {
    // The element is present in the DOM
  }
})

selectors can be an array of CSS selectors (array of strings) or a single CSS selector (string).

By default, condition is "and" (wait for all CSS selectors) but it can be changed to "or" (wait for any CSS selector).

— selectors (Array or String)

What to wait for. Can be an array of CSS selectors (array of strings) or a single CSS selector (string).

— timeout (Number)

Maximum number of milliseconds to wait for, by default it is set to 5000(optional).
callback will be called with an error if the elements have not become present after timeout milliseconds.

— [condition] (String)

When selectors is an array, this optional argument lets you choose how to wait for the CSS selectors(optional).
If condition is "and" (the default), the method will wait for all CSS selectors.
On the other hand, if condition is "or", the method will wait for any CSS selector.

— callback (Function(err, selector))

Function called when finished(optional).

  • err (String): null or a description of what went wrong if the CSS selectors were not present after timeout milliseconds
  • selector (String):
    • In case of success (err is null):
      • If condition was "and" then selector is null because all CSS selectors are present
      • If condition was "or" then selector is one of the present CSS selectors of the given array
    • In case of failure (err is not null):
      • If condition was "and" then selector is one of the non-present CSS selectors of the given array
      • If condition was "or" then selector is null because none of the CSS selectors are present

waitWhilePresent()

waitWhilePresent(selectors [, timeout, condition, callback])

 

Waits for a list of selectors CSS selectors to become non-present in the DOM.
Aborts with an error if the elements are still present in the DOM after timeout milliseconds.

selectors can be an array of CSS selectors (array of strings) or a single CSS selector (string).

By default, condition is "and" (wait for all CSS selectors) but it can be changed to "or" (wait for any CSS selector).

— selectors (Array or String)

What to wait for. Can be an array of CSS selectors (array of strings) or a single CSS selector (string).

— timeout (Number)

The maximum number of milliseconds to wait for, by default it is set to 5000 (optional).
callback will be called with an error if the elements are still present after timeout milliseconds.

— [condition] (String)

When selectors is an array, this optional argument lets you choose how to wait for the CSS selectors (optional).
If condition is "and" (the default), the method will wait for all CSS selectors.
On the other hand, if condition is "or", the method will wait for any CSS selector.

— callback (Function(err, selector))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if the CSS selectors were still present after timeout milliseconds
  • selector (String):
    • In case of success (err is null):
      • If condition was "and" then selector is null because none of the CSS selectors are present
      • If condition was "or" then selector is one of the non-present CSS selectors of the given array
    • In case of failure (err is not null):
      • If condition was "and" then selector is one of the still present CSS selectors of the given array
      • If condition was "or" then selector is null because all of the CSS selectors are still present
const selectors = "#header > h1.big-title"
const pageTimeout = 5000

try {
  await tab.waitWhilePresent(selectors, pageTimeout)
  // The selector has succesfully become non-present
} catch(err) {
  console.log("Oh no! Even after 5s, the element was still present:", err)
}
const selectors = "#header > h1.big-title"
const pageTimeout = 5000

tab.waitUntilPresent(selectors, pageTimeout)
.then(() => {
  // The selector has succesfully become non-present
})
.catch((err, selector) => {
  console.log("Oh no! Even after 5s, the element was still present:", err)
  console.log("This element is present: ", selector)
})
var selectors = "#header > h1.big-title"
var pageTimeout = 5000

tab.waitUntilPresent(selectors, pageTimeout, function(err, selector) {
  if (err) {
    console.log("Oh no! Even after 5s, the element was still present:", err)
    console.log("This element is present:", selector)
  } else {
    // The selector has succesfully become non-present
  }
})

click()

click(selector[, callback])

 

Performs a click on the element matching the CSS selector selector.

Clicking on elements is one of the main ways to manipulate web pages with Nick. Clicking is an easy way to navigate where you want, but keep in mind that it can be more efficient to scrape URLs (for example with evaluate()) and then call open().

— selector (String)

CSS selector targeting what element to click.
Probably a button or an a but can be anything you want.
Make sure the target element is visible or present by calling waitUntilVisible() or waitUntilPresent() beforehand.

— callback (Function(err))

Function called when finished (optional).

  • err (String): null or a string describing what went wrong with the click (typically the CSS selector did no match any element)
const selector = "button.cool-button"
const pageTimeout = 5000

try {
  await tab.waitUntilPresent(selector, pageTimeout)
  await tab.click(selector)
} catch (err) {
  console.log("An error occured:", err)
}
// Continue your navigation in this branch
// You should probably do a waitUntilVisible() or waitUntilPresent() here
const selector = "button.cool-button"
const pageTimeout = 5000

tab.waitUntilPresent(selector, pageTimeout)
.then(() => {
  return tab.click(selector)
})
.then(() => {
  // Continue your navigation in this branch
  // You should probably do a waitUntilVisible() or waitUntilPresent() here
})
.catch((err) => {
  console.log("An error occured:", err)
})
var selector = "button.cool-button"
var pageTimeout = 5000

tab.waitUntilPresent(selector, pageTimeout, function(err) {
  if (err) {
    console.log("The button is not present, so we cannot click on it...")
  } else {
    tab.click(selector, function(err) {
      if (err) {
        console.log("Oops, could not click on the button:", err)
      } else {
        // Continue your navigation in this branch
        // You should probably do a waitUntilVisible() or waitUntilPresent() here
      }
    })
  }
})

Make sure your target is here

Before calling click() you should make sure the element you are trying to click on is actually visible or present in the page by using waitUntilVisible() or waitUntilPresent().

screenshot()

screenshot(filename [, options, callback])

 

Takes a screenshot of the current page.

Not yet implemented but coming soon: support for PDF, clipping (clipRect), selector screenshot (selector), base64 instead of file to disk (filename set to base64:png or base64:jpg).

— filename (String)

Where to save the image on disk. The format is defined by the file extension, it defaults to JPEG. 'image.jpg' will create a JPEG image in the current working directory. There are two supported formats: png and jpg.

— options (PlainObject)

Screenshot configuration (optional).

{
  quality: 80, // used only when generating a JPEG image (75 by default)
  fullPage: true // this is true by default, can only be disabled with the Chrome driver
}

— callback (Function(err))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong
  • filename (String): path of the image file on disk (if the screenshot was successful)
try {
  const path = await tab.screenshot("image.jpg")
  console.log("Screenshot saved at", path)
  // Your screenshot is available at this path
} catch (err) {
  console.log("Could not take a screenshot:", err)
}
const path = "./image.jpg"

tab.screenshot(path)
.then(() => {
  console.log("Screenshot saved at", path)
  // Your screenshot is available at this path
})
.catch((err) => {
  console.log("Could not take a screenshot:", err)
})
var path = "./image.jpg"

tab.screenshot(path, function(err) {
  if (err) {
    console.log("Could not take a screenshot:", err)
  }
  else {
    console.log("Screenshot saved at", path)
		// Your screenshot is available at this path
  }
})

inject()

inject(urlOrPath [, callback])

 

Injects a script in the current DOM page context.

The script can be stored locally on disk or on a remote server.

— urlOrPath (String)

Path to a local or remote script.

— callback (Function(err))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong
const urlOrPath = "https://code.jquery.com/jquery-3.2.1.min.js"

try {
  await tab.inject(urlOrPath)
  console.log("Jquery script inserted!")
  //You may now use tab.evaluate() and use jQuery functions
} catch (err) {
  console.log("Could not inject jQuery:", err)
}
const urlOrPath = "https://code.jquery.com/jquery-3.2.1.min.js"

tab.inject(urlOrPath)
.then(() => {
  console.log("Jquery script inserted!")
  //You may now use tab.evaluate() and use jQuery functions
})
.catch((err) => {
  console.log("Could not inject jQuery:", err)
})
var urlOrPath = "https://code.jquery.com/jquery-3.2.1.min.js"

tab.inject(urlOrPath, function(err) {
  if (err) {
    console.log("Could not inject jQuery:", err)
  }
  else {
    console.log("Jquery script inserted!")
    //You may now use tab.evaluate() and use jQuery functions
  }  
})

Phantombuster

When using NickJS on the Phantombuster platform, your bot has access to injectable JS modules already present on the disk. No need to make an additional request to a CDN to load the most common modules!

For example: await tab.inject('../injectables/jquery-3.0.0.min.js')

List of all injectable modules →

fill()

fill(selector, inputs [, submit, callback])

 

Fills a form with the given values and optionally submits it.

Inputs are referenced by their name attribute.

— selector (String)

CSS selector targeting what form to fill. It should point to a form tag. Make sure the target form is visible or present by calling waitUntilVisible() or waitUntilPresent() beforehand.

— inputs (PlainObject)

An object containing the data you want to enter in the form.
Keys must correspond to the inputs' name attribute. This method supports single select fields in the same way as normal input fields. For select fields allowing multiple selections, supply an array of values to match against.

— options (Boolean)

  • submit (Boolean): Whether or not to submit the form after filling it (false by default).

— callback (Function(err))

Function called when finished.

  • err (String): null or a string describing what went wrong when filling the form
const selector = "#contact-form"
const inputs = {
  "subject": "I am watching you",
  "content": "So be careful.",
  "civility": "Mr",
  "name": "Chuck Norris",
  "email": "chuck@norris.com",
  "cc": true,
  "attachment": "roundhousekick.doc" // file taken from your agent's disk
}

try {
  await tab.waitUntilVisible(selector, 5000)
  await tab.fill(selector, inputs, { submit: true })
  console.log("Form sent!")
  // Continue your navigation in this branch
  // You should probably do a waitUntilVisible() or waitUntilPresent() here
} catch (err) {
  console.log("Form not found:", err)
}
const selector = "#contact-form"
const inputs = {
  "subject": "I am watching you",
  "content": "So be careful.",
  "civility": "Mr",
  "name": "Chuck Norris",
  "email": "chuck@norris.com",
  "cc": true,
  "attachment": "roundhousekick.doc" // file taken from your agent's disk
}

tab.waitUntilVisible(selector, 5000)
.then(() => {
  return tab.fill(selector, inputs, { submit: true })
})
.then(() => {
  console.log("Form sent!")
  // Continue your navigation in this branch
  // You should probably do a waitUntilVisible() or waitUntilPresent() here
})
.catch((err) => {
  console.log("Form not found:", err)
})
var selector = "#contact-form"
var inputs = {
  "subject": "I am watching you",
  "content": "So be careful.",
  "civility": "Mr",
  "name": "Chuck Norris",
  "email": "chuck@norris.com",
  "cc": true,
  "attachment": "roundhousekick.doc" // file taken from your agent's disk
}

tab.waitUntilVisible(selector, 5000, function(err) {
  if (err) {
    console.log("Form not found:", err)
  } else {
    tab.fill(selector, inputs, { submit: true }, function(err) {
      if (err) {
        console.log("Could not fill the form:", err)
      } else {
      	console.log("Form sent!")
        // Continue your navigation in this branch
        // You should probably do a waitUntilVisible() or waitUntilPresent() here
      }
    })
  }
})
<form action="/contact" id="contact-form" enctype="multipart/form-data">
  <input type="text" name="subject"/>
  <textearea name="content"></textearea>
  <input type="radio" name="civility" value="Mr"/> Mr
  <input type="radio" name="civility" value="Mrs"/> Mrs
  <input type="text" name="name"/>
  <input type="email" name="email"/>
  <input type="file" name="attachment"/>
  <input type="checkbox" name="cc"/> Receive a copy
  <input type="submit"/>
</form>

sendKeys()

sendKeys(selector, keys[, options, callback])

 

Writes keys in an <input>, <textarea> or any DOM element with contenteditable="true" in the current page.

— selector (String)

A CSS3 or XPath expression that describes the path to DOM elements.

— keys (String)

Keys to send to the editable DOM element.

— options (String)

The three options available are:

  • reset (Boolean): remove the content of the targeted element before sending key presses.
  • keepFocus (Boolean): keep the focus in the editable DOM element after keys have been sent (useful for input with dropdowns).
  • modifiers (PlainObject): modifier string concatenated with a + (available modifiers are ctrl, alt, shift, meta and keypad).

— callback (Function(err))

Function called when finished(optional).

  • err (String): null or a description of what went wrong if something went wrong
const selector = '#message'
const keys = "Boo!"
const options = {
  reset: true,
  keepFocus: false,
  modifiers: {}
}

try {
  await tab.sendKeys(selector, keys, options)
  console.log("Keys sent!")
  // You may continue your actions here
} catch (err) {
  console.log("Could not send keys:", err)
}
const selector = '#message'
const keys = "Boo!"
const options = {
  reset: true,
  keepFocus: false,
  modifiers: {}
}

tab.sendKeys(selector, keys, options)
.then(() => {
  console.log("Keys sent!")
  // You may continue your actions here
})
.catch((err) => {
  console.log("Could not send keys:", err)
})
var selector = '#message'
var keys = "Boo!"
var options = {
  reset: true,
  keepFocus: false,
  modifiers: {}
}

tab.sendKeys(selector, keys, options, function(err) {
  if (err) {
    console.log("Could not send keys:", err)
  }
  console.log("Keys sent!")
  // You may continue your actions here
})

getUrl()

getUrl([callback])

 

Returns the current page URL as a string.

— callback (Function(err))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong
  • url (String): the full URL of the current page.
try {
  const url = await tab.getUrl()
  console.log("The url of the page is", url)
  // You can use the variable url and continue your actions
} catch (err) {
  console.log("Could not get the current url:", err)
}
tab.getUrl()
.then((url) => {
  console.log("The url of the page is", url)
  // You can use the variable url and continue your actions
})
.catch((err) => {
  console.log("Could not get the current url:", err)
})
tab.getUrl(function (err, url) {
  if (err) {
    console.log("Could not get the current url:", err)
  }
  else {
    console.log("The url of the page is", url)
    // You can use the variable url and continue your actions
  }
})

Note

The URL you get will be URL-decoded.

getContent()

getContent([callback])

 

Returns the current page content as a string.

— callback (Function(err))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong
  • content (String): the full HTML content of the current webpage.

Note

When the current page is a dynamic JavaScript powered HTML page, getContent() will return a snapshot of the current state of the DOM and not the initial source code.

try {
  const content = await tab.getContent()
  // content contains the content of the current webpage
} catch (err) {
  console.log("Could not get the content of the page:", err)
}
tab.getContent()
.then((content) => {
  // content contains the content of the current webpage
})
.catch((err) => {
  console.log("Could not get the content of the page:", err)
})
tab.getContent(function (err, content) {
  if (err) {
    console.log("Could not get the content of the page:", err)
  }
  else {
    // content contains the content of the current webpage
  }
})

evaluate()

evaluate(inPageFunction [, argumentObject, callback])

 

Executes inPageFunction in the current page context.

Nick provides you with two separate JavaScript contexts:

  1. Where the Nick code runs: this is your script environment, with all your locally declared variables and all your calls to Nick methods
  2. Where the page code runs: this is where the page executes jQuery or AngularJS code for example

The evaluate() method allows you to declare a function in your Nick context (1) and executes it in the page context (2). It's like executing code in your browser's inspector tool: you can do anything you want with the page.

In the page context, you have access to all the global variables declared by the page, as well as the DOM (window, document, ...). Any JavaScript libraries included by the page can also be used.

If the page does not include what you want (jQuery or underscore for example), you can inject any JavaScript file with inject() before calling evaluate().

— inPageFunction (Function(argumentObject, callback))

Function to execute in the current page context. argumentObject will be passed as its first argument and a callback as it second argument.
argumentObject is an empty plainObject by default.
callback is the function to call when finished.

  • err (String): null if the function succeeds otherwise put a description of what went wrong
  • res (Any): return value of inPageFunction in case of success (this value is serialized to be transferred back to the Nick context — complex object like DOM elements, functions or jQuery objects cannot be returned to the Nick context reliably)

— [argumentObject] (PlainObject)

Optional object that will be passed as an argument of inPageFunction (optional).
This object is serialized to be transferred to the page context — complex objects like functions or JavaScript modules cannot be passed as argument reliably.

— callback (Function(err, res)

Function called when finished.

  • err (String): null or a string describing what went wrong during the evaluation of inPageFunction
  • res (Any): return value of inPageFunction in case of success (this value is serialized to be transferred back to the Nick context — complex object like DOM elements, functions or jQuery objects cannot be returned to the Nick context reliably)
const scraper = (arg, done) => {
  // In this case, the current page uses a typical jQuery declared as $
  done(null, $(arg.link).attr("href"))
}
const arg = { link: "#header > a.title" }

try {
  const res = await tab.evaluate(scraper, arg)
  console.log("Scraped this link:", res)
  // Continue your navigation here
} catch (err) {
  console.log("Something went wrong:", err)
}
const scraper = (arg, done) => {
  // In this case, the current page uses a typical jQuery declared as $
  done(null, $(arg.link).attr("href"))
}
const arg = { link: "#header > a.title" }

tab.evaluate(scraper, arg)
.then((res) => {
  console.log("Scraped this link:", res)
  // Continue your navigation here
})
.catch((err) => {
  console.log("Something went wrong:", err)
})
var scraper = function(arg, done) {
  // In this case, the current page uses a typical jQuery declared as $
  done(null, $(arg.link).attr("href"))
}
var arg = { link: "#header > a.title" }

tab.evaluate(scraper, arg, function(err, res) {
  if (err) {
    console.log("Something went wrong:", err)
  } else {
    console.log("Scraped this link:", res)
    // Continue your navigation here
  }
})

Local variables not accessible

Because inPageFunction is executed in the current page context, your local variables that have been declared before your evaluate() call will not be accessible. You can, however, transfer variables using the argumentObject parameter.

For this reason, Nick methods won't be available inside evaluate.

Error in callback

When returning data with the callback in the inPageFunction take care to always set the first argument as null if there is no error.

Serialization subtleties

Keep in mind that to transfer inPageFunction and its return value to and from the page context, serialization has to occur. Everything becomes a string at some point. So you cannot return DOM elements or jQuery objects from the page. Moreover, the underlying PhantomJS browser has a bug where serialization of null gives an empty string "" (even in nested objects and arrays). Beware!

close()

close([callback])

 

Closes the tab in current use.

After close() is called, the tab becomes unusable.
All subsequent method calls will throw an exception saying that this specific tab instance has stopped. Lose all references to the instance for it to be garbage-collected.

— callback (Function)

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong
try {
  await tab.close()
  // tab can not be used here anymore 
  // but you may continue other actions
} catch (err) {
  console.log("Could not close tab:", err)
}
tab.close()
.then(() => {
  // tab can not be used here anymore 
  // but you may continue other actions with buster for example
})
.catch((err) => {
  console.log("Could not close tab:", err)
})
tab.close(function(err){
  if (err) {
    console.log("Could not close tab:", err)
  } else {
    // tab can not be used here anymore 
    // but you may continue other actions with buster for example
  }
})

It's like closing a tab in your browser

This method is useful when using multiple Nick instances to simulate browsing on multiple tabs. Calling close() is the equivalent of closing a tab.

onConfirm

 

Sets an event to a JS confirm alert.
Executes the function assigned to this variable whenever a confirm dialog is called by window.confirm.
The only parameter is the message sent by the dialog, and the function needs to return the user's response as a boolean.

— message (String)

A string containing the message from the confirm dialog.

tab.onConfirm = (message) => {
  console.log("The confirm messsage is", message)
  return true
}
tab.onConfirm = function(message) {
  console.log("The confirm alert message is", message)
  return true
}

onPrompt

 

Sets an event to a JS prompt alert.
Executes the function assigned to this variable whenever a prompt dialog is called by window.prompt().
The only parameter is the message sent by the dialog, and the function needs to return the user's response as a string.

— message (String)

A string containing the message from the prompt dialog.

tab.onPrompt = (message) => {
  console.log("The prompt message is", message)
  return "Response"
}
tab.onPrompt = function(message) {
  console.log("The prompt message is", message)
  return("Response")
}

isVisible()

isVisible(selectors[, conditions, callback])

 

Checks for a list of selectors CSS selectors if they are visible in the page and return a boolean: true if the selectors are visible and false in the contrary.

— selectors (Array or String)

What to check for. Can be an array of CSS selectors (array of strings) or a single CSS selector (string).

— [condition] (String)

When selectors is an array, this optional argument lets you choose how to wait for the CSS selectors (optional).
If condition is "and" (the default), the method will check for the visibility of all CSS selectors.
On the other hand, if condition is "or", the method will check for the visibility of any CSS selector.

— callback (Function(err, selector))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if the function fails to check
  • visible (Boolean): true if the condition succeeds or false in the contrary
const selectors = ["div.first", "div.second"]

const visible = await tab.isVisible(selectors, "or")
if (visible) {
  // Either .first or .second is visible at this time
} else {
  console.log("Elements aren't visible")
}
const selectors = ["div.first", "div.second"]

tab.isVisible(selectors, "or")
.then((visible) => {
  if (visible) {
    // Either .first or .second is visible at this time
  } else {
    console.log("Elements aren't visible")
  }
})
var selectors = ["div.first", "div.second"]

tab.isVisible(selectors, "or", (err, visible) => {
  if (visible) {
    // Either .first or .second is visible at this time
  } else {
    console.log("Elements aren't visible")
  }
})

isPresent()

isPresent(selectors[, conditions, callback])

 

Checks for a list of selectors CSS selectors if they are present in the DOM and return a boolean: true if the selectors are present and false in the contrary.

— selectors (Array or String)

What to look for in the DOM. Can be an array of CSS selectors (array of strings) or a single CSS selector (string).

— [condition] (String)

When selectors is an array, this optional argument lets you choose how to wait for the CSS selectors(optional).
If condition is "and" (the default), the method will check for the presence of all CSS selectors.
On the other hand, if condition is "or", the method will check for the presence of any CSS selector.

— callback (Function(err, selector))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if the function fails to check
  • visible (Boolean): true if the condition succeeds or false in the contrary
const selectors = ["div.first", "div.second"]

const present = await tab.isPresent(selectors, "or")
if (present) {
  // Either .first or .second is present at this time
} else {
  console.log("Elements aren't present")
}
const selectors = ["div.first", "div.second"]

tab.isPresent(selectors, "or")
.then((present) => {
  if (present) {
    // Either .first or .second is present at this time
  } else {
    console.log("Elements aren't present")
  }
})
var selectors = ["div.first", "div.second"]

tab.isPresent(selectors, "or", (err, present) => {
  if (present) {
    // Either .first or .second is present at this time
  } else {
    console.log("Elements aren't present")
  }
})

scroll()

scroll(x, y,[, callback])

 

Scrolls to coordinates [x, y] on the page.

— x (Number)

The X-axis coordinate in pixels to scroll to (horizontally).

— y (Number)

The Y-axis coordinate in pixels to scroll to (vertically).

— callback (Function(err))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong
const x = 1000
const y = 2000

try {
  await tab.scroll(x, y)
  // Your position will be [1000, 2000] in the page now
} catch (err) {
  console.log("Could not scroll to coordinates:", err)
}
const x = 1000
const y = 2000

tab.scroll(x, y)
.then(() => {
  // Your position will be [1000, 2000] in the page now
})
.catch(err => {
  console.log("Could not scroll to coordinates:", err)
})
var x = 1000
var y = 2000

tab.scroll(x, y, function() {
  if (err) {
    console.log("Could not scroll to coordinates:", err)
  } else {
    // Your position will be [1000, 2000] in the page now
  }
})

Tips

scroll() can also be called using scrollTo()

scrollToBottom()

scrollToBottom([callback])

 

Scrolls to the bottom of the page.

— callback (Function(err))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong
try {
  await tab.scrollToBottom()
  // You are now at the bottom of the page
} catch (err) {
  console.log("An error occured during the scroll to bottom:", err)
}
tab.scrollToBottom()
.then(() => {
  // You are now at the bottom of the page
})
.catch(err => {
  console.log("An error occured during the scroll to bottom:", err)
})
tab.scrollToBottom(function(err) {
  if (err) {
    console.log("An error occured during the scroll to bottom:", err)
  } else {
    // You are now at the bottom of the page
  }
})

wait()

wait(duration[, callback])

 

Wait for duration milliseconds.

Info

This function has nothing to do with the tab you are using, it is pure syntactic sugar to replace Promise.delay() (from Bluebird).
It is like waiting in front of your computer after opening a web page.

— duration (Number)

The number of milliseconds to wait for.

— callback (Function(err))

Function called when finished (optional).

  • err (String): null or a description of what went wrong if something went wrong
try {
  await tab.doSomething()
  await tab.wait(10000)
  // After waiting 10 seconds the script continues
  await tab.doSomething()
} catch (err) {
  console.log("An error occured during the execution:", err)
}
tab.doSomething()
.then(() => {
  return tab.wait(10000)
})
.then(() => {
  // After waiting 10 seconds the script continues
  tab.doSomething()
})
.catch((err) => {
  console.log("An error occured during the execution:", err)
})
tab.doSomething(function(err) {
  if (err) {
    console.log(err)
  } else {
    tab.wait(10000, function(err) {
      if (err) {
        console.log("An error occured during the wait:", err)
      } else {
        // After waiting 10 seconds the script continues
        tab.doSomthing()
      }
    })
  }
})