/function API

A quick way to run commands with Browserless is via our /function API. You can use Python, NodeJS or any other language that supports making HTTP requests, so you don't need to install any libraries on your end.

The /function endpoint allows for POSTing of custom code and context to run them with. The code function, which only supports puppeteer code, gets called with an object containing several properties: a page property, which is a puppeteer page object, and context which is the context you provide in the JSON body.

Functions should return an object with two properties: data and type. data can be whatever you'd like (Buffer, JSON, or plain text) and type is a string describing the Content-Type of data. Browserless reads both of these from your functions return value and resolves the request appropriately.

You can view the complete Function API OpenAPI specification.

Basic Usage

Both the /function and the /download API environments use Ecmascript modules. You can use any code and native APIs available in the Chrome browser environment.

JS Code

export default async function ({ page }) {
  const rndNumber = () => {
    return Math.floor(Math.random() * (10**6 - 0));
  };

  await page.goto("https://example.com/");
  const url = await page.title();
  const numbers = [...Array(5)].map(() => rndNumber());

  return {
    data: {
      url,
      numbers,
    },
    // Make sure to match the appropriate content here
    type: "application/json",
  };
}

cURL

curl -X POST \
  https://production-sfo.browserless.io/function?token=YOUR_API_TOKEN_HERE \
  -H 'Content-Type: application/javascript' \
  -d 'export default async function ({ page }) {
  const rndNumber = () => {
    return Math.floor(Math.random() * (10**6 - 0));
  };

  await page.goto("https://example.com/");
  const url = await page.title();
  const numbers = [...Array(5)].map(() => rndNumber());

  return {
    data: {
      url,
      numbers,
    },
    // Make sure to match the appropriate content here
    type: "application/json",
  };
}'

Javascript

const TOKEN = "YOUR_API_TOKEN_HERE";
const url = `https://production-sfo.browserless.io/function?token=${TOKEN}`;
const headers = {
  "Content-Type": "application/javascript"
};

const data = `
export default async function ({ page }) {
  const rndNumber = () => {
    return Math.floor(Math.random() * (10**6 - 0));
  };

  await page.goto("https://example.com/");
  const url = await page.title();
  const numbers = [...Array(5)].map(() => rndNumber());

  return {
    data: {
      url,
      numbers,
    },
    type: "application/json",
  };
}`;

const sendRequest = async () => {
  const response = await fetch(url, {
    method: 'POST',
    headers: headers,
    body: data
  });

  const result = await response.json();
  console.log(result);
};

sendRequest();

Python

import requests

TOKEN = "YOUR_API_TOKEN_HERE"
url = f"https://production-sfo.browserless.io/function?token={TOKEN}"
headers = {
    "Content-Type": "application/javascript"
}

data = """
export default async function ({ page }) {
  const rndNumber = () => {
    return Math.floor(Math.random() * (10**6 - 0));
  };

  await page.goto("https://example.com/");
  const url = await page.title();
  const numbers = [...Array(5)].map(() => rndNumber());

  return {
    data: {
      url,
      numbers,
    },
    type: "application/json",
  };
}
"""

response = requests.post(url, headers=headers, data=data)

result = response.json()
print(result)

Java

import java.net.URI;
import java.net.http.*;
import org.json.JSONObject;

