Can I use Phantombuster as a CLI?

Yes. KosmoKrator exposes a Phantombuster CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Phantombuster through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Phantombuster tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Phantombuster credentials stored?

Phantombuster credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Phantombuster MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

data

Phantombuster Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Phantombuster KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.phantombuster.*. Use lua_read_doc("integrations.phantombuster") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Phantombuster workflow without starting an interactive agent session.

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.phantombuster.list_agents({input_types = "example_input_types", output_types = "example_output_types", agent_ids = "example_agent_ids", with_argument = true, with_agent_slots_factor = true}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("phantombuster"))' --json
kosmo integrations:lua --eval 'print(docs.read("phantombuster.list_agents"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua

local phantombuster = app.integrations.phantombuster
local result = phantombuster.list_agents({input_types = "example_input_types", output_types = "example_output_types", agent_ids = "example_agent_ids", with_argument = true, with_agent_slots_factor = true})

dump(result)

Run the workflow

kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json

Namespace note. integrations:lua exposes app.integrations.phantombuster, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.phantombuster.default.* or app.integrations.phantombuster.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Phantombuster, use the narrower mcp:lua command.

MCP Lua command

# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Phantombuster Lua API Reference

Namespace: app.integrations.phantombuster

Use this integration to manage Phantombuster agents, launches, containers, outputs, scripts, branches, and organization metadata. Returned values are the parsed JSON response from the Phantombuster API. Raw container output is returned as { body = "..." } when the API responds with plain text.

Agents

Function	Purpose
`list_agents({ input_types?, output_types?, agent_ids?, with_argument?, with_agent_slots_factor? })`	List agents in the current organization.
`get_agent({ id, with_manifest?, with_agent_object?, with_code?, with_slaves?, with_sub_slaves? })`	Get one agent by ID.
`launch_agent({ id, argument?, arguments?, bonus_argument?, save_argument?, payload? })`	Launch one agent and return its launch container response.
`save_agent({ id?, name?, script?, branch?, environment?, launch_type?, argument?, payload? })`	Create or update an agent.
`stop_agent({ id })`	Stop a running agent.
`delete_agent({ id })`	Delete an agent.
`list_deleted_agents({})`	List deleted agents.
`fetch_agent_output({ id, from_output_pos?, prev_container_id?, prev_status?, prev_runtime_event_index? })`	Fetch incremental output from the latest relevant container for an agent.

Example:

local agents = app.integrations.phantombuster.list_agents({
  with_argument = true
})

local launch = app.integrations.phantombuster.launch_agent({
  id = agents.agents[1].id,
  bonus_argument = { profileUrl = "https://example.test/profile" }
})

print(launch.containerId or launch.id)

Containers

Function	Purpose
`list_containers({ agent_id, before_ended_at?, limit?, mode?, with_runtime_events? })`	List containers for one agent.
`get_container({ id, with_result_object?, with_output?, with_runtime_events?, with_newer_and_older_container_id? })`	Get a container by ID.
`fetch_container_output({ id, mode? })`	Fetch container output. `mode` can be `json` or `raw`.
`fetch_container_result_object({ id })`	Fetch the result object associated with a container.

list_containers requires an agent ID because Phantombuster’s v2 /containers/fetch-all endpoint is scoped to one agent.

Scripts, Branches, And Organization

Function	Purpose
`list_scripts({})`	List scripts available to the current user.
`get_script({ id })`	Get one script by ID.
`save_script({ payload })`	Create or update a script with the official `/scripts/save` payload.
`delete_script({ id })`	Delete a script.
`list_branches({})`	List script branches for the current organization.
`get_organization({ with_global_object?, with_proxies?, with_crm_integrations?, with_custom_prompts? })`	Fetch current organization metadata.
`get_ip_location({ ip })`	Resolve country metadata for an IP address.

Use payload for large or fast-changing official Phantombuster request bodies. Keep examples and tests on fake values such as example.test.

Generic API Helpers

Function	Purpose
`api_get({ path, params? })`	Send GET to a relative API path.
`api_post({ path, payload? })`	Send POST to a relative API path.
`api_put({ path, payload? })`	Send PUT to a relative API path.
`api_delete({ path, payload? })`	Send DELETE to a relative API path.

Generic helpers reject absolute URLs. Use paths like /agents/fetch-all, /containers/fetch-output, or /orgs/fetch so hosts retain control of the API base URL and credentials.

Current User

get_current_user({}) fetches the authenticated Phantombuster user from /user. Use it to verify which account a configured API key represents.

