Swarms API Documentation - Build AI Agents & Multi-Agent Systems

What This Example Shows

A GraphWorkflow shaped as fan-out → fan-in: thousands of per-fund parser nodes run in parallel, then converge into a cross-fund aggregator and a Theme Synthesizer
How to parse raw SEC EDGAR 13F-HR filings (CIK + accession number) into structured holdings, then diff against the prior quarter
The batch volume math for the quarterly burst: ~5,000 filings dropping in 48 hours, dispatched concurrently against /v1/graph-workflow/completions
Model diversification across the DAG: gpt-4.1-mini for mechanical parsing, gpt-4.1 for aggregation, claude-sonnet-5 for the synthesis layer
Journalist-grade output: ranked sector adds/cuts, new positions crossing $100M of cumulative flow, eliminated positions, and named emerging themes with the funds driving them
A reusable pattern for any high-volume regulatory-filing burst (Form 4, N-PORT, NPX)

This tutorial leans on the graph workflow endpoint (/v1/graph-workflow/completions), dispatched concurrently across the filing list for the burst — a premium-only endpoint (Pro, Ultra, Premium). Note that the API’s night-mode discount (see Night-Mode Pricing Strategy) applies only to /v1/swarm/completions and /v1/swarm/batch/completions — it does not apply to /v1/graph-workflow/completions, so running this burst overnight does not itself lower the bill. The reasons to fire it overnight here are operational: EDGAR’s after-hours filing pattern and your own concurrency/rate-limit headroom, not a pricing discount.

Why This Matters

Form 13F-HR filings publish on a 45-day lag — every institutional manager with over $100M AUM has to disclose their long US-equity positions within 45 days of quarter-end, and almost all of them file in the same 48-hour window right at the deadline. ~5,000 filings hit EDGAR essentially simultaneously, and that window is when the entire allocator and newsroom ecosystem scrambles: Bloomberg, the FT, Institutional Investor, fund-of-funds managers, sell-side strategists, and signal traders are all racing to surface “what did the smart money buy” before the next morning’s open. The traditional shape of that work is a junior analyst manually pulling a handful of “name brand” 13Fs (Pershing Square, Tiger, Coatue, Berkshire) and writing one-off blurbs — leaving 4,990 filings unread and the cross-fund themes invisible. A GraphWorkflow turns the firehose into a structured story automatically: every filing parsed, every position diffed, every theme ranked by cumulative dollar flow across all reporting managers. By 7am Pacific on day 2 of the window, you have a brief that took a newsroom team two weeks the old way.

The Architecture

                                         GraphWorkflow
                                ┌─────────────────────────────────┐
EDGAR 13F feed (~5,000 CIKs)    │                                 │
        │                       │ [13F Parser — Fund 1]  ──┐      │
        ▼                       │ [13F Parser — Fund 2]  ──┤      │
[Batch Dispatcher]  ────────►   │ [13F Parser — Fund 3]  ──┼──►   │
   (one swarm                   │           …                │    │
    payload per                 │ [13F Parser — Fund N]  ──┘      │
    filing)                     │           │                     │
                                │           ▼                     │
                                │  [Cross-Fund Aggregator]        │
                                │           │                     │
                                │           ▼                     │
                                │  [Theme Synthesizer]            │
                                └───────────┬─────────────────────┘
                                            │
                                            ▼
                          Markdown brief per theme  +  Top-N adds/cuts per manager
                                            │
                                            ▼
                                    Postgres / Slack

Per-fund parsing happens in parallel inside each filing’s own GraphWorkflow. The batch dispatcher fans the workload out across the 5,000 filings. The synthesis is the cross-cutting layer that runs once across the batched outputs.

Step 1: Setup

pip install requests python-dotenv
export SWARMS_API_KEY="your-api-key-here"

import json
import os
from concurrent.futures import ThreadPoolExecutor, as_completed
from datetime import datetime
from pathlib import Path

import requests
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"

headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}

Step 2: Define the Function Tools

Every tool the parser and aggregator nodes use is declared as an OpenAI-style function tool. The model calls them, the runtime resolves them on your side.