public class BrowserlessFunction {
    public static void main(String[] args) {
        String TOKEN = "YOUR_API_TOKEN_HERE";
        String url = "https://production-sfo.browserless.io/function?token=" + TOKEN;

        String javascriptCode = """
        export default async function ({ page }) {
            const rndNumber = () => {
                return Math.floor(Math.random() * (10**6 - 0));
            };

            await page.goto("https://example.com/");
            const url = await page.title();
            const numbers = [...Array(5)].map(() => rndNumber());

            return {
                data: {
                    url,
                    numbers,
                },
                type: "application/json",
            };
        }
        """;

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Content-Type", "application/javascript")
            .POST(HttpRequest.BodyPublishers.ofString(javascriptCode))
            .build();

        try {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            JSONObject jsonResponse = new JSONObject(response.body());
            System.out.println(jsonResponse.toString(4));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

C#

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program {
    static async Task Main(string[] args) {
        string TOKEN = "YOUR_API_TOKEN_HERE";
        string url = $"https://production-sfo.browserless.io/function?token={TOKEN}";

        string javascriptCode = @"
        export default async function ({ page }) {
            const rndNumber = () => {
                return Math.floor(Math.random() * (10**6 - 0));
            };

            await page.goto('https://example.com/');
            const url = await page.title();
            const numbers = [...Array(5)].map(() => rndNumber());

            return {
                data: {
                    url,
                    numbers,
                },
                type: 'application/json',
            };
        }
        ";

        using var client = new HttpClient();
        var content = new StringContent(javascriptCode, Encoding.UTF8, "application/javascript");

        try {
            var response = await client.PostAsync(url, content);
            response.EnsureSuccessStatusCode();

            var result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        } catch (Exception ex) {
            Console.WriteLine("Error: " + ex.Message);
        }
    }
}

Example Reponse

{
  "data": {
    "url": "Example Domain",
    "numbers": [
      854246,
      114512,
      212580,
      482122,
      107878
    ]
  },
  "type": "application/json"
}

Importing libraries

Since the /function API uses ESM modules, you can use import syntax over HTTP to load moules. For instance, let's try leading the Fake module.

JS Code

import { faker } from "https://esm.sh/@faker-js/faker";

export default async function () {
  const Internet = faker.internet;
  const rndData = [...Array(5)].map(() => ({
    domain: Internet.domainName(),
    ip: Internet.ip(),
    mac: Internet.mac(),
    protocol: Internet.protocol(),
  }));

  return {
    data: { domains: rndData },
    type: "application/json",
  };
}

cURL

curl -X POST \
https://production-sfo.browserless.io/function?token=YOUR_API_TOKEN_HERE \
-H 'Content-Type: application/javascript' \
-d 'import { faker } from "https://esm.sh/@faker-js/faker";

export default async function () {
const Internet = faker.internet;
const rndData = [...Array(5)].map(() => ({
  domain: Internet.domainName(),
  ip: Internet.ip(),
  mac: Internet.mac(),
  protocol: Internet.protocol(),
}));

return {
  data: { domains: rndData },
  type: "application/json",
};
}'

Javascript

const TOKEN = "YOUR_API_TOKEN_HERE";
const url = `https://production-sfo.browserless.io/function?token=${TOKEN}`;
const headers = {
  "Content-Type": "application/javascript"
};

const data = `
import { faker } from "https://esm.sh/@faker-js/faker";

export default async function () {
  const Internet = faker.internet;
  const rndData = [...Array(5)].map(() => ({
    domain: Internet.domainName(),
    ip: Internet.ip(),
    mac: Internet.mac(),
    protocol: Internet.protocol(),
  }));

  return {
    data: { domains: rndData },
    type: "application/json",
  };
}`;

const sendRequest = async () => {
  const response = await fetch(url, {
    method: 'POST',
    headers: headers,
    body: data
  });

  const result = await response.json();
  console.log(result);
};

sendRequest();

Python

import requests

TOKEN = "YOUR_API_TOKEN_HERE"
url = f"https://production-sfo.browserless.io/function?token={TOKEN}"
headers = {
    "Content-Type": "application/javascript"
}

data = """
import { faker } from "https://esm.sh/@faker-js/faker";

export default async function () {
  const Internet = faker.internet;
  const rndData = [...Array(5)].map(() => ({
    domain: Internet.domainName(),
    ip: Internet.ip(),
    mac: Internet.mac(),
    protocol: Internet.protocol(),
  }));

  return {
    data: { domains: rndData },
    type: "application/json",
  };
}
"""

response = requests.post(url, headers=headers, data=data)
result = response.json()
print(result)

Java

import java.net.URI;
import java.net.http.*;
import org.json.JSONObject;

public class BrowserlessFakerFunction {
    public static void main(String[] args) {
        String TOKEN = "YOUR_API_TOKEN_HERE";
        String url = "https://production-sfo.browserless.io/function?token=" + TOKEN;

        String javascriptCode = """
        import { faker } from "https://esm.sh/@faker-js/faker";

        export default async function () {
            const Internet = faker.internet;
            const rndData = [...Array(5)].map(() => ({
                domain: Internet.domainName(),
                ip: Internet.ip(),
                mac: Internet.mac(),
                protocol: Internet.protocol(),
            }));

            return {
                data: { domains: rndData },
                type: "application/json",
            };
        }
        """;

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Content-Type", "application/javascript")
            .POST(HttpRequest.BodyPublishers.ofString(javascriptCode))
            .build();

        try {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            JSONObject jsonResponse = new JSONObject(response.body());
            System.out.println(jsonResponse.toString(4));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

C#

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program {
    static async Task Main(string[] args) {
        string TOKEN = "YOUR_API_TOKEN_HERE";
        string url = $"https://production-sfo.browserless.io/function?token={TOKEN}";

        string javascriptCode = @"
        import { faker } from 'https://esm.sh/@faker-js/faker';

        export default async function () {
            const Internet = faker.internet;
            const rndData = [...Array(5)].map(() => ({
                domain: Internet.domainName(),
                ip: Internet.ip(),
                mac: Internet.mac(),
                protocol: Internet.protocol(),
            }));

            return {
                data: { domains: rndData },
                type: 'application/json',
            };
        }
        ";

        using var client = new HttpClient();
        var content = new StringContent(javascriptCode, Encoding.UTF8, "application/javascript");

        try {
            var response = await client.PostAsync(url, content);
            response.EnsureSuccessStatusCode();

            var result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        } catch (Exception ex) {
            Console.WriteLine("Error: " + ex.Message);
        }
    }
}

JSON API

You can also use the /function API sending a JSON payload. You must send an object with the following values:

• code: String, required — custom function code.
• context: Object, optional — value used to pass context values and arguments to the code

Example

JS Code

import { faker } from "https://esm.sh/@faker-js/faker";

export default async function ({ context }) {
  const Internet = faker.internet;
  const rndData = [...Array(context.len)].map(() => ({
    domain: Internet.domainName(),
    ip: Internet.ip(),
    mac: Internet.mac(),
    protocol: Internet.protocol(),
  }));

  return {
    data: {
      domains: rndData,
      length: context.len
    },
    type: "application/json",
  };
}

cURL

curl --request POST \
  --url 'https://production-sfo.browserless.io/function?token=YOUR_API_TOKEN_HERE' \
  --header 'Content-Type: application/json' \
  # Minified code
  --data '{
  "code": "import{faker as a}from\"https://esm.sh/@faker-js/faker\";export default async function({context:o}){let t=a.internet,e=[...Array(o.len)].map(()=>({domain:t.domainName(),ip:t.ip(),mac:t.mac(),protocol:t.protocol()}));return{data:{domains:e,length:o.len},type:`application/json`}};",
  "context": {
    "len": 10
  }
}'

Javascript

import fetch from 'node-fetch';

const TOKEN = "YOUR_API_TOKEN_HERE";
const url = `https://production-sfo.browserless.io/function?token=${TOKEN}`;
const headers = {
  "Content-Type": "application/json"
};

const data = {
  code: 'import{faker as a}from"https://esm.sh/@faker-js/faker";export default async function({context:o}){let t=a.internet,e=[...Array(o.len)].map(()=>({domain:t.domainName(),ip:t.ip(),mac:t.mac(),protocol:t.protocol()}));return{data:{domains:e,length:o.len},type:`application/json`}};',
  context: { len: 10 }
};

const sendRequest = async () => {
  const response = await fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
  });

  const result = await response.json();
  console.log(result);
};

sendRequest();

Python

import requests

TOKEN = "YOUR_API_TOKEN_HERE"
url = f"https://production-sfo.browserless.io/function?token={TOKEN}"
headers = {
    "Content-Type": "application/json"
}

data = {
    "code": 'import{faker as a}from"https://esm.sh/@faker-js/faker";export default async function({context:o}){let t=a.internet,e=[...Array(o.len)].map(()=>({domain:t.domainName(),ip:t.ip(),mac:t.mac(),protocol:t.protocol()}));return{data:{domains:e,length:o.len},type:`application/json`}};',
    "context": {
        "len": 10
    }
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)

Java

import java.net.URI;
import java.net.http.*;
import org.json.JSONObject;

public class BrowserlessFakerMinified {
    public static void main(String[] args) {
        String TOKEN = "YOUR_API_TOKEN_HERE";
        String url = "https://production-sfo.browserless.io/function?token=" + TOKEN;

        String jsonData = """
        {
            "code": "import{faker as a}from\\\"https://esm.sh/@faker-js/faker\\\";export default async function({context:o}){let t=a.internet,e=[...Array(o.len)].map(()=>({domain:t.domainName(),ip:t.ip(),mac:t.mac(),protocol:t.protocol()}));return{data:{domains:e,length:o.len},type:`application/json`}};",
            "context": {
                "len": 10
            }
        }
        """;

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonData))
            .build();

        try {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            JSONObject jsonResponse = new JSONObject(response.body());
            System.out.println(jsonResponse.toString(4));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

C#

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program {
    static async Task Main(string[] args) {
        string TOKEN = "YOUR_API_TOKEN_HERE";
        string url = $"https://production-sfo.browserless.io/function?token={TOKEN}";

        string jsonData = @"
        {
            ""code"": ""import{faker as a}from\""https://esm.sh/@faker-js/faker\"";export default async function({context:o}){let t=a.internet,e=[...Array(o.len)].map(()=>({domain:t.domainName(),ip:t.ip(),mac:t.mac(),protocol:t.protocol()}));return{data:{domains:e,length:o.len},type:`application/json`}};"",
            ""context"": {
                ""len"": 10
            }
        }
        ";

        using var client = new HttpClient();
        var content = new StringContent(jsonData, Encoding.UTF8, "application/json");

        try {
            var response = await client.PostAsync(url, content);
            response.EnsureSuccessStatusCode();

            var result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        } catch (Exception ex) {
            Console.WriteLine("Error: " + ex.Message);
        }
    }
}

Exception handling

When working with the /function API, you can catch exceptions and handle errors gracefully. This is particularly useful for debugging and providing meaningful error responses when automation fails.

The following example shows how to implement comprehensive error handling, including capturing screenshots when errors occur:

JS Code

export default async ({ page }) => {
  let error;
  let title;

  try {
    await page.goto('https://www.example.com');
    title = await page.title();
    await page.click('.nonexistent-button'); // This will throw
  } catch (err) {
    const errorDetails = {
      message: err.message,
      stack: err.stack,
      name: err.name,
    };

    try {
      const screenshot = await page.screenshot({ encoding: 'base64' });
      errorDetails.screenshot = screenshot;
    } catch (screenshotErr) {
      errorDetails.screenshotError = {
        message: screenshotErr.message,
        stack: screenshotErr.stack,
        name: screenshotErr.name,
      };
    }
    error = errorDetails;
  }
  return {
    data: {
      title,
      error,
    },
  };
};

cURL

curl -X POST \
  https://production-sfo.browserless.io/function?token=YOUR_API_TOKEN_HERE \
  -H 'Content-Type: application/javascript' \
  -d 'export default async ({ page }) => {
  let error;
  let title;

  try {
    await page.goto("https://www.example.com");
    title = await page.title();
    await page.click(".nonexistent-button"); // This will throw
  } catch (err) {
    const errorDetails = {
      message: err.message,
      stack: err.stack,
      name: err.name,
    };

    try {
      const screenshot = await page.screenshot({ encoding: "base64" });
      errorDetails.screenshot = screenshot;
    } catch (screenshotErr) {
      errorDetails.screenshotError = {
        message: screenshotErr.message,
        stack: screenshotErr.stack,
        name: screenshotErr.name,
      };
    }
    error = errorDetails;
  }
  return {
    data: {
      title,
      error,
    },
  };
};'

Javascript

const TOKEN = "YOUR_API_TOKEN_HERE";
const url = `https://production-sfo.browserless.io/function?token=${TOKEN}`;
const headers = {
  "Content-Type": "application/javascript"
};

const data = `
export default async ({ page }) => {
  let error;
  let title;

  try {
    await page.goto('https://www.example.com');
    title = await page.title();
    await page.click('.nonexistent-button'); // This will throw
  } catch (err) {
    const errorDetails = {
      message: err.message,
      stack: err.stack,
      name: err.name,
    };

    try {
      const screenshot = await page.screenshot({ encoding: 'base64' });
      errorDetails.screenshot = screenshot;
    } catch (screenshotErr) {
      errorDetails.screenshotError = {
        message: screenshotErr.message,
        stack: screenshotErr.stack,
        name: screenshotErr.name,
      };
    }
    error = errorDetails;
  }
  return {
    data: {
      title,
      error,
    },
  };
};`;

const sendRequest = async () => {
  const response = await fetch(url, {
    method: 'POST',
    headers: headers,
    body: data
  });

  const result = await response.json();
  console.log(result);
};

sendRequest();

Python

import requests

TOKEN = "YOUR_API_TOKEN_HERE"
url = f"https://production-sfo.browserless.io/function?token={TOKEN}"
headers = {
    "Content-Type": "application/javascript"
}

data = """
export default async ({ page }) => {
  let error;
  let title;

  try {
    await page.goto('https://www.example.com');
    title = await page.title();
    await page.click('.nonexistent-button'); // This will throw
  } catch (err) {
    const errorDetails = {
      message: err.message,
      stack: err.stack,
      name: err.name,
    };

    try {
      const screenshot = await page.screenshot({ encoding: 'base64' });
      errorDetails.screenshot = screenshot;
    } catch (screenshotErr) {
      errorDetails.screenshotError = {
        message: screenshotErr.message,
        stack: screenshotErr.stack,
        name: screenshotErr.name,
      };
    }
    error = errorDetails;
  }
  return {
    data: {
      title,
      error,
    },
  };
};
"""

response = requests.post(url, headers=headers, data=data)
result = response.json()
print(result)

Java

import java.net.URI;
import java.net.http.*;
import org.json.JSONObject;

public class BrowserlessExceptionHandling {
    public static void main(String[] args) {
        String TOKEN = "YOUR_API_TOKEN_HERE";
        String url = "https://production-sfo.browserless.io/function?token=" + TOKEN;

        String javascriptCode = """
        export default async ({ page }) => {
          let error;
          let title;

          try {
            await page.goto('https://www.example.com');
            title = await page.title();
            await page.click('.nonexistent-button'); // This will throw
          } catch (err) {
            const errorDetails = {
              message: err.message,
              stack: err.stack,
              name: err.name,
            };

            try {
              const screenshot = await page.screenshot({ encoding: 'base64' });
              errorDetails.screenshot = screenshot;
            } catch (screenshotErr) {
              errorDetails.screenshotError = {
                message: screenshotErr.message,
                stack: screenshotErr.stack,
                name: screenshotErr.name,
              };
            }
            error = errorDetails;
          }
          return {
            data: {
              title,
              error,
            },
          };
        };
        """;

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Content-Type", "application/javascript")
            .POST(HttpRequest.BodyPublishers.ofString(javascriptCode))
            .build();

        try {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            JSONObject jsonResponse = new JSONObject(response.body());
            System.out.println(jsonResponse.toString(4));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

C#

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program {
    static async Task Main(string[] args) {
        string TOKEN = "YOUR_API_TOKEN_HERE";
        string url = $"https://production-sfo.browserless.io/function?token={TOKEN}";

        string javascriptCode = @"
        export default async ({ page }) => {
          let error;
          let title;

          try {
            await page.goto('https://www.example.com');
            title = await page.title();
            await page.click('.nonexistent-button'); // This will throw
          } catch (err) {
            const errorDetails = {
              message: err.message,
              stack: err.stack,
              name: err.name,
            };

            try {
              const screenshot = await page.screenshot({ encoding: 'base64' });
              errorDetails.screenshot = screenshot;
            } catch (screenshotErr) {
              errorDetails.screenshotError = {
                message: screenshotErr.message,
                stack: screenshotErr.stack,
                name: screenshotErr.name,
              };
            }
            error = errorDetails;
          }
          return {
            data: {
              title,
              error,
            },
          };
        };
        ";

        using var client = new HttpClient();
        var content = new StringContent(javascriptCode, Encoding.UTF8, "application/javascript");

        try {
            var response = await client.PostAsync(url, content);
            response.EnsureSuccessStatusCode();

            var result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        } catch (Exception ex) {
            Console.WriteLine("Error: " + ex.Message);
        }
    }
}

Example Response

{
  "data": {
    "title": "Example Domain",
    "error": {
      "message": "No node found for selector: .nonexistent-button",
      "stack": "Error: No node found for selector: .nonexistent-button\n    at ...",
      "name": "Error",
      "screenshot": "iVBORw0KGgoAAAANSUhEUgAAA..."
    }
  }
}

This pattern allows you to:

• Capture detailed error information including the error message, stack trace, and error type
• Take a screenshot when an error occurs for visual debugging
• Handle screenshot capture errors gracefully
• Return both successful data and error information in a structured format