Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to PhantomBuster

Scalekit connector
Open markdown

The PhantomBuster connector lets your AI agent act in each user's PhantomBuster account. Each user connects their own PhantomBuster API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 56 tools.

Tools
56
What they doRead · write · destructive
31 · 19 · 631 read19 write6 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the PhantomBuster connection

    In AgentKit > Connections, create a PhantomBuster connection. The name you give it is the connection_name your code passes. See Configure connections.

    Console steps with screenshots

    Register your PhantomBuster API key with Scalekit so it can authenticate and proxy automation requests on behalf of your users. PhantomBuster uses API key authentication.

    1. Get your PhantomBuster API key

      • Sign in to phantombuster.com and go to Settings → API in the left sidebar.

      • Your API key is displayed on this page. Click the copy icon to copy it. If you need a new key, click Regenerate.

      PhantomBuster Settings API page showing the API key field with copy button

    2. Create a connection in Scalekit

      • In Scalekit dashboard, go to AgentKit > Connections > Create Connection. Find PhantomBuster and click Create.

      • Note the Connection name — you will use this as connection_name in your code (e.g., phantombuster).

      Scalekit connection configuration page for PhantomBuster showing the connection name and API Key authentication type

    3. Add a connected account

      Connected accounts link a specific user identifier in your system to a PhantomBuster API key. Add one in the dashboard to test. In production, each user adds their own through the authorization link: they enter their credentials on the page it opens.

      In the dashboard, to test

      • Open the connection you created and click the Connected Accounts tab → Add account.

      • Fill in:

        • Your User’s ID — a unique identifier for this user in your system (e.g., user_123)
        • API Key — the PhantomBuster API key you copied in step 1

      • Click Save.

      Add connected account form for PhantomBuster in Scalekit dashboard showing User ID and API Key fields

      From your backend, if your app already has the credentials

      For example, when users enter them on a settings page in your app:

      import { ConnectorStatus } from '@scalekit-sdk/node'
      

      const authorizationDetails = {
        details: {
          case: 'staticAuth',
          value: { details: { api_key: 'your-phantombuster-api-key' } },
        },
      };
      

      let { connectedAccount } = await scalekit.actions.upsertConnectedAccount({
        connectionName: 'phantombuster',
        identifier: 'user_123',
        authorizationDetails,
      });
      

      // Make sure the account is ACTIVE before the first tool call.
      if (connectedAccount?.status !== ConnectorStatus.ACTIVE) {
        ({ connectedAccount } = await scalekit.actions.upsertConnectedAccount({
          connectionName: 'phantombuster',
          identifier: 'user_123',
          authorizationDetails,
        }));
      }

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'phantombuster'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize PhantomBuster:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'phantombuster_user_fetch_me',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their PhantomBuster credentials there. If your app already has a user's credentials, add the account from your backend instead, as the console steps above show. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • phantombuster_agent_fetchRetrieve details of a specific PhantomBuster agent by its ID.Read-only

    Get Agent

    Retrieve details of a specific PhantomBuster agent by its ID. Returns agent name, script, schedule, launch type, argument configuration, and current status.

    Inputs

    agentIdstringrequired
    The unique identifier of the agent to retrieve.
  • phantombuster_agent_fetch_outputGet the output of the most recent container of an agent.Read-only

    Get Agent Output

    Get the output of the most recent container of an agent. Designed for incremental data retrieval — use fromOutputPos to fetch only new output since the last call.

    Inputs

    idstringrequired
    ID of the agent to fetch output from.
    fromOutputPosnumber
    Start output from this byte position (for incremental fetching).
    prevContainerIdstring
    Retrieve output from the container after this previous container ID.
    prevRuntimeEventIndexnumber
    Return runtime events starting from this index.
    prevStatusstring
    Previously retrieved status from user-side (for delta detection).
  • phantombuster_agents_fetch_allRetrieve all automation agents in the PhantomBuster organization.Read-only

    List Agents

    Retrieve all automation agents in the PhantomBuster organization. Returns agent IDs, names, associated scripts, schedules, and current status.

    Inputs

    This tool takes no inputs.

  • phantombuster_agents_fetch_deletedRetrieve all deleted agents in the PhantomBuster organization.Read-only

    List Deleted Agents

    Retrieve all deleted agents in the PhantomBuster organization. Returns agent IDs, names, creation timestamps, deletion timestamps, and who deleted each agent.

    Inputs

    This tool takes no inputs.

  • phantombuster_branch_diffGet the length difference between the staging and release branch of all scripts in the current organization.Read-only

    Get Branch Diff

    Get the length difference between the staging and release branch of all scripts in the current organization.

    Inputs

    namestring
    Name of a specific branch to diff. Omit to diff all branches.
  • phantombuster_branches_fetch_allRetrieve all branches associated with the current PhantomBuster organization.Read-only

    List Branches

    Retrieve all branches associated with the current PhantomBuster organization.

    Inputs

    This tool takes no inputs.

  • phantombuster_buyers_personas_fetch_allRetrieve all buyer personas configured for the current PhantomBuster organization, including each persona's linked Ideal Customer Profile, target job titles, countries, pain points, and goals.Read-only

    List Buyer Personas

    Retrieve all buyer personas configured for the current PhantomBuster organization, including each persona's linked Ideal Customer Profile, target job titles, countries, pain points, and goals.

    Inputs

    This tool takes no inputs.