FETCH_13F_FILING = {
    "type": "function",
    "function": {
        "name": "fetch_13f_filing",
        "description": (
            "Download the raw 13F-HR filing for a given CIK and accession number "
            "from SEC EDGAR and return the holdings table as text."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "cik": {
                    "type": "string",
                    "description": "SEC CIK (Central Index Key) of the filing manager, zero-padded to 10 digits.",
                },
                "accession": {
                    "type": "string",
                    "description": "EDGAR accession number, e.g. '0001172661-24-000123'.",
                },
            },
            "required": ["cik", "accession"],
        },
    },
}

PARSE_13F_HOLDINGS = {
    "type": "function",
    "function": {
        "name": "parse_13f_holdings",
        "description": (
            "Parse the raw informationTable.xml body of a 13F-HR filing into a "
            "list of holdings with ticker, CUSIP, issuer, shares, and market value."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "filing_text": {
                    "type": "string",
                    "description": "Raw XML or text body of the 13F informationTable.",
                }
            },
            "required": ["filing_text"],
        },
    },
}

LOOKUP_FUND_PROFILE = {
    "type": "function",
    "function": {
        "name": "lookup_fund_profile",
        "description": (
            "Return the fund's name, AUM bucket, strategy tag (e.g. long-short, "
            "activist, quant, family office), and known PM."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "cik": {"type": "string", "description": "Manager CIK."},
            },
            "required": ["cik"],
        },
    },
}

DIFF_QUARTER_HOLDINGS = {
    "type": "function",
    "function": {
        "name": "diff_quarter_holdings",
        "description": (
            "Compute position deltas between this quarter and the prior quarter. "
            "Returns adds, trims, new positions, and eliminated positions with "
            "share-count and market-value changes."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "this_q": {
                    "type": "array",
                    "description": "Holdings array for the current quarter.",
                    "items": {"type": "object"},
                },
                "last_q": {
                    "type": "array",
                    "description": "Holdings array for the prior quarter.",
                    "items": {"type": "object"},
                },
            },
            "required": ["this_q", "last_q"],
        },
    },
}

CROSS_FUND_AGGREGATE = {
    "type": "function",
    "function": {
        "name": "cross_fund_aggregate",
        "description": (
            "Aggregate per-fund adds and cuts into cross-fund sector flows. "
            "Sums cumulative dollar inflow/outflow per ticker and per GICS sector."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "adds_by_sector": {
                    "type": "object",
                    "description": "Map of sector → list of {ticker, fund_cik, dollar_change}.",
                },
                "cuts_by_sector": {
                    "type": "object",
                    "description": "Map of sector → list of {ticker, fund_cik, dollar_change}.",
                },
            },
            "required": ["adds_by_sector", "cuts_by_sector"],
        },
    },
}

IS_NEW_POSITION = {
    "type": "function",
    "function": {
        "name": "is_new_position",
        "description": (
            "Check whether a ticker is a brand-new position for the fund by "
            "scanning the fund's prior 8 quarters of holdings history."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "ticker": {"type": "string", "description": "Equity ticker."},
                "fund_history": {
                    "type": "array",
                    "description": "Array of prior-quarter holdings arrays for this fund.",
                    "items": {"type": "object"},
                },
            },
            "required": ["ticker", "fund_history"],
        },
    },
}

POST_THEME_BRIEF_TO_SLACK = {
    "type": "function",
    "function": {
        "name": "post_theme_brief_to_slack",
        "description": (
            "Post a rendered Markdown theme brief to the #13f-tracker Slack channel."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "text": {
                    "type": "string",
                    "description": "Rendered Markdown body of the theme brief.",
                }
            },
            "required": ["text"],
        },
    },
}

PARSER_TOOLS = [FETCH_13F_FILING, PARSE_13F_HOLDINGS, LOOKUP_FUND_PROFILE, DIFF_QUARTER_HOLDINGS, IS_NEW_POSITION]
AGGREGATOR_TOOLS = [CROSS_FUND_AGGREGATE]
SYNTHESIZER_TOOLS = [POST_THEME_BRIEF_TO_SLACK]

Step 3: Define the Graph Workflow Nodes