Multi-Account Usage

All functions work the same way under account-specific namespaces:

app.integrations.phantombuster.list_agents({})
app.integrations.phantombuster.default.list_agents({})
app.integrations.phantombuster.client.list_agents({})

Raw agent markdown

# Phantombuster Lua API Reference

Namespace: `app.integrations.phantombuster`

Use this integration to manage Phantombuster agents, launches, containers,
outputs, scripts, branches, and organization metadata. Returned values are the
parsed JSON response from the Phantombuster API. Raw container output is returned
as `{ body = "..." }` when the API responds with plain text.

## Agents

| Function | Purpose |
|----------|---------|
| `list_agents({ input_types?, output_types?, agent_ids?, with_argument?, with_agent_slots_factor? })` | List agents in the current organization. |
| `get_agent({ id, with_manifest?, with_agent_object?, with_code?, with_slaves?, with_sub_slaves? })` | Get one agent by ID. |
| `launch_agent({ id, argument?, arguments?, bonus_argument?, save_argument?, payload? })` | Launch one agent and return its launch container response. |
| `save_agent({ id?, name?, script?, branch?, environment?, launch_type?, argument?, payload? })` | Create or update an agent. |
| `stop_agent({ id })` | Stop a running agent. |
| `delete_agent({ id })` | Delete an agent. |
| `list_deleted_agents({})` | List deleted agents. |
| `fetch_agent_output({ id, from_output_pos?, prev_container_id?, prev_status?, prev_runtime_event_index? })` | Fetch incremental output from the latest relevant container for an agent. |

Example:

```lua
local agents = app.integrations.phantombuster.list_agents({
  with_argument = true
})

local launch = app.integrations.phantombuster.launch_agent({
  id = agents.agents[1].id,
  bonus_argument = { profileUrl = "https://example.test/profile" }
})

print(launch.containerId or launch.id)
```

## Containers

| Function | Purpose |
|----------|---------|
| `list_containers({ agent_id, before_ended_at?, limit?, mode?, with_runtime_events? })` | List containers for one agent. |
| `get_container({ id, with_result_object?, with_output?, with_runtime_events?, with_newer_and_older_container_id? })` | Get a container by ID. |
| `fetch_container_output({ id, mode? })` | Fetch container output. `mode` can be `json` or `raw`. |
| `fetch_container_result_object({ id })` | Fetch the result object associated with a container. |

`list_containers` requires an agent ID because Phantombuster's v2
`/containers/fetch-all` endpoint is scoped to one agent.

## Scripts, Branches, And Organization

| Function | Purpose |
|----------|---------|
| `list_scripts({})` | List scripts available to the current user. |
| `get_script({ id })` | Get one script by ID. |
| `save_script({ payload })` | Create or update a script with the official `/scripts/save` payload. |
| `delete_script({ id })` | Delete a script. |
| `list_branches({})` | List script branches for the current organization. |
| `get_organization({ with_global_object?, with_proxies?, with_crm_integrations?, with_custom_prompts? })` | Fetch current organization metadata. |
| `get_ip_location({ ip })` | Resolve country metadata for an IP address. |

Use `payload` for large or fast-changing official Phantombuster request bodies.
Keep examples and tests on fake values such as `example.test`.

## Generic API Helpers

| Function | Purpose |
|----------|---------|
| `api_get({ path, params? })` | Send GET to a relative API path. |
| `api_post({ path, payload? })` | Send POST to a relative API path. |
| `api_put({ path, payload? })` | Send PUT to a relative API path. |
| `api_delete({ path, payload? })` | Send DELETE to a relative API path. |

Generic helpers reject absolute URLs. Use paths like `/agents/fetch-all`,
`/containers/fetch-output`, or `/orgs/fetch` so hosts retain control of the API
base URL and credentials.

## Current User

`get_current_user({})` fetches the authenticated Phantombuster user from `/user`.
Use it to verify which account a configured API key represents.

## Multi-Account Usage

All functions work the same way under account-specific namespaces:

```lua
app.integrations.phantombuster.list_agents({})
app.integrations.phantombuster.default.list_agents({})
app.integrations.phantombuster.client.list_agents({})
```

Metadata-derived Lua example

local result = app.integrations.phantombuster.list_agents({input_types = "example_input_types", output_types = "example_output_types", agent_ids = "example_agent_ids", with_argument = true, with_agent_slots_factor = true})
print(result)

Functions

list_agents Read