Workflows

Proxy API call
// List all agents via Scalekit proxy — no API key needed here
const result = await actions.request({
  connectionName: 'phantombuster',
  identifier: 'user_123',
  path: '/api/v2/agents',
  method: 'GET',
});
console.log(result.data);
Launch an agent and retrieve results

The most common PhantomBuster workflow: launch an automation agent, stream its console output while it runs, then read the final result.

examples/phantombuster_launch.py
# Step 1: Find the agent you want to run
agents = actions.execute_tool(
    connection_name='phantombuster',
    identifier='user_123',
    tool_name="phantombuster_agents_fetch_all",
    tool_input={}
)
agent_id = agents.data[0]["id"]  # pick the first agent, or filter by name


# Step 2: Launch the agent
launch_result = actions.execute_tool(
    connection_name='phantombuster',
    identifier='user_123',
    tool_name="phantombuster_agent_launch",
    tool_input={
        "id": agent_id,
        "output": "result-object",
    }
)
container_id = launch_result.data["containerId"]
print(f"Agent launched. Container ID: {container_id}")


# Step 3: Poll for output until the agent finishes
output_pos = 0
while True:
    output = actions.execute_tool(
        connection_name='phantombuster',
        identifier='user_123',
        tool_name="phantombuster_container_fetch_output",
        tool_input={"id": container_id, "fromOutputPos": output_pos}
    )
    print(output.data.get("output", ""), end="", flush=True)
    output_pos = output.data.get("nextOutputPos", output_pos)
    if output.data.get("status") in ("finished", "error"):
        break
    time.sleep(3)  # poll every 3 seconds


# Step 4: Fetch the structured result
final_result = actions.execute_tool(
    connection_name='phantombuster',
    identifier='user_123',
    tool_name="phantombuster_container_fetch_result",
    tool_input={"id": container_id}
)
print("Scraped profiles:", final_result.data)
Save scraped profiles as leads

After a scraping run, bulk-save extracted profiles to a PhantomBuster lead list for downstream CRM enrichment or outreach.

examples/phantombuster_save_leads.py
# First: fetch available lead lists (or create one in the PhantomBuster dashboard)
lists = actions.execute_tool(
    connection_name='phantombuster',
    identifier='user_123',
    tool_name="phantombuster_lists_fetch_all",
    tool_input={}
)
list_id = lists.data[0]["id"]  # use the first list, or filter by name