The shape is fan-out → fan-in. Each per-fund parser is a node that fetches the filing, parses the holdings table, looks up the fund profile, and diffs against the prior quarter. Multiple parsers run in parallel inside one GraphWorkflow when a filing covers multiple sub-funds under one umbrella manager. They converge into a Cross-Fund Aggregator, which feeds the Theme Synthesizer. Models are diversified across the DAG by the cognitive load of each node:

Per-fund parsers → gpt-4.1-mini — cheap, fast, mechanical. Most of the work is tool calling against structured XML.
Cross-fund aggregator → gpt-4.1 — needs to reason over many per-fund summaries and group them coherently.
Theme synthesizer → claude-sonnet-5 — produces the journalist-grade narrative the brief is built around.

def build_13f_workflow_for_filing(cik: str, accession: str, fund_name: str, sub_funds: list[str]) -> dict:
    """
    Build the GraphWorkflow payload for a single 13F filing.

    Graph structure:
        [Parser — sub-fund 1] ──┐
        [Parser — sub-fund 2] ──┼──> [CrossFundAggregator] ──> [ThemeSynthesizer]
        [Parser — sub-fund N] ──┘
    """
    parser_agents = [
        {
            "agent_name": f"Parser_{sub}",
            "description": f"Per-fund 13F parser for {sub}.",
            "system_prompt": (
                "You are a 13F parser. Use the provided tools to: "
                "(1) fetch_13f_filing(cik, accession), "
                "(2) parse_13f_holdings on the raw text, "
                "(3) lookup_fund_profile(cik) for context, "
                "(4) diff_quarter_holdings against the prior quarter. "
                "Return a compact JSON object with: fund_name, strategy, "
                "top_5_adds, top_5_cuts, new_positions, eliminated_positions. "
                "Be terse — no prose."
            ),
            "model_name": "gpt-4.1-mini",
            "max_tokens": 3000,
            "temperature": 0.1,
            "max_loops": 1,
            "tools_list_dictionary": PARSER_TOOLS,
        }
        for sub in sub_funds
    ]

    aggregator_agent = {
        "agent_name": "CrossFundAggregator",
        "description": "Aggregates per-fund deltas into cross-fund sector flows.",
        "system_prompt": (
            "You receive per-fund delta JSON from upstream parsers. "
            "Group adds and cuts by GICS sector, sum cumulative dollar flow per "
            "ticker, and call cross_fund_aggregate. Output a JSON object: "
            "{sector_adds, sector_cuts, top_inflows, top_outflows}. No prose."
        ),
        "model_name": "gpt-4.1",
        "max_tokens": 4000,
        "temperature": 0.2,
        "max_loops": 1,
        "tools_list_dictionary": AGGREGATOR_TOOLS,
    }

    synthesizer_agent = {
        "agent_name": "ThemeSynthesizer",
        "description": "Produces the journalist-grade theme brief.",
        "system_prompt": (
            "You are a senior markets editor. Given the aggregated cross-fund "
            "sector flows, produce a Markdown brief with: (1) top 10 sector adds "
            "with dollar magnitudes and named funds driving each, (2) top 10 "
            "sector cuts, (3) new positions crossing $100M of cumulative flow, "
            "(4) eliminated positions, (5) 3-5 emerging themes with named funds. "
            "Cite manager names. Be specific, numbers-forward, and printable."
        ),
        "model_name": "claude-sonnet-5",
        "max_tokens": 6000,
        "temperature": 0.4,
        "max_loops": 1,
        "tools_list_dictionary": SYNTHESIZER_TOOLS,
    }

    edges = (
        [{"source": p["agent_name"], "target": "CrossFundAggregator"} for p in parser_agents]
        + [{"source": "CrossFundAggregator", "target": "ThemeSynthesizer"}]
    )

    return {
        "name": f"13F-Tracker — {fund_name}",
        "description": f"Per-fund GraphWorkflow for {fund_name} ({cik}) filing {accession}.",
        "max_loops": 1,
        "task": (
            f"Process the 13F-HR filing for {fund_name} (CIK {cik}, accession "
            f"{accession}). Parse all sub-fund holdings, diff against the prior "
            f"quarter, aggregate cross-fund flows, and produce the theme brief."
        ),
        "agents": parser_agents + [aggregator_agent, synthesizer_agent],
        "edges": edges,
        "entry_points": [p["agent_name"] for p in parser_agents],
        "end_points": ["ThemeSynthesizer"],
    }