List all Phantombuster agents in your account. Returns agent IDs, names, and status so you can inspect or launch them.

Lua path: app.integrations.phantombuster.list_agents
Full name: phantombuster.phantombuster_list_agents

Parameter	Type	Required	Description
`input_types`	array	no	Filter by manifest input types.
`output_types`	array	no	Filter by manifest output types.
`agent_ids`	array	no	Limit to up to 100 agent IDs.
`with_argument`	boolean	no	Include default agent arguments.
`with_agent_slots_factor`	boolean	no	Include reserved agent slots factor.

get_agent Read

Get details for a specific Phantombuster agent, including its configuration, last run status, and output.

Lua path: app.integrations.phantombuster.get_agent
Full name: phantombuster.phantombuster_get_agent

Parameter	Type	Required	Description
`id`	string	yes	The agent ID (e.g., "1234567890123456789").
`with_manifest`	boolean	no	Include the agent manifest.
`with_agent_object`	boolean	no	Include the agent object.
`with_code`	boolean	no	Include script code when available.
`with_slaves`	boolean	no	Include slave agents.
`with_sub_slaves`	boolean	no	Include nested slave agents.

launch_agent Write

Launch a Phantombuster agent to start an automation. Returns the container ID for tracking execution progress.

Lua path: app.integrations.phantombuster.launch_agent
Full name: phantombuster.phantombuster_launch_agent

Parameter	Type	Required	Description
`id`	string	yes	The agent ID to launch (e.g., "1234567890123456789").
`argument`	object	no	Temporary launch argument object or string accepted by Phantombuster.
`arguments`	object	no	Alternative launch argument field accepted by Phantombuster.
`bonus_argument`	object	no	Single-use argument merged with the saved argument.
`save_argument`	boolean	no	Save argument as the default launch options.
`payload`	object	no	Additional official launch fields.

save_agent Write

Create or update a Phantombuster agent using official /agents/save fields.

Lua path: app.integrations.phantombuster.save_agent
Full name: phantombuster.phantombuster_save_agent

Parameter	Type	Required	Description
`id`	string	no	Existing agent ID to update. Omit to create.
`name`	string	no	Agent name.
`script`	string	no	Script ID.
`branch`	string	no	Branch ID.
`environment`	string	no	Script environment.
`launch_type`	string	no	Launch mode.
`argument`	object	no	Default launch argument.
`payload`	object	no	Additional official /agents/save fields.

stop_agent Write

Stop a running Phantombuster agent.

Lua path: app.integrations.phantombuster.stop_agent
Full name: phantombuster.phantombuster_stop_agent

Parameter	Type	Required	Description
`id`	string	yes	Agent ID.

delete_agent Write

Delete a Phantombuster agent by ID.

Lua path: app.integrations.phantombuster.delete_agent
Full name: phantombuster.phantombuster_delete_agent

Parameter	Type	Required	Description
`id`	string	yes	Agent ID.

list_deleted_agents Read

List deleted Phantombuster agents in the current organization.

Lua path: app.integrations.phantombuster.list_deleted_agents
Full name: phantombuster.phantombuster_list_deleted_agents

Parameter	Type	Required	Description
No parameters.

fetch_agent_output Read

Fetch output from the latest relevant container of a Phantombuster agent.

Lua path: app.integrations.phantombuster.fetch_agent_output
Full name: phantombuster.phantombuster_fetch_agent_output

Parameter	Type	Required	Description
`id`	string	yes	Agent ID.
`from_output_pos`	number	no	Start output from this position.
`prev_container_id`	string	no	Previously seen container ID.
`prev_status`	string	no	Previously seen status.
`prev_runtime_event_index`	number	no	Runtime event index to continue from.

list_containers Read

List Phantombuster containers (execution runs) for one agent. Returns container IDs, status, timestamps, and optional runtime events.

Lua path: app.integrations.phantombuster.list_containers
Full name: phantombuster.phantombuster_list_containers

Parameter	Type	Required	Description
`agent_id`	string	yes	Agent ID whose containers should be listed.
`before_ended_at`	string	no	Return containers that ended before this date.
`limit`	integer	no	Maximum number of containers.
`mode`	string	no	Return all or only finalized containers.
`with_runtime_events`	boolean	no	Include runtime events.

get_container Read

Get details for a specific Phantombuster container (execution run), including its status, output, and logs.

Lua path: app.integrations.phantombuster.get_container
Full name: phantombuster.phantombuster_get_container

