# Phantombuster

> PhantomBuster API integration for LinkedIn automation via phantom agents. Manage phantoms (list, launch, stop, get output), organization resources, and lead storage. Use when needing to (1) launch LinkedIn automation phantoms (messaging, connection requests, profile visits), (2) manage phantom agents and their configurations, (3) store and manage leads for automation, (4) check execution status and results, or (5) monitor org resource usage.

- Skill: `buzzmatic/phantombuster` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add buzzmatic/phantombuster`
- Raw SKILL.md: https://api.skillmd.com/api/skills/buzzmatic/phantombuster/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: Buzzmatic (https://skillmd.com/u/buzzmatic)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/buzzmatic/phantombuster

---


# PhantomBuster Skill

Manage PhantomBuster phantoms and LinkedIn automation via the API v2.

## Quick Start

All scripts:
- Accept an optional `--output-dir` parameter (defaults to `output/`)
- Save raw JSON and processed CSV under the output directory (created automatically)
- Return JSON with `{"output_files": [...], "summary": "..."}`

## Authentication

Set `PHANTOMBUSTER_API_KEY` in `.env`:

```bash
export PHANTOMBUSTER_API_KEY="your-api-key"
```

Optional: `PHANTOMBUSTER_ORG_ID` for multi-org setups.

API uses header `X-Phantombuster-Key` for auth, base URL `https://api.phantombuster.com/api/v2`.

## Core Operations

### Test Authentication

```bash
python scripts/auth.py
```

### Organization Info

```bash
python scripts/get_org.py
python scripts/get_org.py --include-resources --include-running
```

### List All Agents (Phantoms)

```bash
python scripts/list_agents.py
python scripts/list_agents.py --output-dir output
```

### Get Agent Details

```bash
python scripts/get_agent.py --agent-id "AGENT_ID"
python scripts/get_agent.py --agent-id "AGENT_ID" --include-output
```

### Launch an Agent

**Async launch (fire and forget):**
```bash
python scripts/launch_agent.py --agent-id "AGENT_ID"
```

**Sync launch (wait for completion):**
```bash
python scripts/launch_agent.py --agent-id "AGENT_ID" --sync --timeout 300
```

**With argument overrides (dynamic configuration):**
```bash
python scripts/launch_agent.py \
  --agent-id "AGENT_ID" \
  --arguments '{"spreadsheetUrl": "https://...", "message": "Hello!"}'
```

**From arguments file:**
```bash
python scripts/launch_agent.py \
  --agent-id "AGENT_ID" \
  --arguments-file path/to/args.json
```

### Stop a Running Agent

```bash
python scripts/stop_agent.py --agent-id "AGENT_ID"
```

### Get Agent Output/Results

```bash
python scripts/get_output.py --agent-id "AGENT_ID"
python scripts/get_output.py --agent-id "AGENT_ID" --output-dir output
```

## Lead Storage

### List all lead lists

```bash
python scripts/manage_leads.py list-all
```

### Create a lead list

```bash
python scripts/manage_leads.py create-list --name "LinkedIn Targets Q1"
```

### Save leads to a list

```bash
python scripts/manage_leads.py save \
  --list-id "LIST_ID" \
  --leads-file path/to/leads.json
```

Lead JSON format:
```json
[
  {"linkedinUrl": "https://linkedin.com/in/username", "firstName": "John", "lastName": "Doe"},
  {"linkedinUrl": "https://linkedin.com/in/other", "firstName": "Jane", "lastName": "Smith"}
]
```

### Search leads

```bash
python scripts/manage_leads.py search \
  --query '{"linkedinUrl": "linkedin.com/in/username"}'
```

### Delete leads

```bash
python scripts/manage_leads.py delete \
  --list-id "LIST_ID" \
  --lead-ids "id1" "id2"
```

## LinkedIn Automation Workflow

PhantomBuster phantoms are pre-configured in the PhantomBuster dashboard for specific LinkedIn tasks. Via API, you:

1. **List agents** to find the right phantom for the task
2. **Launch** with optional argument overrides (target URLs, messages, etc.)
3. **Poll status** or use sync mode to wait for completion
4. **Fetch output** to get results (connections sent, messages delivered, profiles visited)

### LinkedIn Phantom Types & Argument Configs

**LinkedIn Auto Connect** (`linkedin-auto-connect`):
```json
{
  "sessionCookie": "li_at cookie",
  "spreadsheetUrl": "Google Sheets URL or org-storage://leads/by-list/{listId}",
  "numberOfProfilesToProcess": 10,
  "message": "Hi {firstName}, I'd love to connect!",
  "onlySecondCircle": true,
  "disableScrapingWhenAlreadyConnected": true,
  "waitBetweenActions": 5
}
```

**LinkedIn Message Sender** (`linkedin-message-sender`):
```json
{
  "sessionCookie": "li_at cookie",
  "spreadsheetUrl": "Google Sheets URL or org-storage://leads/by-list/{listId}",
  "numberOfProfilesToProcess": 10,
  "message": "Hi {firstName}, ...",
  "onlyFirstCircle": true,
  "waitBetweenActions": 10
}
```
Note: Message Sender only works with 1st-degree connections. Use InMail for non-connections (requires LinkedIn Premium).

**LinkedIn Profile Visitor** (`linkedin-profile-visitor`):
```json
{
  "sessionCookie": "li_at cookie",
  "spreadsheetUrl": "Google Sheets URL",
  "numberOfProfilesToProcess": 50,
  "waitBetweenActions": 3
}
```

**LinkedIn Connection Accepter** (`linkedin-connection-accepter`):
```json
{
  "sessionCookie": "li_at cookie",
  "message": "Thanks for connecting, {firstName}!",
  "numberOfConnectionsToAccept": 20,
  "waitBetweenActions": 3
}
```

**Template variables**: `{firstName}`, `{lastName}`, `{company}`, `{title}`, `{school}`

### LinkedIn Daily Limits (Platform-Enforced)

| Action | Daily Limit | Per Launch |
|--------|-------------|------------|
| Connection requests | 80-100 | 10-20 |
| Messages | 100-150 | 10-20 |
| Profile visits | 200-300 | 30-50 |

### Outreach Pipeline Pattern

1. **Search** prospects -> 2. **Visit** profiles (wait 1 day) -> 3. **Connect** (wait 2 days) -> 4. **Message** new connections

## API Endpoints Reference

| Endpoint | Method | Script |
|----------|--------|--------|
| `/agents/fetch-all` | GET | `list_agents.py` |
| `/agents/fetch` | GET | `get_agent.py` |
| `/agents/launch` | POST | `launch_agent.py` |
| `/agents/stop` | POST | `stop_agent.py` |
| `/agents/fetch-output` | GET | `get_output.py` |
| `/orgs/fetch` | GET | `get_org.py` |
| `/orgs/fetch-resources` | GET | `get_org.py --include-resources` |
| `/orgs/fetch-running-containers` | GET | `get_org.py --include-running` |
| `/org-storage/lists/*` | GET/POST | `manage_leads.py` |
| `/org-storage/leads/*` | POST | `manage_leads.py` |
| `/containers/fetch-result-object` | GET | `get_output.py` |