Step 4: Run One Fund’s 13F

Smoke-test the shape against a single filing before you fire the burst. Pershing Square’s umbrella files include the main fund plus the SPARC vehicle, which makes for a clean multi-parser fan-in.

def run_single_filing(cik: str, accession: str, fund_name: str, sub_funds: list[str]) -> dict:
    payload = build_13f_workflow_for_filing(cik, accession, fund_name, sub_funds)
    response = requests.post(
        f"{BASE_URL}/v1/graph-workflow/completions",
        headers=headers,
        json=payload,
        timeout=300,
    )
    response.raise_for_status()
    return response.json()


result = run_single_filing(
    cik="0001336528",
    accession="0001172661-24-000123",
    fund_name="Pershing Square Capital",
    sub_funds=["PSCM_Main", "PSCM_SPARC"],
)

for node, output in result.get("outputs", {}).items():
    print("=" * 60)
    print(f"[{node}]")
    print("=" * 60)
    if isinstance(output, list):
        output = " ".join(str(o) for o in output)
    print(str(output)[:600])

print(f"\nToken cost: {result['usage']['total_cost']:.4f} credits")
print(f"Status: {result['status']}")

The ThemeSynthesizer output for a single filing is just that one manager’s contribution to the cross-fund picture. The real value emerges when you batch it across the full 5,000-fund universe in Step 5 — at that point the aggregator sees the entire flow and the themes pop.

Step 5: The Quarterly Burst — 5,000 Funds in One Night

Production shape: you have a feed (EDGAR’s RSS or a vendor like SEC-API.io) emitting accession numbers as they hit the system. You buffer them across the 48-hour deadline window, then fire one batch at 11pm Pacific on day 1 of the burst.

# Imagine this list comes from a pull of EDGAR's 13F-HR daily index for the
# deadline week. ~5,000 entries in practice.
QUARTERLY_FILINGS = [
    {"cik": "0001336528", "accession": "0001172661-24-000123", "fund_name": "Pershing Square Capital", "sub_funds": ["PSCM_Main"]},
    {"cik": "0001478912", "accession": "0001478912-24-000089", "fund_name": "Tiger Global Management", "sub_funds": ["TGM_Main", "TGM_PIPE"]},
    {"cik": "0001423053", "accession": "0001423053-24-000045", "fund_name": "Coatue Management", "sub_funds": ["Coatue_LP"]},
    {"cik": "0001067983", "accession": "0001067983-24-000018", "fund_name": "Berkshire Hathaway", "sub_funds": ["BRK_Core"]},
    # ... ~5,000 entries pulled from the EDGAR 13F-HR daily index
]


def _run_one_filing(filing: dict) -> dict:
    payload = build_13f_workflow_for_filing(
        cik=filing["cik"],
        accession=filing["accession"],
        fund_name=filing["fund_name"],
        sub_funds=filing["sub_funds"],
    )
    response = requests.post(
        f"{BASE_URL}/v1/graph-workflow/completions",
        headers=headers,
        json=payload,
        timeout=300,
    )
    response.raise_for_status()
    return response.json()


def run_quarterly_burst(filings: list[dict], max_workers: int = 50) -> list[dict]:
    """
    There is no bulk endpoint for graph workflows, so the burst is a pool of
    concurrent single calls to /v1/graph-workflow/completions rather than one
    request carrying the whole list. Tune max_workers against your account's
    concurrency and rate limits — see /v1/rate/limits.
    """
    print(f"Dispatching burst of {len(filings)} GraphWorkflows across {max_workers} workers.")

    results: list[dict] = []
    with ThreadPoolExecutor(max_workers=max_workers) as pool:
        futures = {pool.submit(_run_one_filing, f): f for f in filings}
        for future in as_completed(futures):
            filing = futures[future]
            try:
                results.append(future.result())
            except requests.HTTPError as exc:
                results.append({"error": str(exc), "cik": filing["cik"], "accession": filing["accession"]})
    return results