Parameter	Type	Required	Description
`id`	string	yes	The container ID (e.g., "9876543210987654321").
`with_result_object`	boolean	no	Include the result object.
`with_output`	boolean	no	Include output.
`with_runtime_events`	boolean	no	Include runtime events.
`with_newer_and_older_container_id`	boolean	no	Include adjacent container IDs.

fetch_container_output Read

Fetch JSON or raw output for a Phantombuster container.

Lua path: app.integrations.phantombuster.fetch_container_output
Full name: phantombuster.phantombuster_fetch_container_output

Parameter	Type	Required	Description
`id`	string	yes	Container ID.
`mode`	string	no	Output mode. Defaults to json.

fetch_container_result_object Read

Fetch the result object associated with a Phantombuster container.

Lua path: app.integrations.phantombuster.fetch_container_result_object
Full name: phantombuster.phantombuster_fetch_container_result_object

Parameter	Type	Required	Description
`id`	string	yes	Container ID.

list_scripts Read

List scripts available to the authenticated Phantombuster user.

Lua path: app.integrations.phantombuster.list_scripts
Full name: phantombuster.phantombuster_list_scripts

Parameter	Type	Required	Description
No parameters.

get_script Read

Get a Phantombuster script by ID.

Lua path: app.integrations.phantombuster.get_script
Full name: phantombuster.phantombuster_get_script

Parameter	Type	Required	Description
`id`	string	yes	Script ID.

save_script Write

Create or update a Phantombuster script using official /scripts/save fields.

Lua path: app.integrations.phantombuster.save_script
Full name: phantombuster.phantombuster_save_script

Parameter	Type	Required	Description
`payload`	object	yes	Official /scripts/save payload.

delete_script Write

Delete a Phantombuster script by ID.

Lua path: app.integrations.phantombuster.delete_script
Full name: phantombuster.phantombuster_delete_script

Parameter	Type	Required	Description
`id`	string	yes	Script ID.

list_branches Read

List script branches in the current Phantombuster organization.

Lua path: app.integrations.phantombuster.list_branches
Full name: phantombuster.phantombuster_list_branches

Parameter	Type	Required	Description
No parameters.

get_organization Read

Get current Phantombuster organization metadata and optional configuration details.

Lua path: app.integrations.phantombuster.get_organization
Full name: phantombuster.phantombuster_get_organization

Parameter	Type	Required	Description
`with_global_object`	boolean	no	Include the organization global object.
`with_proxies`	boolean	no	Include organization proxies.
`with_crm_integrations`	boolean	no	Include CRM integration metadata.
`with_custom_prompts`	boolean	no	Include custom prompt metadata.

get_ip_location Read

Retrieve the country metadata for an IPv4 or IPv6 address.

Lua path: app.integrations.phantombuster.get_ip_location
Full name: phantombuster.phantombuster_get_ip_location

Parameter	Type	Required	Description
`ip`	string	yes	IPv4 or IPv6 address.

get_current_user Read

Get the authenticated Phantombuster user profile, including account info and plan details.

Lua path: app.integrations.phantombuster.get_current_user
Full name: phantombuster.phantombuster_get_current_user

Parameter	Type	Required	Description
No parameters.

api_get Read

Call a relative Phantombuster API GET path, such as "/agents/fetch-all". Absolute URLs are rejected.

Lua path: app.integrations.phantombuster.api_get
Full name: phantombuster.phantombuster_api_get

Parameter	Type	Required	Description
`path`	string	yes	Relative Phantombuster API path.
`params`	object	no	Query parameters.

api_post Write

Call a relative Phantombuster API POST path. Absolute URLs are rejected.

Lua path: app.integrations.phantombuster.api_post
Full name: phantombuster.phantombuster_api_post

Parameter	Type	Required	Description
`path`	string	yes	Relative Phantombuster API path.
`payload`	object	no	JSON body.

api_put Write

Call a relative Phantombuster API PUT path. Absolute URLs are rejected.

Lua path: app.integrations.phantombuster.api_put
Full name: phantombuster.phantombuster_api_put

Parameter	Type	Required	Description
`path`	string	yes	Relative Phantombuster API path.
`payload`	object	no	JSON body.

api_delete Write

Call a relative Phantombuster API DELETE path. Absolute URLs are rejected.

Lua path: app.integrations.phantombuster.api_delete
Full name: phantombuster.phantombuster_api_delete

Parameter	Type	Required	Description
`path`	string	yes	Relative Phantombuster API path.
`payload`	object	no	Optional JSON body.