# Bulk-save up to 1,000 profiles in one call — more efficient than looping
actions.execute_tool(
    connection_name='phantombuster',
    identifier='user_123',
    tool_name="phantombuster_leads_save_many",
    tool_input={
        "listId": list_id,
        "leads": [
            {
                "firstName": p.get("firstName"),
                "lastName": p.get("lastName"),
                "email": p.get("email"),
                "linkedinUrl": p.get("linkedinUrl"),
                "company": p.get("company"),
                "jobTitle": p.get("title"),
                "additionalFields": {
                    "source": "phantombuster-scraper",
                    "agentId": agent_id,
                    "containerId": container_id,
                },
            }
            for p in final_result.data
        ],
    }
)
print(f"{len(final_result.data)} leads saved to list {list_id}.")
Check resource usage before running agents

Avoid quota errors by verifying execution time and credit balances before launching a large scraping run.

examples/phantombuster_check_resources.py
resources = actions.execute_tool(
    connection_name='phantombuster',
    identifier='user_123',
    tool_name="phantombuster_org_fetch_resources",
    tool_input={}
)


exec_time = resources.data.get("executionTime", {})
ai_credits = resources.data.get("aiCredits", {})


if exec_time.get("remaining", 0) < 30:
    raise RuntimeError(
        f"Insufficient execution time: {exec_time.get('remaining')} min remaining. "
        "Upgrade at phantombuster.com/pricing or wait for your plan to reset."
    )


print(f"Execution time: {exec_time['remaining']} min remaining ({exec_time.get('used')} used)")
print(f"AI credits: {ai_credits.get('remaining', 'N/A')}")
Run AI completions on scraped data

Use PhantomBuster’s AI service to extract structured data from raw agent output — such as parsing job titles into seniority levels or extracting skills from profile summaries.

examples/phantombuster_ai_enrichment.py
# Extract structured data from a raw LinkedIn profile headline
completion = actions.execute_tool(
    connection_name='phantombuster',
    identifier='user_123',
    tool_name="phantombuster_ai_completions",
    tool_input={
        "model": "gpt-4o",
        "messages": [
            {
                "role": "system",
                "content": "Extract the seniority level and primary skill from this LinkedIn headline. Return JSON only.",
            },
            {
                "role": "user",
                "content": "Senior Software Engineer at Acme Corp | React, TypeScript, GraphQL",
            },
        ],
        "responseSchema": {
            "type": "object",
            "properties": {
                "seniority": {"type": "string", "enum": ["junior", "mid", "senior", "lead", "exec"]},
                "primarySkill": {"type": "string"},
            },
            "required": ["seniority", "primarySkill"],
        },
    }
)
print("Parsed profile:", completion.data)
# → {'seniority': 'senior', 'primarySkill': 'React'}
LangChain integration

Let an LLM decide which PhantomBuster tool to call based on natural language. This example builds an agent that can manage automation runs and leads in response to user input.

examples/phantombuster_langchain.py
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_core.prompts import (
    ChatPromptTemplate, SystemMessagePromptTemplate,
    HumanMessagePromptTemplate, MessagesPlaceholder, PromptTemplate
)


# Load all PhantomBuster tools in LangChain format. Use page_size=100 so connector tool lists are not truncated.
tools = actions.langchain.get_tools(
    identifier='user_123',
    providers=["PHANTOMBUSTER"],
    page_size=100
)


prompt = ChatPromptTemplate.from_messages([
    SystemMessagePromptTemplate(prompt=PromptTemplate(
        input_variables=[],
        template=(
            "You are a PhantomBuster automation assistant. "
            "Use the available tools to manage agents, check resource usage, "
            "manage leads, and analyse automation run results."
        )
    )),
    MessagesPlaceholder(variable_name="chat_history", optional=True),
    HumanMessagePromptTemplate(prompt=PromptTemplate(
        input_variables=["input"], template="{input}"
    )),
    MessagesPlaceholder(variable_name="agent_scratchpad")
])


llm = ChatOpenAI(model="gpt-4o")
agent = create_openai_tools_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)


result = agent_executor.invoke({
    "input": "List all my agents, show which ones ran in the last 24 hours, and tell me how many leads are in each list"
})
print(result["output"])

Related: other AI connectors

All 134 in AI