results = run_quarterly_burst(QUARTERLY_FILINGS)

# Persist raw responses first — partial network failures are easier to recover
# from when you have the bytes on disk.
out_dir = Path("13f_runs") / datetime.utcnow().strftime("%Y-Q%m-%d")
out_dir.mkdir(parents=True, exist_ok=True)
(out_dir / "raw_batch_response.json").write_text(json.dumps(results, indent=2))

The math. A single 5-node GraphWorkflow per filing — three lean parsers on gpt-4.1-mini, one aggregator on gpt-4.1, one synthesizer on claude-sonnet-5 — comes out to roughly $0.04 per filing. Across the full quarterly burst:

Volume	Per-filing cost	Total
5,000 13F-HR filings	~$0.04	~$200

A takeout dinner gets you the entire quarter’s 13F coverage. Run four times a year and your annual budget for the program is roughly $800 in API cost.

/v1/graph-workflow/completions token costs do not get the night-mode discount (that applies only to /v1/swarm/completions and /v1/swarm/batch/completions — see Night-Mode Pricing Strategy). Firing the burst overnight is still worth doing here to stay clear of daytime rate-limit and concurrency contention on other production workloads — see Rate Limits if you need to chunk a larger batch across multiple windows.

Step 6: The Theme Synthesizer Output

A representative ThemeSynthesizer output for the cross-fund aggregate. This is the artifact your DB, Slack channel, and morning newsletter pull from.

# 13F Tracker — Q3 2024 Cross-Fund Brief
Reporting universe: 4,983 13F-HR filings, $6.4T in long US-equity AUM.

## Top 10 Sector Adds (by cumulative net dollar inflow)

| Rank | Sector                  | Cumulative Net Add | Named Managers Driving |
| ---- | ----------------------- | ------------------ | ---------------------- |
| 1    | Semiconductors          | +$18.4B            | Coatue, Tiger Global, Lone Pine, Whale Rock |
| 2    | Hyperscaler infra       | +$12.1B            | Pershing Square, ValueAct, Pat Dorsey |
| 3    | Power & utilities       | +$ 9.7B            | Berkshire, Soros, Third Point |
| 4    | Defense primes          | +$ 6.2B            | Discovery Capital, Maverick, Viking |
| 5    | Obesity-adjacent biotech| +$ 5.9B            | Baker Bros, Perceptive, RTW |
| ...  | ...                     | ...                | ... |

## Top 10 Sector Cuts (by cumulative net dollar outflow)

| Rank | Sector                  | Cumulative Net Cut | Named Managers Driving |
| ---- | ----------------------- | ------------------ | ---------------------- |
| 1    | Regional banks          | -$ 8.7B            | Hound Partners, Greenlight, Pershing Square |
| 2    | China ADRs              | -$ 7.4B            | Tiger Global, Coatue, Lone Pine |
| 3    | Legacy media            | -$ 4.1B            | Third Point, Trian, ValueAct |
| ...  | ...                     | ...                | ... |

## New Positions Crossing $100M Cumulative Flow

- **VST** (Vistra) — 14 funds initiated, $1.9B cumulative; Berkshire, Soros, Third Point
- **CRWV** (CoreWeave) — 9 funds initiated, $640M cumulative; Coatue, Tiger Global, Whale Rock
- **VRT** (Vertiv) — 11 funds initiated, $480M cumulative; Pershing Square, Lone Pine
- **SMCI** (Super Micro) — 7 funds initiated, $310M cumulative; Maverick, Discovery

## Eliminated Positions

- **PYPL** — 22 funds eliminated, $2.1B exiting; concentrated in long-short pods
- **BABA** — 18 funds eliminated, $1.6B exiting; Tiger Global, Lone Pine, Hound
- **CVS** — 12 funds eliminated, $740M exiting; ValueAct, Glenview

## Emerging Themes

1. **Power buildout as the AI shadow trade.** Power & utilities (+$9.7B) plus
   hyperscaler infra (+$12.1B) reads as one trade: capacity to feed the
   datacenter buildout. Berkshire (VST), Third Point (CEG), and Soros (NRG)
   are the names to watch.
2. **Semis are crowding.** Coatue, Tiger, Lone Pine, and Whale Rock are all
   adding the same five names (NVDA, AVGO, AMD, TSM, MRVL). When the velocity
   tightens like this, the unwind is fast — flag for the desk.
3. **China ADR capitulation.** -$7.4B cut concentrated in BABA, JD, PDD across
   the long-only crossover managers. The cleanup is finally happening.
4. **Obesity drugs broadening.** Baker, Perceptive, and RTW added second-tier
   names (VKTX, ALT, STRC) alongside their existing LLY/NVO core — signaling
   conviction that the platform is bigger than two names.
5. **Defense primes rotation.** Discovery and Maverick added LMT, NOC, GD
   simultaneously — the same week as the supplemental funding bill passed.

The Slack post fires automatically via the post_theme_brief_to_slack tool. The structured per-manager output also writes to a Postgres table so the desk can query “every fund that added NVDA this quarter, ranked by dollar size.”

Real Cost vs. Newsroom 13F Team

Approach	Wall time	Cost per quarter	Annualized
Junior research analyst manually pulling ~50 “name brand” 13Fs	~2 weeks of nights	—	~$120,000 fully loaded
Senior markets editor reviewing and writing the brief under deadline	~3 days each quarter	—	~$200,000 fully loaded
Combined 2-person desk (junior + senior) covering ~50 funds	~2 weeks	~$10,000–$20,000 in burdened labor	~$320,000+
GraphWorkflow batch burst, 5,000 funds	~1 hour server-side	~$200	~$800

The swarm isn’t replacing the senior editor — it’s replacing the two weeks of mechanical 13F-pulling that buries them. The editor now lands at their desk on day 2 of the window with the entire universe of 4,983 filings already parsed, diffed, and themed. Their job becomes choosing which three themes to lead with — the work that actually requires judgement.

Next Steps

SEC Filing Triage Pipeline for the same fan-out pattern applied to 8-K, S-1, and 10-K firehoses
Insider Form 4 Monitor for the daily-burst variant: insider transactions instead of quarterly positions
Graph Workflows for Production Pipelines for the DAG-shape reference and conditional gating patterns
Night-Mode Pricing Strategy for how the off-peak discount works on /v1/swarm/completions — useful if you rebuild a stage of this pipeline on the swarm endpoint instead of GraphWorkflow

Getting Started

MCP Server Tutorials

Agent Capabilities

Multi-Agent Architectures

Finance & Investing

Healthcare & Life Sciences

Legal, M&A & Diligence

Customer Operations

Defense, Gov & Supply Chain

Marketing, Content & Founder Tools

API Utilities

Migration Guides

Resources

Production

Compatibility & Benchmarks

Tutorials & Integrations

13F Tracker: Quarterly Hedge Fund Position Changes at Scale

What This Example Shows

Why This Matters

The Architecture

Step 1: Setup

Step 2: Define the Function Tools

Step 3: Define the Graph Workflow Nodes

Step 4: Run One Fund’s 13F

Step 5: The Quarterly Burst — 5,000 Funds in One Night

Step 6: The Theme Synthesizer Output

Real Cost vs. Newsroom 13F Team

Next Steps

​What This Example Shows

​Why This Matters

​The Architecture

​Step 1: Setup

​Step 2: Define the Function Tools

​Step 3: Define the Graph Workflow Nodes

​Step 4: Run One Fund’s 13F

​Step 5: The Quarterly Burst — 5,000 Funds in One Night

​Step 6: The Theme Synthesizer Output

​Real Cost vs. Newsroom 13F Team

​Next Steps

What This Example Shows

Why This Matters

The Architecture

Step 1: Setup

Step 2: Define the Function Tools

Step 3: Define the Graph Workflow Nodes

Step 4: Run One Fund’s 13F

Step 5: The Quarterly Burst — 5,000 Funds in One Night

Step 6: The Theme Synthesizer Output

Real Cost vs. Newsroom 13F Team

Next Steps