# Frontrun API - Full Documentation

> Generated 2026-08-07T21:33:35.967Z. Single-file dump of all docs at https://www.frontrun.vc.

This file contains every page of the Frontrun API documentation in one document, optimized for ingestion by an LLM. Each page is delimited by an `---` rule and includes its source URL. For the structured index, see https://www.frontrun.vc/llms.txt.

---

# Introduction

> Source: https://www.frontrun.vc/docs
> Raw markdown: https://www.frontrun.vc/raw/docs.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Programmatic access to VC follow graph intelligence on X. Track accounts, detect new follows, surface convergence signals, and classify entities - all through a REST API designed for agents and automation.

**Base URL:** `https://frontrun.vc/v1`

---

## For LLMs and agents

Every page on this site is also available as raw markdown - use the **Copy page** button at the top of any page, or pull the whole spec at once:

| File | What it is |
|---|---|
| [`/llms.txt`](/llms.txt) | [llmstxt.org](https://llmstxt.org) index - every page with a one-line summary and a link to its raw markdown |
| [`/llms-full.txt`](/llms-full.txt) | Entire docs concatenated into a single file. Drop into any LLM context for instant working knowledge of the API |
| `/docs/raw/<path>.md` | Per-page raw markdown for any doc URL (e.g. `/docs/raw/endpoints/follows-new.md`) |

These files regenerate on every deploy. Point an agent at `llms-full.txt` and it has the full API reference, integration guides, and use-case examples in one shot.

---

## What you get

Frontrun monitors X accounts and surfaces follow activity changes as structured, enriched data:

- **New follows** - who accounts started following and when
- **Convergence** - entities followed by multiple tracked accounts independently
- **Trending** - entities ranked by attention across your tracked set
- **Activity profiles** - per-account follow velocity and sector focus
- **AI classification** - every entity tagged by sector, type, and confidence
- **Custom rules** - build your own classification layer on top

---

## Core concepts

### Tracked accounts

A tracked account is an X account that Frontrun monitors for follow activity. Add them via `POST /v1/track` or through the dashboard.

### Classification

Passing `?classify=true` on supported endpoints enriches returned entities with AI classification:

- `is_company` - whether the account represents a company or project
- `sector` - e.g., `"AI/ML"`, `"Fintech"`, `"Crypto/Web3"`, `"Enterprise SaaS"`
- `entity_type` - e.g., `"startup"`, `"growth_company"`, `"vc_fund"`, `"individual"`
- `confidence` - `"high"`, `"medium"`, or `"low"`

---

## Pricing

API + MCP access is included with **Pro**. Starter covers the web app only.

| Plan | Monthly cost | Credits included | API + MCP |
|---|---|---|---|
| **Starter** | $49/mo | - | No |
| **Pro** | $99/mo | 10,000/mo | Yes |
| **Enterprise** | Custom | Unlimited | Yes |

Standard rates: 4 credits basic, 16 signal, 24 trending, 40 thesis search, 60 company deep-dive, 100 founder intelligence. Pro has no trial - API access unlocks immediately on payment.

Every response includes `cost_credits` and `balance_credits` so you always know your spend.

[Full pricing details →](/docs/reference/pricing)

---

## Quickstart

### Get your API key

Generate an API key from your [Frontrun dashboard](https://frontrun.vc/dashboard). Pro subscribers get 10,000 monthly credits automatically; top-up packs are available via the developer page.

Machine-readable spec: the full API is described in an [OpenAPI 3.1 spec at /openapi.json](https://www.frontrun.vc/openapi.json) - point a generator, a Postman import, or your agent at it.

## Remote MCP endpoint (beta)

No local install needed - the Frontrun MCP server is also hosted at `https://www.frontrun.vc/mcp` (streamable HTTP).

**claude.ai / Claude Desktop:** Settings → Connectors → Add custom connector → paste `https://mcp.frontrun.vc`. Claude opens a Frontrun login and handles auth via OAuth - no key to copy.

**Any other MCP client:** authenticate with your API key:

```
URL:    https://www.frontrun.vc/mcp
Header: Authorization: Bearer <your API key>
```

For Claude Code: `claude mcp add --transport http frontrun https://www.frontrun.vc/mcp --header "Authorization: Bearer <your API key>"`. Same 36 tools, same credit metering as the [`frontrun-mcp-server`](https://www.npmjs.com/package/frontrun-mcp-server) npm package.

### Track an account

```bash
curl -X POST https://frontrun.vc/v1/track \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"username": "pmarca"}'
```

```json
{
  "username": "pmarca",
  "tracking": true,
  "follow_count": 70,
  "cost_credits": 4,
  "balance_credits": 9996,
  "message": "Tracking active. New follows will appear once activity is detected."
}
```

### Query new follows

```bash
curl https://frontrun.vc/v1/follows/new?since=48h \
  -H "X-API-Key: your_api_key"
```

```json
{
  "since": "2026-03-05T04:00:00.000Z",
  "accounts_checked": 1,
  "total_new_follows": 3,
  "cost_credits": 16,
  "balance_credits": 9980,
  "results": [
    {
      "tracked_account": "pmarca",
      "new_follows_count": 3,
      "new_follows": [
        {
          "twitter_user_id": "1234567890",
          "username": "newai_startup",
          "name": "NewAI",
          "description": "Building the future of AI infrastructure",
          "verified": true
        }
      ]
    }
  ]
}
```

---

# GET /v1/status

> Source: https://www.frontrun.vc/docs/endpoints/status
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/status.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Returns your tier, credit balance, tracked account count, daily spend, and 30-day usage breakdown.

**Cost:** Free

```bash
curl https://frontrun.vc/v1/status \
  -H "X-API-Key: your_api_key"
```

## Response

```json
{
  "tier": "pro",
  "mcp_access": true,
  "tracked_accounts": 12,
  "balance": {
    "credits": 9840,
    "monthly_credits": 8400,
    "topup_credits": 1440
  },
  "daily_spend": {
    "credits": 320,
    "cap_credits": 80000
  },
  "usage_30d": {
    "total_calls": 347,
    "total_credits": 6428,
    "by_operation": {
      "follows_new": { "calls": 280, "credits": 4480 },
      "track_setup": { "calls": 12, "credits": 48 },
      "convergence": { "calls": 30, "credits": 1800 },
      "follows_snapshot": { "calls": 25, "credits": 100 }
    }
  },
  "pricing_credits": {
    "track_setup": 4,
    "follows_new": 16,
    "follows_snapshot": 4,
    "convergence": 60,
    "classification": 16
  },
  "rate_multiplier": 1.0
}
```

## Response fields

| Field | Type | Description |
|-------|------|-------------|
| `tier` | string | Your subscription tier: `free`, `pro`, or `enterprise`. |
| `mcp_access` | boolean | Whether your plan includes MCP access. |
| `tracked_accounts` | integer | Number of accounts currently being monitored. |
| `balance` | object | Available credits. `monthly_credits` is your subscription allowance (resets each billing period); `topup_credits` is purchased balance (never expires); `credits` is the total. |
| `daily_spend` | object | Credits spent today and your daily cap (`cap_credits` is `null` when no cap applies). |
| `usage_30d` | object | Usage for the last 30 days, grouped by operation, in credits. |
| `pricing_credits` | object | Current per-operation pricing in credits, at your tier's rate. |
| `rate_multiplier` | number | `2.5` on the free tier, `1.0` for subscribers. |

---

# MCP Server

> Source: https://www.frontrun.vc/docs/integrations/mcp-server
> Raw markdown: https://www.frontrun.vc/raw/docs/integrations/mcp-server.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

The Frontrun MCP server gives AI agents native access to the Frontrun API. 36 tools, version 2.6.0.

## Claude (claude.ai and Claude Desktop): custom connector

The fastest way to connect. No install, no key handling:

1. Open Claude → **Settings** → **Connectors** → **Add custom connector**
2. Paste the server URL:

```
https://mcp.frontrun.vc
```

3. Claude opens a Frontrun login window. Sign in, click **Connect**, done.

Behind the scenes this uses OAuth: Claude gets your personal MCP key, which you can revoke anytime at frontrun.vc → **Settings** → **API Keys**. Requires an active Pro subscription or trial.

For terminal and IDE clients (Claude Code, Cursor), everything below runs via `npx`.

## Setup

### Option A: OAuth login (recommended)

No API key needed. Log in with your frontrun.vc account directly:

```bash
# Step 1: Log in - opens browser to frontrun.vc, saves credentials locally
npx frontrun-mcp-server --login

# Step 2: Auto-configure your client
npx frontrun-mcp-server --setup         # Claude Desktop
npx frontrun-mcp-server --setup-code    # Claude Code (uses `claude mcp add`)
```

Credentials are saved to `~/.frontrun/credentials.json`.

```bash
npx frontrun-mcp-server --status   # Check auth status
npx frontrun-mcp-server --logout   # Clear saved credentials
```

### Option B: Manual API key

Go to [frontrun.vc](https://frontrun.vc) → **Settings** → **API Keys** and create a key (starts with `sig_`). Then configure your client below.

---

### Claude Code

**If you used `--setup-code` above, you're done.** Otherwise, run:

```bash
claude mcp add frontrun -e FRONTRUN_API_KEY=your_api_key --scope user -- npx frontrun-mcp-server
```

The `--scope user` flag makes it available in every project. Verify with `claude mcp list`.

---

### Claude Desktop

**If you used `--setup` above, you're done.** Otherwise, add to your config file:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "frontrun": {
      "command": "npx",
      "args": ["frontrun-mcp-server"],
      "env": {
        "FRONTRUN_API_KEY": "your_api_key"
      }
    }
  }
}
```

Restart Claude Desktop. The Frontrun tools will appear automatically.

---

### Cursor

Add to `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "frontrun": {
      "command": "npx",
      "args": ["frontrun-mcp-server"],
      "env": {
        "FRONTRUN_API_KEY": "your_api_key"
      }
    }
  }
}
```

---

### Python

```python
import subprocess, json

process = subprocess.Popen(
    ["npx", "frontrun-mcp-server"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    env={"FRONTRUN_API_KEY": "your_api_key", "PATH": "/usr/local/bin:/usr/bin"}
)
```

---

### JavaScript

```javascript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["frontrun-mcp-server"],
  env: { FRONTRUN_API_KEY: "your_api_key" },
});

const client = new Client({ name: "my-app", version: "1.0.0" });
await client.connect(transport);
```

---

## Available tools (36)

### No API key required

| Tool | Description |
|------|-------------|
| `trending_teaser` | Free sample: top 5 trending companies from the last 7 days, no auth needed |
| `send_feedback` | Report a confusing error, a missing capability, or a docs gap to the Frontrun team |

### Tracking

| Tool | Description |
|------|-------------|
| `frontrun_status` | Account status, balance, usage stats |
| `frontrun_list_tracked` | List all monitored accounts |
| `frontrun_track` | Start monitoring an X account |
| `frontrun_untrack` | Stop monitoring an X account |
| `frontrun_preview` | Preview an account before tracking - signal score, sector hints, recommendation |

### Signals

| Tool | Description |
|------|-------------|
| `frontrun_new_follows` | Detect new follows across tracked accounts |
| `frontrun_snapshot` | Get current follow list for an account |
| `frontrun_enriched_follows` | New follows with full AI enrichment |
| `frontrun_convergence` | Detect multi-account convergence signals |
| `frontrun_trending` | Get trending entities by follow velocity |
| `frontrun_search` | Search entities by sector, keyword, or type |
| `frontrun_thesis_search` | Semantic thesis search - plain-language thesis in, matching companies out |
| `frontrun_feed` | Real-time activity feed across all tracked accounts |
| `frontrun_sectors` | Sector breakdown of discovered entities |
| `frontrun_discover` | Personalized recommendations - accounts your VCs follow that you're not tracking |
| `frontrun_reports` | Generated intelligence reports for your tracked accounts |

### Company intelligence

| Tool | Description |
|------|-------------|
| `frontrun_company` | Company overview - what they do, sector, stage |
| `frontrun_company_founders` | Founder profiles, backgrounds, previous companies (one company) |
| `frontrun_founders_batch` | Founder lookup for up to 10 companies in one call, served from verified cache |
| `frontrun_company_signals` | Social buzz, sentiment, notable engagements |
| `frontrun_company_resources` | Website, GitHub, docs, community links |
| `frontrun_company_funding` | Funding rounds, investors, amounts |

### VC intelligence

| Tool | Description |
|------|-------------|
| `frontrun_vc_activity` | VC follow patterns - velocity, sector focus, recent follows |
| `frontrun_vc_similar` | Find VCs with overlapping follow patterns |

### Classification

| Tool | Description |
|------|-------------|
| `frontrun_classify` | Run AI classification on specific entities |
| `frontrun_create_rule` | Create custom classification rules |
| `frontrun_list_rules` | List classification rules |
| `frontrun_update_rule` | Update a classification rule |
| `frontrun_delete_rule` | Delete a classification rule |
| `frontrun_tag` | Add custom tags/notes to entities |
| `frontrun_list_tags` | List your custom-tagged entities |

### Webhooks

| Tool | Description |
|------|-------------|
| `frontrun_list_webhooks` | List your registered webhooks |
| `frontrun_create_webhook` | Register a webhook for new_follows / convergence events |
| `frontrun_delete_webhook` | Delete a webhook |

## Example prompts

Once connected, ask your agent:

- *"What are the trending companies this week?"*
- *"Show me convergence signals with threshold 3 in the last 14 days"*
- *"What new accounts did pmarca follow in the last 48 hours?"*
- *"Search for AI startups in the follow graph"*
- *"Track @sequoia"*
- *"Tag @openai as a competitor with sector AI"*

## Troubleshooting

**"FRONTRUN_API_KEY environment variable is required"**
Your API key isn't set. Double-check the key in your config or command.

**"Invalid API key"**
The key is wrong or inactive. Generate a new one at frontrun.vc → Settings → API Keys.

**npx command not found**
Install Node.js 18+ from [nodejs.org](https://nodejs.org).

## Compatible clients

Any MCP-compatible client works:

- Claude Code (CLI)
- Claude Desktop
- Cursor
- Windsurf
- Continue
- Custom MCP clients

## Source code

The MCP server is open source: [github.com/jongall45/frontrun-mcp-server](https://github.com/jongall45/frontrun-mcp-server)

---

# Pricing

> Source: https://www.frontrun.vc/docs/reference/pricing
> Raw markdown: https://www.frontrun.vc/raw/docs/reference/pricing.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Frontrun has **two plans**: Starter for the platform, Pro for the platform plus API + MCP access.

---

## Plans

| Plan | Monthly cost | Credits included | API + MCP access | Trial |
|---|---|---|---|---|
| **Starter** | $49/mo | - | No | 7-day free trial |
| **Pro** | $99/mo | 10,000/mo | Yes | None - pay upfront, API unlocks immediately |
| **Enterprise** | Custom | Unlimited | Yes | - |

**Monthly credits do not roll over** - unused monthly credits expire at the end of each billing period. Top-up credits never expire.

---

## What each plan includes

### Starter - $49/mo
- Web app: 100 tracked accounts, daily discovery reports, full history + advanced analytics, watchlist + alerts
- No API or MCP access
- **7-day free trial** - card required, cancel anytime before it converts

### Pro - $99/mo
- Everything in Starter, with 250 tracked accounts
- **API + MCP access** (Claude Code, Cursor, Claude Desktop)
- **10,000 credits every month** (expires monthly)
- Standard credit rates (see table below)
- 80,000 credits/day cap
- 300 requests/minute
- Priority support
- No trial - API access unlocks immediately on payment

### Enterprise
- Unlimited API at custom rates
- Custom rate limits, dedicated support, SLA
- [Contact us](mailto:hello@frontrun.vc)

---

## Standard credit rates

Applies to Pro and Enterprise.

### Free operations

| Operation | Endpoint |
|-----------|----------|
| Account status | `GET /v1/status` |
| List tracked | `GET /v1/track` |
| Remove tracking | `DELETE /v1/track/:handle` |
| Classification rules | CRUD operations |
| Custom tags | CRUD operations |

### Basic - 4 credits

| Operation | Endpoint |
|-----------|----------|
| Track account (new baseline) | `POST /v1/track` |
| Preview account | `GET /v1/preview/:handle` |
| Follow snapshot | `GET /v1/follows/snapshot/:handle` |
| Search | `GET /v1/search` |
| Sectors | `GET /v1/sectors` |
| Reports | `GET /v1/reports` |

### Signal - 16 credits

| Operation | Endpoint |
|-----------|----------|
| New follows | `GET /v1/follows/new` |
| Enriched follows | `GET /v1/follows/enriched` |
| Feed | `GET /v1/feed` |
| AI classification | `POST /v1/classify` (per entity) |
| Company signals | `GET /v1/company/:handle/signals` |

### Trending & activity - 24 credits

| Operation | Endpoint |
|-----------|----------|
| Trending | `GET /v1/trending` |
| VC activity | `GET /v1/vc/:handle/activity` |

### Thesis search - 40 credits

| Operation | Endpoint |
|-----------|----------|
| Thesis search | `GET /v1/search/thesis` |

### Company deep-dive - 60 credits

| Operation | Endpoint |
|-----------|----------|
| Company overview | `GET /v1/company/:handle` |
| Company funding | `GET /v1/company/:handle/funding` |
| Company resources | `GET /v1/company/:handle/resources` |
| Convergence | `GET /v1/convergence` |
| Discover | `GET /v1/discover` |
| VC similar | `GET /v1/vc/:handle/similar` |

### Founder intelligence - 100 credits

| Operation | Endpoint |
|-----------|----------|
| Company founders | `GET /v1/company/:handle/founders` |

### Webhooks

| Operation | Credits |
|-----------|---------|
| Webhook setup | 40 |
| Per delivery | 8 |

---

## Top-up packs

Buy credits any time from the developer page. Top-up credits never expire and are spent after your monthly allowance runs out.

| Pack | Price |
|---|---|
| 4,000 credits | $12 |
| **10,000 credits** - a full monthly refill, most popular | $25 |
| 25,000 credits (+25% bonus) | $50 |
| 60,000 credits (+50% bonus) | $100 |

### Auto-refill

Opt in to auto-refill and Frontrun automatically adds 10,000 credits whenever your balance drops below 1,000 - so long-running agents never stall on a `402`. Configure (or pick a different pack) from the developer page. If a refill payment fails, auto-refill is disabled and you're notified.

---

## Which plan should I pick?

**"I just want to try it"** → Starter. The 7-day free trial covers the full web app - no API.

**"I'm using this for real"** → Pro. 10,000 credits/mo covers ~2,500 basic, ~625 signal, or ~166 deep-dive calls - plus the full web app, 250 tracked accounts, and MCP access. No trial; API unlocks immediately.

**"I need high volume or guarantees"** → Enterprise. Custom rate limits, dedicated support.

---

## Monthly usage examples

**Daily driver on Pro** - web dashboard plus regular API calls

| Usage | Calls/mo | Credits |
|-------|----------|---------|
| Feed 2x/day | 60 | 960 |
| New follows 1x/day | 30 | 480 |
| Convergence 1x/day | 30 | 1,800 |
| Company deep-dives | 15 | 900 |
| Search | 20 | 80 |
| **Total** | | **~4,200 credits** |

Comfortably inside the 10,000 monthly allowance - no top-ups needed.

**Agent on Pro** - autonomous pipeline with MCP

| Usage | Calls/mo | Credits |
|-------|----------|---------|
| Feed hourly | 720 | 11,520 |
| Enriched follows 10x/day | 300 | 4,800 |
| Convergence 5x/day | 150 | 9,000 |
| Company deep-dives | 200 | 12,000 |
| Founder intelligence | 100 | 10,000 |
| Search + discover | 200 | 6,400 |
| **Total** | | **~53,700 credits** |

The monthly 10,000 covers the first chunk; top up with packs for the rest (a $100 pack adds 60,000 credits). Enable auto-refill so the pipeline never stops.

---

## How billing works

1. **Subscribe or buy a pack** - Pro includes 10,000 credits/month; packs top up any account
2. **Monthly credits applied first** - Subscribers spend their monthly allowance before top-up balance
3. **Monthly credits expire** - Unused monthly credits reset each billing period
4. **Top-up never expires** - Credits you buy stay in your balance indefinitely
5. **Track spend** - Every charged response includes `cost_credits` and `balance_credits`
6. **Out of credits** - A `402` response means insufficient credits; top up or enable auto-refill

```json
{
  "data": [...],
  "cost_credits": 16,
  "balance_credits": 9884
}
```

---

# Authentication

> Source: https://www.frontrun.vc/docs/authentication
> Raw markdown: https://www.frontrun.vc/raw/docs/authentication.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

All API requests require an API key passed via the `X-API-Key` header.

```bash
curl https://frontrun.vc/v1/status \
  -H "X-API-Key: your_api_key"
```

## Getting an API key

1. Sign up or log in at [frontrun.vc](https://frontrun.vc)
2. Navigate to **Developer > API Keys**
3. Click **Create Key**
4. Copy and store your key - it will not be displayed again

## Getting credits

Your key needs credits to make billable calls. There are two ways:

- **Subscribe** - Pro ($99/mo, pay upfront) includes API + MCP access and 10,000 credits every month. Credits renew each billing period.
- **Top up** - Buy additional credit packs via the developer page. Top-up credits never expire.

Operations deduct from monthly subscription credits first, then from your top-up balance. Check your current balance anytime with `GET /v1/status`.

[Full pricing →](/docs/reference/pricing)

## Error responses

### 401 Unauthorized

```json
{
  "error": "Missing X-API-Key header",
  "docs": "https://frontrun.vc/docs/api"
}
```

The `X-API-Key` header is missing, or the key is invalid or inactive.

### 402 Payment Required

```json
{
  "error": "Insufficient credits",
  "required_credits": 16,
  "balance_credits": 4,
  "monthly_credits": 0,
  "topup_credits": 4,
  "tier": "free",
  "top_up": "https://frontrun.vc/api/billing"
}
```

Credit balance is insufficient for the requested operation. Top up (or enable auto-refill) to continue.

## Security

- API keys are bearer tokens. Treat them as secrets.
- Do not expose keys in client-side code, public repositories, or browser requests.
- Rotate keys immediately if compromised via your dashboard.
- All API traffic is encrypted over HTTPS.

---

# Track Accounts

> Source: https://www.frontrun.vc/docs/endpoints/track
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/track.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Manage which X accounts you're monitoring for follow activity.

---

## Add Account

`POST /v1/track`

**Cost:** 4 credits

Starts monitoring an X account for new follows.

```bash
curl -X POST https://frontrun.vc/v1/track \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"username": "pmarca"}'
```

### Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `username` | string | Yes | X username to track. Leading `@` is stripped automatically. |

### Response

```json
{
  "username": "pmarca",
  "tracking": true,
  "ready": true,
  "follow_count": 70,
  "cost_credits": 4,
  "balance_credits": 9996,
  "message": "Tracking active. New activity will appear shortly."
}
```

| Field | Type | Description |
|-------|------|-------------|
| `ready` | boolean | `true` once the account is fully initialized and queryable. Newly added accounts may return `false` briefly. |
| `follow_count` | integer | Number of accounts currently being followed. |

### Errors

| Status | Description |
|--------|-------------|
| 402 | Insufficient credits |
| 404 | X account not found |
| 409 | Already tracking this account |

---

## Add Accounts in Bulk

`POST /v1/track`

**Cost:** 4 credits per account **new to the platform**. Accounts already in the
shared coverage pool are free.

Send an array instead of a single `username` and the same endpoint takes a
batch. Onboarding a 150-firm list is 3 calls, not 150.

```bash
curl -X POST https://frontrun.vc/v1/track \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"usernames": ["pmarca", "naval", "paulg"], "max_credits": 40}'
```

### Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `usernames` | string[] | Yes | X usernames to track. Max **50** per request. `handles` is accepted as an alias. Duplicates are collapsed. |
| `max_credits` | integer | No | Cap what this call may cost. See [Budgets & Cursors](/docs/reference/budgets-and-cursors). |

The single-`username` form above is unchanged and still returns `201` / `409` /
`404`. Only an array body takes the batch path.

### Response

Always `200`. Partial success is the normal case, so read the per-item
`status` rather than the HTTP code.

```json
{
  "batch": true,
  "results": [
    { "username": "pmarca", "status": "tracked", "tracking": true, "ready": true, "follow_count": 70, "new_introduction": false, "cost_credits": 0 },
    { "username": "naval", "status": "already_tracked", "tracking": true, "ready": true, "error": "Already tracking this account", "cost_credits": 0 },
    { "username": "not_a_real_handle", "status": "not_found", "error": "Twitter account @not_a_real_handle not found", "cost_credits": 0 }
  ],
  "summary": { "submitted": 3, "tracked": 1, "already_tracked": 1, "not_found": 1 },
  "cost_credits": 0,
  "max_cost_credits": 40,
  "balance_credits": 9996
}
```

### Per-item status values

| Status | Meaning |
|--------|---------|
| `tracked` | Added. `new_introduction: true` means it was new to the platform and billed. |
| `already_tracked` | You were already tracking it. Free. |
| `not_found` | The handle does not resolve on X. Never billed. |
| `invalid` | Empty or malformed handle. |
| `deferred` | Not attempted: this request had already used its 10 new-account introductions. Resubmit just these handles. |
| `intro_cap` | The daily new-account introduction limit for your tier was reached (free 20, starter 100, pro 250, enterprise 2000). Accounts already in the coverage pool are unlimited. |
| `insufficient_credits` | Balance ran out partway through the batch. |
| `tracked_limit` | Your plan's tracked-account quota is full. |
| `upstream_unavailable` | X was temporarily unreachable for this handle. Retry it. |
| `failed` | Server-side failure for this handle. Retry it. |

### Limits worth knowing

- **50 handles per request.** Larger batches return `400` with
  `error_code: "batch_too_large"`.
- **10 new-account introductions per request.** An introduction means a handle
  the platform has never seen, which costs us a live X lookup. Handles past the
  tenth come back `deferred` rather than failed, and the rest of the batch still
  processes. Handles already in the coverage pool do not count.
- **The daily introduction cap is shared across the whole batch**, not applied
  per item, and it is the same counter the single-handle endpoint uses.

---

## Remove Account

`DELETE /v1/track/:username`

**Cost:** Free

Stops monitoring an account.

```bash
curl -X DELETE https://frontrun.vc/v1/track/pmarca \
  -H "X-API-Key: your_api_key"
```

### Response

```json
{
  "username": "pmarca",
  "tracking": false
}
```

---

## List Tracked Accounts

`GET /v1/track`

**Cost:** Free

Returns all accounts you're currently monitoring.

```bash
curl https://frontrun.vc/v1/track \
  -H "X-API-Key: your_api_key"
```

### Response

```json
{
  "count": 3,
  "accounts": [
    {
      "username": "pmarca",
      "ready": true,
      "created_at": "2026-03-01T12:00:00Z"
    },
    {
      "username": "naval",
      "ready": true,
      "created_at": "2026-03-01T12:01:00Z"
    },
    {
      "username": "paulg",
      "ready": false,
      "created_at": "2026-03-07T18:30:00Z"
    }
  ]
}
```

---

# OpenClaw

> Source: https://www.frontrun.vc/docs/integrations/openclaw
> Raw markdown: https://www.frontrun.vc/raw/docs/integrations/openclaw.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Use Frontrun as a data source in your OpenClaw agent. Surface VC follow signals, convergence events, and classified entities directly in your agent's workflow.

## Setup

### Via MCP Server

Add to your OpenClaw agent's MCP configuration:

```json
{
  "mcpServers": {
    "frontrun": {
      "command": "npx",
      "args": ["frontrun-mcp-server"],
      "env": {
        "FRONTRUN_API_KEY": "your_api_key"
      }
    }
  }
}
```

Your agent now has access to all Frontrun tools - tracking, convergence detection, classification, and search.

### Via REST API

If your agent uses HTTP directly, call the REST API:

```python
import requests

FRONTRUN = "https://frontrun.vc/v1"
HEADERS = {"X-API-Key": "your_api_key"}

# Get convergence signals
signals = requests.get(
    f"{FRONTRUN}/convergence",
    headers=HEADERS,
    params={"threshold": 3, "since": "7d"}
).json()
```

---

## Agent Workflows

### Daily deal flow monitor

Set your agent to check Frontrun daily and surface high-signal opportunities:

```
Agent prompt:
"Every morning, check Frontrun for:
1. Convergence signals (threshold 3+) from the last 24 hours
2. Trending entities with classification
3. Any new follows from [priority accounts]

Summarize findings and flag anything in the AI or DeFi sectors."
```

**MCP tools used:** `frontrun_convergence`, `frontrun_trending`, `frontrun_new_follows`

### Automated classification pipeline

Let your agent build and maintain a custom classification layer:

```
Agent prompt:
"Create Frontrun classification rules for my investment thesis:
- AI Infrastructure: keywords 'inference', 'gpu cluster', 'model serving', 'llm ops'
- Developer Tools: keywords 'sdk', 'api platform', 'developer experience'
- DeFi: keywords 'defi', 'lending', 'amm', 'liquidity'

Then pull enriched follows weekly and flag anything matching these rules."
```

**MCP tools used:** `frontrun_create_rule`, `frontrun_enriched_follows`

### VC activity tracker

Monitor specific investors for thesis changes:

```
Agent prompt:
"Track these VCs: @pmarca, @naval, @sequoia, @a16zcrypto
Every week, pull their activity profiles (90-day window).
Compare sector breakdowns week-over-week.
Alert me if any VC shows a >20% shift in sector attention."
```

**MCP tools used:** `frontrun_vc_activity`, `frontrun_track`

### Research assistant

Use Frontrun data as context for deeper research:

```
Agent prompt:
"Search Frontrun for all AI startups in the follow graph.
For any company followed by 3+ tracked accounts, research:
- What do they build?
- Who are their competitors?
- What stage are they at?
Draft a one-paragraph brief for each."
```

**MCP tools used:** `frontrun_search`, `frontrun_convergence`, `frontrun_classify`

---

## Available MCP Tools

All 36 tools, in one table. Credit costs are on the [MCP server](/docs/integrations/mcp-server) page.

| Tool | Description |
|------|-------------|
| `frontrun_status` | Account status, balance, usage |
| `frontrun_track` | Start monitoring an X account |
| `frontrun_untrack` | Stop monitoring |
| `frontrun_list_tracked` | List monitored accounts |
| `frontrun_preview` | Evaluate an account before tracking: signal score, sector hints |
| `frontrun_new_follows` | New follows across tracked accounts |
| `frontrun_snapshot` | Current follow list for an account |
| `frontrun_convergence` | Multi-account convergence signals |
| `frontrun_trending` | Trending entities by attention |
| `frontrun_feed` | Real-time activity feed across tracked accounts |
| `frontrun_vc_activity` | Activity profile: velocity, sectors |
| `frontrun_vc_similar` | VCs with overlapping follow patterns |
| `frontrun_search` | Search by sector, keyword, type (tracked graph or full catalog) |
| `frontrun_thesis_search` | Plain-language investment thesis in, matching companies out |
| `frontrun_sectors` | Sector and entity-type breakdown of discovered entities |
| `frontrun_discover` | Accounts your tracked VCs follow that you're not tracking yet |
| `frontrun_reports` | Historical daily reports, filterable by date range and sector |
| `frontrun_company` | Synthesized company overview: what they do, sector, stage |
| `frontrun_company_founders` | Founder profiles for one company: name, role, background |
| `frontrun_founders_batch` | Founder lookup for up to 10 companies in one call |
| `frontrun_company_funding` | Round details and investors, cross-referenced with follow signal |
| `frontrun_company_signals` | Buzz score, sentiment, which tracked VCs follow them |
| `frontrun_company_resources` | Website, GitHub, docs, Discord, Telegram |
| `frontrun_enriched_follows` | New follows + classification + rules |
| `frontrun_classify` | On-demand entity classification |
| `frontrun_create_rule` | Create classification rule |
| `frontrun_list_rules` | List your rules |
| `frontrun_update_rule` | Update a rule |
| `frontrun_delete_rule` | Delete a rule |
| `frontrun_tag` | Tag an entity, or override its sector |
| `frontrun_list_tags` | List tagged entities |
| `frontrun_list_webhooks` | List registered webhooks with status and last delivery |
| `frontrun_create_webhook` | Register a webhook for new_follows / convergence events |
| `frontrun_delete_webhook` | Delete a webhook |
| `trending_teaser` | Free sample, no API key: top 5 trending companies from the last 7 days |
| `send_feedback` | No API key: report a confusing error, a missing capability, or a docs gap |

---

## Best Practices

- **Cache results** - Data updates periodically, not in real time. Don't poll more than every 30 minutes.
- **Use convergence** - It's the highest-signal endpoint. Threshold 3+ means multiple independent accounts noticed the same entity.
- **Build rules once** - Classification rules persist. Set them up, then every `/enriched` call auto-applies them.
- **Monitor your balance** - Call `frontrun_status` to check spend. Set up balance alerts to avoid interruptions.

---

# Parameters & Limits

> Source: https://www.frontrun.vc/docs/reference/parameters
> Raw markdown: https://www.frontrun.vc/raw/docs/reference/parameters.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

## Time windows

Many endpoints accept time window parameters to control the lookback period.

### `since` parameter

| Format | Example | Description |
|--------|---------|-------------|
| Hours | `since=24h` | Last 24 hours |
| Days | `since=7d` | Last 7 days |
| ISO date | `since=2026-03-01` | Since specific date |
| ISO datetime | `since=2026-03-01T00:00:00Z` | Since specific timestamp |

### `hours` parameter

Shorthand for `since`. Pass an integer number of hours.

```
GET /v1/follows/new?hours=48
# equivalent to: GET /v1/follows/new?since=48h
```

If both `since` and `hours` are provided, `since` takes priority.

### Defaults by endpoint

| Endpoint | Default |
|----------|---------|
| `GET /v1/follows/new` | `24h` |
| `GET /v1/follows/enriched` | `24h` |
| `GET /v1/convergence` | `7d` |
| `GET /v1/trending` | `7d` |
| `GET /v1/vc/:handle/activity` | `30d` |
| `GET /v1/feed` | `24h` |

### Invalid values

If the time parameter can't be parsed, the API returns:

```json
{ "error": "Invalid \"since\" parameter. Use \"24h\", \"7d\", or \"YYYY-MM-DD\"." }
```

## Result limits

| Endpoint | Default | Max |
|----------|---------|-----|
| `GET /v1/search` | 50 | 200 |
| `GET /v1/trending` | 25 | 100 |
| `GET /v1/feed` | 50 | 200 |
| `GET /v1/discover` | 20 | 50 |
| `GET /v1/vc/:handle/similar` | 20 | 50 |

Other endpoints return all matching results within the time window.

## Filtering

### Enriched follows filters

`GET /v1/follows/enriched` supports filtering results by classification:

| Parameter | Example | Description |
|-----------|---------|-------------|
| `sector` | `?sector=DeFi` | Filter by sector (substring match) |
| `keyword` | `?keyword=stablecoin` | Search username, name, description, sector |
| `entity_type` | `?entity_type=company` | Filter by entity type |
| `tag` | `?tag=my-custom-tag` | Filter by custom tag or rule name |

### Feed filters

| Parameter | Values | Description |
|-----------|--------|-------------|
| `event_type` | `new_follow`, `convergence` | Filter by event type |
| `sector` | Any sector string | Filter targets by sector |

### Discover filters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `sector` | - | Narrow by sector |
| `min_signal` | `0.3` | Minimum signal score (0.0 - 1.0) |

## Classification

### AI classification

Several endpoints return classification data:

| Field | Type | Description |
|-------|------|-------------|
| `sector` | string | Primary sector. Free-form, not a fixed enum. Common values include `AI`, `Trading`, `Infrastructure`, `DeFi`, `payments_banking`, `Gaming`, `Social & Creator`, `Payments`. |
| `entity_type` | string | Entity classification. Free-form, not a fixed enum. Common values include `person`, `company`, `project`, `media`, `vc_firm`, `community`, `institution`, `newsletter`. |
| `is_company` | boolean | Whether entity is an organization |
| `confidence` | string | Classification confidence: `high`, `medium`, or `low` |

Classification is probabilistic. For workflows requiring stable labels, query once and cache.

### Sector and entity_type are filters, not an enum

`sector` and `entity_type` are **not** closed lists. The vocabulary comes from the classifier and it grows over time, so treat the values above as examples rather than as the full set. Two naming conventions currently coexist in the data (`RWA` and `rwa`, `Social & Creator` and `social_creator`), and they are stored as distinct values.

Call [`GET /v1/sectors`](/docs/endpoints/sectors) to discover the exact strings present in your own coverage before you hardcode a filter. It is 4 credits and it returns both vocabularies with counts.

How the filters match:

| Parameter | Endpoint | Matching |
|-----------|----------|----------|
| `sector` | `/v1/search`, `/v1/follows/enriched`, `/v1/feed`, `/v1/discover`, `/v1/tags` | Case-insensitive substring |
| `sector` | `/v1/reports` | Case-insensitive substring, matched against sector, name, and description |
| `entity_type` | `/v1/search` (default `scope=tracked`), `/v1/follows/enriched` | Case-insensitive substring |
| `entity_type` | `/v1/search?scope=catalog` | Exact match, case-insensitive |

Because sector matching is a substring, `?sector=pay` returns both `Payments` and `payments_banking`, and `?sector=rwa` returns both `RWA` and `rwa`. Use a short stem to catch every spelling of an idea, and the full string when you want one specific bucket.

### Custom classification rules

Create custom rules via `POST /v1/classify/rules` to tag entities matching your criteria. These rules are applied automatically in `/v1/follows/enriched` and `/v1/discover` responses.

## Data freshness

Follow data is updated periodically through the processing pipeline. The API serves the latest processed data, not live fetches.

- **New follows**: Detected within hours of the actual follow event
- **Tracked accounts**: Baseline established on first track, then monitored daily
- **Classification**: Cached server-side, refreshed periodically
- **Company intelligence**: Fetched on-demand, with upstream caching (60 min Twitter, 2 hr scrape, 24 hr LinkedIn)

## Cost tracking

Every charged response includes cost and balance fields:

```json
{
  "data": [...],
  "cost_credits": 16,
  "balance_credits": 9884
}
```

Use `GET /v1/status` to check your current balance, daily spend, and usage breakdown at any time (free).

---

# GET /v1/preview/:handle

> Source: https://www.frontrun.vc/docs/endpoints/preview
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/preview.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Preview an account before tracking it. Returns profile summary, signal potential score, tracking recommendation, and sector hints.

**Cost:** 4 credits per call

```bash
curl "https://frontrun.vc/v1/preview/stealth_ai_co" \
  -H "X-API-Key: your_api_key"
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `handle` | string (path) | -- | X username to preview. **Required.** |

## Response

```json
{
  "handle": "stealth_ai_co",
  "name": "StealthAI",
  "bio": "Automating enterprise workflows with LLMs",
  "followers": 12400,
  "following": 843,
  "profile_image": "https://pbs.twimg.com/...",
  "sector_hint": "AI/ML",
  "signal_potential": {
    "score": 0.82,
    "hints": [
      "Followed by 3 tracked VCs",
      "High growth in followers (2x in 90 days)",
      "Sector aligns with active VC interest"
    ],
    "recommendation": "track"
  },
  "is_tracked": false,
  "cost_credits": 4,
  "balance_credits": 9992
}
```

| Field | Type | Description |
|-------|------|-------------|
| `signal_potential.score` | number | Signal potential from 0 to 1. Higher means more likely to surface in reports. |
| `signal_potential.recommendation` | string | One of `"track"`, `"maybe"`, or `"skip"`. |
| `is_tracked` | boolean | Whether this account is already in your tracked set. |

---

# Claude Code

> Source: https://www.frontrun.vc/docs/integrations/claude-code
> Raw markdown: https://www.frontrun.vc/raw/docs/integrations/claude-code.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Use Frontrun natively in Claude Code via the MCP server.

## Setup

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "frontrun": {
      "command": "npx",
      "args": ["frontrun-mcp-server"],
      "env": {
        "FRONTRUN_API_KEY": "your_api_key"
      }
    }
  }
}
```

Restart Claude Code. All Frontrun tools are available immediately.

## Available tools

All 36 tools are listed below. The full reference, including credit costs, lives on the [MCP server](/docs/integrations/mcp-server) page.

### Core Intelligence

| Tool | What it does |
|------|-------------|
| `frontrun_trending` | Entities getting the most attention this week |
| `frontrun_convergence` | Entities followed by 2+ tracked accounts |
| `frontrun_new_follows` | Recent follows across tracked accounts |
| `frontrun_enriched_follows` | New follows with AI + custom rules merged |
| `frontrun_feed` | Real-time activity feed across tracked accounts |
| `frontrun_search` | Find entities by sector, keyword, or type (tracked graph or full catalog) |
| `frontrun_thesis_search` | Describe a thesis in plain language, get matching companies |
| `frontrun_sectors` | Sector and entity-type breakdown of your discovered entities |
| `frontrun_discover` | Accounts your tracked VCs follow that you're not tracking yet |
| `frontrun_reports` | Historical daily reports, filterable by date range and sector |
| `frontrun_vc_activity` | Account velocity, sectors, recent follows |
| `frontrun_vc_similar` | VCs with overlapping follow patterns |

### Company Intelligence

| Tool | What it does |
|------|-------------|
| `frontrun_company` | Synthesized overview: what they do, sector, stage, recent activity |
| `frontrun_company_founders` | Founder profiles for one company: name, role, background |
| `frontrun_founders_batch` | Founder lookup for up to 10 companies in one call |
| `frontrun_company_funding` | Round details and investors, cross-referenced with VC follow signal |
| `frontrun_company_signals` | Buzz score, sentiment, and which of your tracked VCs follow them |
| `frontrun_company_resources` | Website, GitHub, docs, Discord, Telegram |

### Account Management

| Tool | What it does |
|------|-------------|
| `frontrun_status` | Check balance, usage, tracked accounts |
| `frontrun_list_tracked` | List all monitored accounts |
| `frontrun_track` | Start monitoring an X account |
| `frontrun_untrack` | Stop monitoring an X account |
| `frontrun_preview` | Evaluate an account before tracking: signal score, sector hints |
| `frontrun_snapshot` | Get the full current follow list for an account |

### Custom Classification

| Tool | What it does |
|------|-------------|
| `frontrun_create_rule` | Create an auto-classification rule |
| `frontrun_list_rules` | List your classification rules |
| `frontrun_update_rule` | Update an existing rule |
| `frontrun_delete_rule` | Remove a rule |
| `frontrun_tag` | Manually tag an entity, or override its sector |
| `frontrun_list_tags` | List all custom-tagged entities |
| `frontrun_classify` | Run on-demand classification |

### Webhooks

| Tool | What it does |
|------|-------------|
| `frontrun_list_webhooks` | List registered webhooks with status and last delivery |
| `frontrun_create_webhook` | Register a webhook for new_follows / convergence events |
| `frontrun_delete_webhook` | Delete a webhook |

### No API key required

| Tool | What it does |
|------|-------------|
| `trending_teaser` | Free sample: top 5 trending companies from the last 7 days |
| `send_feedback` | Report a confusing error, a missing capability, or a docs gap |

---

## Example prompts

```
"What's trending in the last 24 hours?"
```

```
"Show me convergence signals with threshold 3 in the last 14 days"
```

```
"Create a rule to flag any company with 'sales automation' in their bio"
```

```
"Show me pmarca's activity over the last 90 days"
```

---

## CLAUDE.md integration

Add Frontrun context to your project's `CLAUDE.md`:

```markdown
## Frontrun Intelligence

This project has access to Frontrun via MCP server.
Use frontrun_* tools to monitor follow activity, detect convergence, and classify entities.
```

---

# Budgets & Cursors

> Source: https://www.frontrun.vc/docs/reference/budgets-and-cursors
> Raw markdown: https://www.frontrun.vc/raw/docs/reference/budgets-and-cursors.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Two parameters exist for automated callers: `max_credits` caps what a single
call is allowed to cost, and `cursor` makes a repeating job idempotent. Both
are optional and additive. Nothing changes for callers that ignore them.

---

## `max_credits` - cap the cost of one call

Most endpoints are flat-priced, but a few price **per result**. On those, the
final cost depends on how much data came back, which an agent could not know
until after it was charged.

`max_credits` is the ceiling you state up front.

```bash
curl "https://frontrun.vc/v1/trending?limit=100&classify=true&max_credits=200" \
  -H "X-API-Key: your_api_key"
```

It **fails closed**. If the call could cost more than your ceiling, no work is
done, nothing is charged, and you get a `400` telling you the number:

```json
{
  "error": "This call could cost up to 1624 credits, which is above your max_credits of 200. Nothing was charged and no work was done.",
  "error_code": "max_credits_exceeded",
  "max_cost_credits": 1624,
  "max_credits": 200,
  "max_cost_breakdown_credits": { "trending": 24, "classification": 1600 },
  "charged_credits": 0,
  "balance_credits": 9836,
  "hint": "Classification is 16 credits per entity returned. Lower limit (currently 100), drop classify=true, or raise max_credits."
}
```

### The ceiling is checked against the worst case

The check runs against the **maximum** the call could cost, before any billable
work happens. Billing itself is unchanged: you are still charged only for what
was actually computed. A call that clears the ceiling usually lands well under
it.

That matters most on the sections that are free when empty. `include=founders`
could cost 100 credits, so it counts 100 toward the ceiling, but it costs 0 if
no founders are found.

### Reading the estimate without a failed call

Every endpoint that honors `max_credits` returns `max_cost_credits` in its
normal `200` response. That is the same worst-case number, for the parameters
you sent, so you can budget the next call from the last one.

### Where it applies

| Endpoint | What scales the cost |
|----------|----------------------|
| `GET /v1/trending` | `classify=true` adds 16 credits per entity returned |
| `POST /v1/classify` | 16 credits per entity found |
| `GET /v1/search?scope=catalog` | `include_founders=true` adds 100 credits per company that resolves |
| `POST /v1/founders/batch` | 100 credits per company that resolves |
| `GET /v1/company/:handle` | each `include=` section is priced at its standalone rate |
| `POST /v1/track` (batch) | 4 credits per account new to the platform |

On every other endpoint the cost is a fixed number you can read from
[Pricing](/docs/reference/pricing), so `max_credits` is not needed and is
ignored.

---

## `cursor` - resume exactly where the last run stopped

`since` describes a window. It cannot tell you what you have already
processed, so a job that fails and retries either reprocesses its overlap or
guesses at a gap.

A cursor is an opaque watermark. Read a page, process it, save `next_cursor`,
and send it back on the next run.

```bash
# First run: use since as normal.
curl "https://frontrun.vc/v1/follows/new?since=24h" -H "X-API-Key: $KEY"
# -> { ..., "next_cursor": "frc1_eyJ2IjoxLCJ..." }

# Every run after that: no window to guess at.
curl "https://frontrun.vc/v1/follows/new?cursor=frc1_eyJ2IjoxLCJ..." \
  -H "X-API-Key: $KEY"
```

### Rules

- **Persist `next_cursor` only after you have successfully processed the
  response.** If your job dies mid-batch, retrying with the *old* cursor
  returns the same window again. That is the point.
- **Replaying the same cursor is safe** and returns the same window.
- **Cursors are opaque.** Do not parse, edit, or construct them. A modified
  token is rejected.
- **Cursors are scoped** to the endpoint, the API key, and the filters you sent
  (`username`, `sector`, `event_type`, and so on). Change a filter and mint a
  fresh cursor with `since`, otherwise the records your old filter excluded
  would be skipped forever. Replaying a cursor across a different scope returns
  a `400` instead of silently doing the wrong thing.
- **`cursor` and `since` are mutually exclusive in effect.** When `cursor` is
  present it sets the window and `since` is ignored.

### `next_cursor` is withheld while `has_more` is true

The watermark covers everything the query matched, not just the page you were
handed. If more results are waiting, `next_cursor` comes back `null` with a
note: page through with `offset` first, then take the cursor from the final
page. Advancing mid-pagination would skip the pages you never read.

### Granularity

Follow data is stored as one snapshot per tracked account per day, so the
watermark is a snapshot boundary. A cursor resumes at the first snapshot after
the newest one your last response consumed. Nothing is delivered twice and
nothing between the two runs is missed.

One exception worth knowing: accounts still establishing a baseline are
answered from a live check against X rather than from a snapshot. Those results
carry `live_refreshed: true` and can appear once more in the following window,
once the poller writes them into a snapshot. Dedupe on `twitter_user_id` if
that matters to you.

### Where it applies

| Endpoint | Watermark |
|----------|-----------|
| `GET /v1/follows/new` | newest follow snapshot consumed |
| `GET /v1/follows/enriched` | newest follow snapshot consumed |
| `GET /v1/feed` | newest follow snapshot consumed |
| `GET /v1/reports` | newest `report_date` returned |

`/v1/trending` and `/v1/convergence` deliberately do **not** take a cursor.
They are ranked aggregations over a window, not record listings: "top 25
trending in the last four hours" is not the continuation of "top 25 in the last
seven days", so a watermark there would quietly degrade the ranking rather than
paginate it. Keep using `since` for those.

---

# Use Cases

> Source: https://www.frontrun.vc/docs/use-cases
> Raw markdown: https://www.frontrun.vc/raw/docs/use-cases.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

---

## Deal sourcing

Track investor accounts and surface convergence - multiple accounts following the same entity independently.

```bash
# Track accounts
curl -X POST .../v1/track -d '{"username": "pmarca"}'
curl -X POST .../v1/track -d '{"username": "naval"}'

# Query convergence
curl ".../v1/convergence?threshold=3&since=7d"
```

Cross-reference convergence results with your existing deal pipeline to find new opportunities.

---

## Custom classification

Build your own taxonomy on top of Frontrun's AI classification:

```bash
# Flag companies in your space
curl -X POST .../v1/classify/rules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Competitors",
    "conditions": {"bio_keywords": ["sales automation", "revenue intelligence"]},
    "actions": {"tags": ["competitor"], "priority": "high"}
  }'

# All future enriched calls auto-apply your rules
curl ".../v1/follows/enriched?since=7d"
```

---

## Slack / Telegram / webhook alerts

Push signals to your team's workflow:

### Slack example

```python
import requests

FRONTRUN = "https://frontrun.vc/v1"
HEADERS = {"X-API-Key": "your_api_key"}
SLACK_WEBHOOK = "https://hooks.slack.com/services/..."

convergence = requests.get(
    f"{FRONTRUN}/convergence",
    headers=HEADERS,
    params={"threshold": 3, "since": "24h"}
).json()

for signal in convergence.get("convergences", []):
    followers = ", ".join(signal["followed_by"])
    requests.post(SLACK_WEBHOOK, json={
        "text": f"*Convergence signal*: {signal['name']} (@{signal['username']})\n"
                f"Followed by: {followers}"
    })
```

### Telegram example

```python
import requests

FRONTRUN = "https://frontrun.vc/v1"
HEADERS = {"X-API-Key": "your_api_key"}
TELEGRAM_BOT_TOKEN = "your_bot_token"
TELEGRAM_CHAT_ID = "your_chat_id"

convergence = requests.get(
    f"{FRONTRUN}/convergence",
    headers=HEADERS,
    params={"threshold": 3, "since": "24h"}
).json()

for signal in convergence.get("convergences", []):
    followers = ", ".join(signal["followed_by"])
    text = (f"*Convergence signal*: {signal['name']} (@{signal['username']})\n"
            f"Followed by: {followers}")
    requests.post(
        f"https://api.telegram.org/bot{TELEGRAM_BOT_TOKEN}/sendMessage",
        json={"chat_id": TELEGRAM_CHAT_ID, "text": text, "parse_mode": "Markdown"}
    )
```

---

## Agent integration

Connect Frontrun to your AI agent via the [MCP server](/docs/integrations/mcp-server) or REST API. Your agent can monitor deal flow, flag opportunities, and surface signals without manual intervention.

```
"What are the top convergence signals this week? Flag anything in AI/ML."
```

See [MCP Server](/docs/integrations/mcp-server) and [Claude Code](/docs/integrations/claude-code) for setup.

---

# GET /v1/follows/new

> Source: https://www.frontrun.vc/docs/endpoints/follows-new
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/follows-new.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Detect new follows across your tracked accounts within a time window.

**Cost:** 16 credits per call

```bash
curl "https://frontrun.vc/v1/follows/new?since=48h" \
  -H "X-API-Key: your_api_key"
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `since` | string (query) | `"24h"` | Time window. Accepts hours (`"24h"`, `"48h"`), days (`"7d"`, `"14d"`, `"30d"`), or ISO date. |
| `username` | string (query) | -- | Filter to a specific tracked account. Omit to check all. |
| `classify` | string (query) | -- | Set to `"true"` to include AI classification. |
| `offset` | integer (query) | `0` | Pagination offset over the grouped results. |
| `limit` | integer (query) | `50` | Maximum grouped tracked-account entries (max 200). |
| `cursor` | string (query) | -- | Opaque watermark from a previous response's `next_cursor`. Resumes exactly where that run stopped, so a retry never double-counts or drops records. Overrides `since`. See [Budgets & Cursors](/docs/reference/budgets-and-cursors). |

## Response

```json
{
  "since": "2026-03-05T04:00:00.000Z",
  "accounts_checked": 3,
  "total_new_follows": 5,
  "has_more": false,
  "next_cursor": "frc1_eyJ2IjoxLCJzIjoiOWY0Yy4uLiIsImQiOiIyMDI2LTA4LTA3In0.Xq9...",
  "cost_credits": 16,
  "balance_credits": 9964,
  "results": [
    {
      "tracked_account": "pmarca",
      "as_of": "2026-04-20T08:00:00Z",
      "new_follows_count": 2,
      "new_follows": [
        {
          "twitter_user_id": "1234567890",
          "username": "newai_startup",
          "name": "NewAI",
          "description": "Building the future of AI infrastructure",
          "verified": true,
          "profile_image_url": "https://pbs.twimg.com/..."
        }
      ]
    }
  ]
}
```

## With classification

```bash
curl ".../v1/follows/new?since=7d&classify=true" \
  -H "X-API-Key: your_api_key"
```

Each new follow includes AI-powered classification:

```json
{
  "twitter_user_id": "1234567890",
  "username": "newai_startup",
  "name": "NewAI",
  "description": "Building the future of AI infrastructure",
  "verified": true,
  "classification": {
    "is_company": true,
    "confidence": "high",
    "sector": "AI/ML",
    "entity_type": "startup"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `classification.is_company` | boolean | Whether this account represents a company/startup. |
| `classification.confidence` | string | `"high"`, `"medium"`, or `"low"`. |
| `classification.sector` | string | Primary sector: `"AI/ML"`, `"Fintech"`, `"Enterprise SaaS"`, `"Crypto/Web3"`, etc. |
| `classification.entity_type` | string | `"startup"`, `"growth_company"`, `"enterprise"`, `"vc_fund"`, `"accelerator"`, `"media"`, `"individual"`, etc. |

## Filter to one account

```bash
curl ".../v1/follows/new?username=pmarca&since=24h"
```

Only returns new follows for `@pmarca`.

---

# Cursor

> Source: https://www.frontrun.vc/docs/integrations/cursor
> Raw markdown: https://www.frontrun.vc/raw/docs/integrations/cursor.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Use Frontrun with Cursor's AI agent mode.

## MCP Server Setup

Add to `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "frontrun": {
      "command": "npx",
      "args": ["frontrun-mcp-server"],
      "env": {
        "FRONTRUN_API_KEY": "your_api_key"
      }
    }
  }
}
```

Restart Cursor. Frontrun tools will be available in agent mode.

## Direct API Usage

Create a `.env` file in your project:

```
FRONTRUN_API_KEY=your_api_key
FRONTRUN_BASE_URL=https://frontrun.vc/v1
```

Then use agent mode to call the API:

```
@agent Call the Frontrun API to get trending companies this week.
Use the base URL and API key from .env.
```

---

# Errors & Status Codes

> Source: https://www.frontrun.vc/docs/reference/errors
> Raw markdown: https://www.frontrun.vc/raw/docs/reference/errors.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Every error response returns a JSON object with an `error` field describing what went wrong.

```json
{
  "error": "Description of the problem"
}
```

## HTTP status codes

| Code | Meaning | When |
|------|---------|------|
| `400` | Bad Request | Missing or invalid parameters |
| `401` | Unauthorized | Missing, invalid, inactive, or expired API key |
| `402` | Payment Required | Insufficient credits |
| `403` | Forbidden | Tier limit reached (e.g., tracked-account quota) |
| `404` | Not Found | Account not tracked, resource doesn't exist |
| `409` | Conflict | Resource already exists (e.g., already tracking account) |
| `429` | Too Many Requests | Rate limit or daily credit cap exceeded |
| `500` | Internal Error | Server-side issue - retry with backoff |
| `503` | Service Unavailable | Upstream (X/Twitter) temporarily unreachable - retry |

## Error responses by type

### 401 - Authentication

```json
{ "error": "Missing X-API-Key header" }
```

```json
{ "error": "Invalid or inactive API key" }
```

```json
{ "error": "API key expired" }
```

Verify your API key is correct, active, and unexpired. Keys can be managed in the [Developer Portal](https://frontrun.vc).

### 402 - Insufficient credits

```json
{
  "error": "Insufficient credits",
  "required_credits": 60,
  "balance_credits": 12,
  "monthly_credits": 0,
  "topup_credits": 12,
  "tier": "pro",
  "top_up": "https://frontrun.vc/api/billing"
}
```

The response tells you exactly how many credits are needed vs. available - `monthly_credits` and `topup_credits` show where your remaining balance comes from. Top up (or enable auto-refill) to continue.

### 429 - Rate limited

Two types of 429 responses:

**Per-minute rate limit:**

```json
{
  "error": "API rate limit exceeded. Please slow down.",
  "retry_after_seconds": 60
}
```

**Daily credit cap reached:**

```json
{
  "error": "Daily credit cap reached",
  "daily_spent_credits": 80000,
  "daily_cap_credits": 80000,
  "tier": "pro",
  "resets_at": "2026-03-12T00:00:00.000Z"
}
```

The daily credit cap (80,000 credits/day on Pro) prevents runaway agent costs. It resets at midnight UTC.

### 400 - Invalid parameters

```json
{ "error": "username is required" }
```

```json
{ "error": "Invalid \"since\" parameter. Use \"24h\", \"7d\", or \"YYYY-MM-DD\"." }
```

```json
{
  "error": "At least one filter required: sector, keyword, or entity_type",
  "example": "/v1/search?sector=AI/ML&entity_type=startup"
}
```

Errors from the agent-oriented parameters carry an `error_code` so they can be
branched on without string matching. See
[Budgets & Cursors](/docs/reference/budgets-and-cursors).

**`max_credits_exceeded`** - the call could cost more than the ceiling you set.
It fails closed: no work ran and nothing was charged. Retry with a smaller
`limit`, fewer `include` sections, or a higher ceiling.

```json
{
  "error": "This call could cost up to 1624 credits, which is above your max_credits of 200. Nothing was charged and no work was done.",
  "error_code": "max_credits_exceeded",
  "max_cost_credits": 1624,
  "max_credits": 200,
  "charged_credits": 0,
  "hint": "Classification is 16 credits per entity returned. Lower limit (currently 100), drop classify=true, or raise max_credits."
}
```

**`invalid_cursor`** - the cursor was modified, or is being replayed against a
different endpoint, API key, or filter set. Cursors are opaque and scoped; mint
a fresh one with `since`.

```json
{
  "error": "This cursor was issued for a different endpoint, API key, or filter set. Cursors are scoped; start a fresh run with since when you change filters.",
  "error_code": "invalid_cursor"
}
```

**`invalid_include`** - an unknown section name was passed to
`GET /v1/company/:handle?include=`. Allowed: `resources`, `founders`, `funding`.

**`batch_too_large`** - more items than the endpoint's batch ceiling. The
response carries `max_batch_size` and `received`.

```json
{
  "error": "Max 50 usernames per request. Split the list and call again.",
  "error_code": "batch_too_large",
  "max_batch_size": 50,
  "received": 150
}
```

### 403 - Tier limit

Returned when an action would exceed your subscription tier's quota. Currently used by `POST /v1/track` when you've reached the tracked-account limit for your tier.

```json
{
  "error": "You have reached your limit of 25 tracked accounts. Please upgrade your plan to track more.",
  "code": "TRACKED_ACCOUNT_LIMIT",
  "tier": "free"
}
```

Upgrade your subscription or untrack existing accounts (`DELETE /v1/track/:username`) before adding new ones.

### 404 - Not found

```json
{ "error": "Not tracking @example. Add with POST /v1/track" }
```

The account must be tracked before you can query follows, convergence, or activity.

### 409 - Already exists

```json
{
  "error": "Already tracking this account",
  "ready": true
}
```

### 503 - Upstream unavailable

Returned by the handle-lookup endpoints (`/v1/preview/:h`, `/v1/company/:h`, `/v1/company/:h/signals`, `/v1/company/:h/resources`, `/v1/company/:h/funding`, `/v1/company/:h/founders`, `/v1/track`) when the upstream X/Twitter data provider is slow or temporarily unreachable.

```json
{
  "error": "Twitter upstream temporarily unavailable. Please retry.",
  "retry_after_seconds": 30
}
```

The response includes a `Retry-After: 30` HTTP header. Back off for the indicated interval and retry - these are transient and usually clear within a minute.

## Retry guidance

| Error | Retry? | Strategy |
|-------|--------|----------|
| `400` | No | Fix the request parameters |
| `401` | No | Check your API key |
| `402` | No | Top up your credits |
| `403` | No | Upgrade plan or delete unused resources |
| `404` | No | Track the account first via `POST /v1/track` |
| `409` | No | Resource already exists - this is a no-op |
| `429` (rate limit) | Yes | Wait `retry_after_seconds`, then retry |
| `429` (credit cap) | Yes | Wait until `resets_at` timestamp |
| `500` | Yes | Exponential backoff: 1s, 2s, 4s, max 3 retries |
| `503` | Yes | Wait `retry_after_seconds` (from body or `Retry-After` header), then retry |

---

# GET /v1/follows/snapshot

> Source: https://www.frontrun.vc/docs/endpoints/follows-snapshot
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/follows-snapshot.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Returns the current follow list for a tracked account.

**Cost:** 4 credits per call

```bash
curl https://frontrun.vc/v1/follows/snapshot/pmarca \
  -H "X-API-Key: your_api_key"
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `username` | string (path) | Yes | X username of the tracked account. |

## Response

```json
{
  "username": "pmarca",
  "as_of": "2026-04-20T08:00:00Z",
  "follow_count": 70,
  "cost_credits": 4,
  "balance_credits": 9908,
  "follows": [
    {
      "twitter_user_id": "1234567890",
      "username": "newai_startup",
      "name": "NewAI",
      "description": "Building the future of AI infrastructure",
      "verified": true,
      "profile_image_url": "https://pbs.twimg.com/..."
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `as_of` | string (ISO 8601) | Timestamp the snapshot reflects. |
| `follow_count` | integer | Total number of accounts being followed. |
| `follows` | array | Array of followed accounts with profile details. |

## Errors

| Status | Description |
|--------|-------------|
| 402 | Insufficient credits |
| 404 | Not tracking this account |

---

# Python

> Source: https://www.frontrun.vc/docs/integrations/python
> Raw markdown: https://www.frontrun.vc/raw/docs/integrations/python.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Use the Frontrun API from Python with `requests` or any HTTP client.

## Installation

```bash
pip install requests
```

## Basic usage

```python
import requests

BASE_URL = "https://frontrun.vc/v1"
HEADERS = {"X-API-Key": "your_api_key"}

def frontrun_get(path, params=None):
    response = requests.get(f"{BASE_URL}{path}", headers=HEADERS, params=params)
    response.raise_for_status()
    return response.json()

def frontrun_post(path, data):
    response = requests.post(f"{BASE_URL}{path}", headers=HEADERS, json=data)
    response.raise_for_status()
    return response.json()
```

## Examples

### Track an account

```python
result = frontrun_post("/track", {"username": "pmarca"})
print(result)
```

### Get new follows

```python
new_follows = frontrun_get("/follows/new", {"since": "48h", "classify": "true"})

for account in new_follows["results"]:
    print(f"\n{account['tracked_account']}:")
    for follow in account["new_follows"]:
        sector = follow.get("classification", {}).get("sector", "Unknown")
        print(f"  @{follow['username']} ({sector})")
```

### Check convergence

```python
convergence = frontrun_get("/convergence", {"threshold": 3, "since": "7d"})

for signal in convergence["convergences"]:
    followers = ", ".join(signal["followed_by"])
    print(f"{signal['name']} - followed by {followers}")
```

### Get trending

```python
trending = frontrun_get("/trending", {"since": "7d", "classify": "true", "limit": 10})

for company in trending["trending"]:
    print(f"#{company['follower_count']} {company['name']} @{company['username']}")
```

### Account activity

```python
activity = frontrun_get("/vc/pmarca/activity", {"since": "30d"})

print(f"Follows/week: {activity['follows_per_week']}")
print(f"Sectors: {activity['sector_breakdown']}")
```

### Search

```python
results = frontrun_get("/search", {"sector": "AI/ML", "entity_type": "startup"})

for company in results["results"]:
    print(f"@{company['username']} - {company['description']}")
```

---

# Rate Limits

> Source: https://www.frontrun.vc/docs/reference/rate-limits
> Raw markdown: https://www.frontrun.vc/raw/docs/reference/rate-limits.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

All API endpoints are rate-limited per API key. Two independent limits apply: a **request-count** rate limit (DoS guardrail) and a **daily credit cap** (spend ceiling).

## Request-count limits

| Tier | Requests/min | Requests/day |
|------|-------------|-------------|
| Free | 60 | 10,000 |
| Pro | 300 | 500,000 |
| Enterprise | Custom | Custom |

## Daily credit cap

| Tier | Daily cap |
|------|-----------|
| Free | 14,000 credits/day |
| Pro | 80,000 credits/day |
| Enterprise | None |

Grandfathered Starter keys keep their existing limits (120 requests/min, 50,000 requests/day, 20,000 credits/day).

The daily credit cap prevents runaway agent costs. When the cap is reached, the API returns `429`:

```json
{
  "error": "Daily credit cap reached",
  "daily_spent_credits": 80000,
  "daily_cap_credits": 80000,
  "tier": "pro",
  "resets_at": "2026-04-22T00:00:00.000Z"
}
```

The cap resets at midnight UTC.

## Rate limit headers

Every API response includes standard rate limit headers:

| Header | Description |
|--------|-------------|
| `RateLimit-Limit` | Maximum requests per window |
| `RateLimit-Remaining` | Requests remaining in current window |
| `RateLimit-Reset` | Unix timestamp when the window resets |

## Exceeding the limit

If you exceed the per-minute rate limit:

```json
{
  "error": "API rate limit exceeded. Please slow down.",
  "retry_after_seconds": 60
}
```

If you exceed the per-day limit:

```json
{
  "error": "Daily API limit reached. Upgrade your plan for higher limits.",
  "retry_after_seconds": 3600
}
```

Back off and retry after the `retry_after_seconds` interval. See [Errors](/docs/reference/errors) for full retry guidance.

## Best practices

- **Cache responses** - Follow data updates periodically, not in real time. Caching responses for 30-60 minutes is usually sufficient.
- **Use time windows** - Query with `?since=24h` instead of polling every minute. See [Parameters](/docs/reference/parameters) for supported formats.
- **Batch where possible** - A single `GET /v1/follows/new` returns new follows across all tracked accounts. No need to query per-account.
- **Check headers first** - Read `RateLimit-Remaining` before making requests to avoid hitting 429s.
- **Use webhooks** - For agent workflows, subscribe to push notifications instead of polling.

---

# GET /v1/follows/enriched

> Source: https://www.frontrun.vc/docs/endpoints/enriched
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/enriched.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

New follows with full enrichment: AI classification + your custom rules + your custom tags, all merged into each result.

This is the most powerful endpoint for building custom workflows.

**Cost:** 16 credits per call

```bash
curl "https://frontrun.vc/v1/follows/enriched?since=48h" \
  -H "X-API-Key: your_api_key"
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `since` | string (query) | `"24h"` | Time window: `"24h"`, `"48h"`, `"7d"`, etc. |
| `username` | string (query) | -- | Filter to a specific tracked account. |
| `sector` / `keyword` / `entity_type` / `tag` | string (query) | -- | Filter the returned follows. |
| `cursor` | string (query) | -- | Opaque watermark from a previous response's `next_cursor`. Resumes exactly where that run stopped, so a retry never double-counts or drops records. Overrides `since`. See [Budgets & Cursors](/docs/reference/budgets-and-cursors). |

## Response

```json
{
  "since": "2026-03-07T04:00:00.000Z",
  "accounts_checked": 50,
  "total_new_follows": 12,
  "has_more": false,
  "next_cursor": "frc1_eyJ2IjoxLCJzIjoiMWEyYi4uLiIsImQiOiIyMDI2LTA4LTA3In0.Kd3...",
  "cost_credits": 16,
  "balance_credits": 9948,
  "results": [
    {
      "tracked_account": "pmarca",
      "as_of": "2026-04-20T08:00:00Z",
      "new_follows_count": 3,
      "new_follows": [
        {
          "twitter_user_id": "1111111111",
          "username": "stealth_ai_co",
          "name": "StealthAI",
          "description": "Automating enterprise workflows with LLMs",
          "verified": true,
          "classification": {
            "is_company": true,
            "confidence": "high",
            "sector": "AI/ML",
            "entity_type": "startup"
          },
          "custom": {
            "tags": ["thesis-match", "watchlist"],
            "sector": "AI Infrastructure",
            "priority": "high",
            "matched_rule": "AI Infra"
          }
        }
      ]
    }
  ]
}
```

## How custom data merges

1. **AI classification** is always included
2. **Custom tags** (from `POST /v1/tags`) are merged - manual overrides take priority
3. **Classification rules** (from `POST /v1/classify/rules`) are evaluated against each entity
4. If both a manual tag and a rule match, they're merged (tags combined, manual sector takes priority)

---

# JavaScript

> Source: https://www.frontrun.vc/docs/integrations/javascript
> Raw markdown: https://www.frontrun.vc/raw/docs/integrations/javascript.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Use the Frontrun API from JavaScript/TypeScript with `fetch`.

## Client wrapper

```javascript
const BASE_URL = 'https://frontrun.vc/v1';
const API_KEY = process.env.FRONTRUN_API_KEY;

async function frontrun(method, path, body = null) {
  const options = {
    method,
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json',
    },
  };
  if (body) options.body = JSON.stringify(body);

  const response = await fetch(`${BASE_URL}${path}`, options);
  if (!response.ok) {
    const error = await response.json().catch(() => ({}));
    throw new Error(error.error || `HTTP ${response.status}`);
  }
  return response.json();
}
```

## Examples

### Track an account

```javascript
const result = await frontrun('POST', '/track', { username: 'pmarca' });
console.log(result);
```

### Get new follows

```javascript
const data = await frontrun('GET', '/follows/new?since=48h&classify=true');

for (const account of data.results) {
  console.log(`\n${account.tracked_account}:`);
  for (const follow of account.new_follows) {
    const sector = follow.classification?.sector || 'Unknown';
    console.log(`  @${follow.username} (${sector})`);
  }
}
```

### Check convergence

```javascript
const data = await frontrun('GET', '/convergence?threshold=3&since=7d');

for (const signal of data.convergences) {
  console.log(`${signal.name} - followed by ${signal.followed_by.join(', ')}`);
}
```

### Get trending

```javascript
const data = await frontrun('GET', '/trending?since=7d&classify=true&limit=10');

for (const company of data.trending) {
  console.log(`#${company.follower_count} ${company.name} @${company.username}`);
}
```

### Account activity

```javascript
const activity = await frontrun('GET', '/vc/pmarca/activity?since=30d');
console.log(`Follows/week: ${activity.follows_per_week}`);
console.log('Sectors:', activity.sector_breakdown);
```

### Search

```javascript
const results = await frontrun('GET', '/search?sector=AI/ML&entity_type=startup');

for (const company of results.results) {
  console.log(`@${company.username} - ${company.description}`);
}
```

---

# Security

> Source: https://www.frontrun.vc/docs/reference/security
> Raw markdown: https://www.frontrun.vc/raw/docs/reference/security.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

## API key management

### Storage

- **Never commit API keys to version control.** Add `.mcp.json` and any config files containing keys to your `.gitignore`.
- Store keys in environment variables or a secrets manager (e.g., 1Password, Doppler, AWS Secrets Manager).
- Use separate keys for development, staging, and production. Each key has independent balance and usage tracking.

### Rotation

If a key is compromised:

1. Create a new key in the [Developer Portal](https://frontrun.vc)
2. Update your environment variables / config
3. Revoke the old key

Keys can be created, toggled (enabled/disabled), and revoked from the Developer Portal or via the key management API.

### Least privilege

- Create purpose-specific keys: one for your agent, one for your dashboard, one for CI/CD
- Monitor usage per key via `GET /v1/status` or the Developer Portal usage dashboard
- Disable keys you're not actively using

## Spend controls

### Daily credit cap

Every API key has a daily credit cap (**80,000 credits/day** on Pro, 14,000 on the free tier). If your key hits the cap, the API returns `429`. This prevents runaway agent loops from draining your balance. The cap resets at midnight UTC.

### Balance visibility

Every charged response includes your remaining balance:

```json
{
  "cost_credits": 16,
  "balance_credits": 984
}
```

Use `GET /v1/status` (free) to check balance and daily spend at any time.

## MCP server security

### Local stdio transport

The Frontrun MCP server runs as a **local subprocess** via stdio transport. This means:

- No network ports are opened
- No external attack surface
- The API key stays in your local environment
- Communication happens over stdin/stdout between your MCP client (Claude Desktop, Claude Code, Cursor) and the server process

### Key handling for MCP

Configure your API key via environment variable, not hardcoded in config:

```json
{
  "frontrun": {
    "command": "npx",
    "args": ["frontrun-mcp-server"],
    "env": {
      "FRONTRUN_API_KEY": "your_key_here"
    }
  }
}
```

For Claude Desktop on macOS, the config file is at:
`~/Library/Application Support/Claude/claude_desktop_config.json`

Ensure this file is not synced to cloud storage or version control.

### Treating MCP tool outputs

When using Frontrun through MCP in AI workflows:

- **Graph data** (follows, convergence, trending) is deterministic and can be trusted as factual
- **Classifications** (sector, entity_type, tags) are AI-generated and probabilistic - verify high-stakes decisions against primary sources
- **All data originates from public social graph information** - no private or privileged data is accessed

## Infrastructure

- API traffic is proxied through `frontrun.vc/v1` - your requests never hit infrastructure URLs directly
- All API communication is over HTTPS (TLS 1.2+)
- API keys are stored hashed in the database - only the last 8 characters are visible in the Developer Portal
- Usage is logged per-key for billing and audit purposes
- No request bodies or response data are logged - only metadata (endpoint, cost, status code, timestamp)

---

# GET /v1/convergence

> Source: https://www.frontrun.vc/docs/endpoints/convergence
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/convergence.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Detect entities followed by multiple tracked accounts independently within a time window.

**Cost:** 60 credits per call

```bash
curl "https://frontrun.vc/v1/convergence?threshold=2&since=7d" \
  -H "X-API-Key: your_api_key"
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `threshold` | integer (query) | `2` | Minimum tracked accounts that must have followed the same entity. |
| `since` | string (query) | `"7d"` | Time window. Accepts hours (`"48h"`), days (`"7d"`, `"14d"`), or ISO date. |

### Threshold guide

| Threshold | Signal strength | Typical use |
|-----------|----------------|-------------|
| 2 | Moderate | Broad scanning |
| 3 | Strong | High-confidence signals |
| 4+ | Very strong | Filtered to highest conviction |

## Response

```json
{
  "threshold": 2,
  "since": "2026-02-28T00:00:00.000Z",
  "total": 3,
  "cost_credits": 60,
  "balance_credits": 9600,
  "convergences": [
    {
      "twitter_user_id": "1111111111",
      "username": "stealth_ai_co",
      "name": "StealthAI",
      "description": "Automating enterprise workflows with LLMs",
      "followed_by": ["pmarca", "naval", "paulg"]
    },
    {
      "twitter_user_id": "2222222222",
      "username": "dev_infra_xyz",
      "name": "DevInfra",
      "description": "Next-gen developer infrastructure",
      "followed_by": ["pmarca", "naval"]
    }
  ]
}
```

Results are sorted by convergence strength (most followers first).

| Field | Type | Description |
|-------|------|-------------|
| `convergences[].followed_by` | array | Tracked account usernames that recently followed this entity. Array length = convergence score. |

## Example

```python
import requests

response = requests.get(
    "https://frontrun.vc/v1/convergence",
    headers={"X-API-Key": "your_api_key"},
    params={"threshold": 3, "since": "7d"}
)

for signal in response.json()["convergences"]:
    print(f"{signal['name']} - followed by {', '.join(signal['followed_by'])}")
```

---

# GET /v1/trending

> Source: https://www.frontrun.vc/docs/endpoints/trending
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/trending.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Entities ranked by the number of tracked accounts that recently followed them.

**Cost:** 24 credits per call (+16 credits/entity with `classify=true`)

```bash
curl "https://frontrun.vc/v1/trending?since=7d&classify=true" \
  -H "X-API-Key: your_api_key"
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `since` | string (query) | `"7d"` | Time window. Accepts `"24h"`, `"48h"`, `"7d"`, `"14d"`, `"30d"`, or ISO date. |
| `limit` | integer (query) | `25` | Maximum results (max 100). |
| `offset` | integer (query) | `0` | Pagination offset. |
| `classify` | string (query) | -- | Set to `"true"` to include AI classification. |
| `max_credits` | integer (query) | -- | Cap what this call may cost. With `classify=true` the cost scales with `limit`, so `limit=100` can reach 1,624 credits. Fails closed: over the ceiling, nothing runs and nothing is charged. See [Budgets & Cursors](/docs/reference/budgets-and-cursors). |

`/v1/trending` does not take a `cursor`. It is a ranked aggregation over a
window, not a record listing, so narrowing the window changes the answer rather
than continuing it. Use `since`.

## Response

```json
{
  "since": "2026-02-28T00:00:00.000Z",
  "accounts_scanned": 50,
  "total": 25,
  "cost_credits": 24,
  "max_cost_credits": 424,
  "balance_credits": 9836,
  "trending": [
    {
      "twitter_user_id": "1111111111",
      "username": "stealth_ai_co",
      "name": "StealthAI",
      "description": "Automating enterprise workflows with LLMs",
      "verified": true,
      "followed_by": ["pmarca", "naval", "paulg", "sequoia"],
      "follower_count": 4,
      "classification": {
        "is_company": true,
        "confidence": "high",
        "sector": "AI/ML",
        "entity_type": "startup"
      }
    }
  ]
}
```

---

# GET /v1/search

> Source: https://www.frontrun.vc/docs/endpoints/search
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/search.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Search across entities followed by your tracked accounts. Filter by sector, keyword, or entity type.

**Cost:** 4 credits per call

```bash
curl "https://frontrun.vc/v1/search?sector=AI/ML&entity_type=startup" \
  -H "X-API-Key: your_api_key"
```

## Parameters

At least one filter is required.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `sector` | string (query) | -- | Filter by sector. Case-insensitive partial match. Values: `"AI/ML"`, `"Fintech"`, `"Enterprise SaaS"`, `"Crypto/Web3"`, `"Healthcare"`, `"Climate"`, `"Developer Tools"`, `"Consumer"`, `"Cybersecurity"` |
| `entity_type` | string (query) | -- | Filter by entity type. Values: `"startup"`, `"growth_company"`, `"enterprise"`, `"vc_fund"`, `"accelerator"`, `"media"`, `"individual"` |
| `keyword` | string (query) | -- | Free-text search across username, sector, and bio. |
| `limit` | integer (query) | `50` | Maximum results (max 200). |
| `scope` | string (query) | -- | Set to `"catalog"` to search the full company catalog instead of only your own follow graph. |
| `include_founders` | string (query) | -- | `scope=catalog` only. Set to `"true"` to join cached founders onto each result. Adds **100 credits per company that resolves**; companies with no cached founders are free. |
| `max_credits` | integer (query) | -- | Cap what this call may cost. With `include_founders=true` and `limit=200` the ceiling is 20,004 credits, so this is the parameter to set. Fails closed: over the ceiling, the founder join never runs and nothing is charged. See [Budgets & Cursors](/docs/reference/budgets-and-cursors). |

## Response

```json
{
  "filters": {
    "sector": "AI/ML",
    "keyword": null,
    "entity_type": "startup"
  },
  "total": 23,
  "cost_credits": 4,
  "balance_credits": 9912,
  "results": [
    {
      "twitter_user_id": "1234567890",
      "username": "newai_startup",
      "description": "Building the future of AI infrastructure",
      "classification": {
        "is_company": true,
        "confidence": "high",
        "sector": "AI/ML",
        "entity_type": "startup"
      }
    }
  ]
}
```

---

# GET /v1/search/thesis

> Source: https://www.frontrun.vc/docs/endpoints/thesis-search
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/thesis-search.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Semantic search over **your database** - every company the investors you track have surfaced. Describe an investment thesis in plain text and the API matches companies by **meaning**, not exact words. A thesis about "information markets" surfaces companies describing themselves as prediction protocols, forecasting tools, or event contracts, even if they never use your phrasing.

**Cost:** 40 credits per call

```bash
curl -G "https://frontrun.vc/v1/search/thesis" \
  --data-urlencode "q=information markets - platforms where people trade on what they know" \
  -H "X-API-Key: your_api_key"
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `q` | string (query) | **required** | Your thesis in plain text (min 10 characters). A sentence or short paragraph works best - more specific theses return sharper matches. |
| `limit` | integer (query) | `25` | Maximum results (max 50). |

## Response

Results are ranked by `similarity` (0–1, cosine similarity between your thesis and the company's description). Signal fields - `followers_count`, `first_flagged_at` (when tracked VCs first surfaced it), and `convergence_count` (how many tracked VCs follow it) - help you prioritize which matches to dig into.

```json
{
  "query": "information markets - platforms where people trade on what they know",
  "returned": 25,
  "cost_credits": 40,
  "balance_credits": 9860,
  "results": [
    {
      "username": "example_protocol",
      "name": "Example Protocol",
      "description": "Prediction markets for real-world events",
      "website": "https://example.xyz",
      "sector": "Crypto/Web3",
      "entity_type": "startup",
      "followers_count": 842,
      "first_flagged_at": "2026-06-12T08:30:00Z",
      "convergence_count": 3,
      "similarity": 0.61
    }
  ]
}
```

## Tips

- Write the thesis the way you'd explain it to a partner, not as keywords. "Tools that let anyone underwrite risk on real-world outcomes" beats "prediction market".
- Combine with [`GET /v1/company/:handle`](/docs/endpoints/company) to pull a full overview of any match, or [`GET /v1/company/:handle/signals`](/docs/endpoints/company-signals) to see who's following it.
- Similarity above ~0.5 is a strong conceptual match; 0.3–0.5 is adjacent territory worth scanning.

---

# GET /v1/reports

> Source: https://www.frontrun.vc/docs/endpoints/reports
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/reports.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Historical daily report data. Returns your saved discovery reports - the companies flagged for you each day - for a date range.

**Cost:** 4 credits per call

```bash
curl "https://frontrun.vc/v1/reports?since=7d" \
  -H "X-API-Key: your_api_key"
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `since` | string (query) | `"7d"` | How far back to fetch. Values: `"7d"`, `"14d"`, or a start date `"YYYY-MM-DD"`. Ignored if `date` is set. |
| `date` | string (query) | -- | Fetch a single report for this date (`YYYY-MM-DD`). |
| `sector` | string (query) | -- | Filter companies by sector, description, or name. Case-insensitive partial match. |
| `limit` | integer (query) | `7` | Maximum reports returned (max 30). |
| `cursor` | string (query) | -- | Opaque watermark from a previous response's `next_cursor`. Walks forward from the day after the newest report you already received. Cannot be combined with `date`. See [Budgets & Cursors](/docs/reference/budgets-and-cursors). |

## Response

```json
{
  "reports": [
    {
      "date": "2026-07-07",
      "total_companies": 2,
      "companies": [
        {
          "handle": "stealth_ai_co",
          "name": "StealthAI",
          "sector": "AI/ML",
          "description": "Automating enterprise workflows with LLMs",
          "confidence": "high",
          "tracked_by": ["pmarca", "naval"],
          "website": "https://stealthai.com",
          "profile_image": "https://pbs.twimg.com/profile_images/..."
        }
      ]
    }
  ],
  "total_reports": 1,
  "total_companies": 2,
  "filter": null,
  "cost_credits": 4
}
```

| Field | Type | Description |
|-------|------|-------------|
| `reports` | array | One entry per daily report, newest first. |
| `reports[].companies` | array | Companies discovered in that report. |
| `tracked_by` | string[] | Your tracked accounts that followed the company. |
| `total_reports` | integer | Number of reports returned. |
| `total_companies` | integer | Companies across all returned reports. |
| `filter` | string | The `sector` filter applied, or `null`. |

---

# POST /v1/classify

> Source: https://www.frontrun.vc/docs/endpoints/classify
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/classify.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Classify specific entities on demand - AI classification with your [classification rules](/docs/endpoints/classify-rules) and [custom tags](/docs/endpoints/tags) merged in.

**Cost:** 16 credits per entity

```bash
curl -X POST https://frontrun.vc/v1/classify \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"usernames": ["stealth_ai_co", "dev_infra_xyz"]}'
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `usernames` | string[] (body) | -- | X usernames to classify. **Required.** Max 100 per request. Cost is 16 credits per entity found. |
| `twitter_user_ids` | string[] (body) | -- | Alternative to `usernames`. Same 100-entity ceiling. |
| `max_credits` | integer (body) | -- | Cap what this call may cost. 100 entities is up to 1,600 credits. Fails closed: over the ceiling, nothing runs and nothing is charged. See [Budgets & Cursors](/docs/reference/budgets-and-cursors). |

## Response

```json
{
  "total": 2,
  "cost_credits": 32,
  "max_cost_credits": 32,
  "balance_credits": 9880,
  "results": [
    {
      "twitter_user_id": "1111111111",
      "username": "stealth_ai_co",
      "description": "Automating enterprise workflows with LLMs",
      "classification": {
        "is_company": true,
        "confidence": "high",
        "sector": "AI/ML",
        "entity_type": "startup",
        "sub_category": "Enterprise AI",
        "tags": []
      },
      "custom": {
        "tags": ["portfolio", "series-a"],
        "sector": "AI Infrastructure",
        "notes": "Series A target Q2."
      }
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `classification` | object | Frontrun's AI classification. |
| `custom` | object | Your own tags, sector overrides, and notes for the entity - from your [rules](/docs/endpoints/classify-rules) and [tags](/docs/endpoints/tags). |

## Build your own classification layer

- **[Classification Rules](/docs/endpoints/classify-rules)** - auto-tag entities matching bio keywords, username patterns, or sectors. Free.
- **[Custom Tags](/docs/endpoints/tags)** - manually tag individual entities with sectors, types, and notes. Free.

---

# Classification Rules

> Source: https://www.frontrun.vc/docs/endpoints/classify-rules
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/classify-rules.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Rules auto-classify entities based on pattern matching. When you query `/follows/enriched` or `/discover`, matching entities get your custom tags, sectors, and types applied automatically. All rule operations are **free**.

Limit: 100 rules per account (500 on Enterprise). A `429` is returned at the cap.

---

## Create a Rule

`POST /v1/classify/rules` - **Free**

```bash
curl -X POST https://frontrun.vc/v1/classify/rules \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DeFi Protocols",
    "conditions": {
      "bio_keywords": ["defi", "lending protocol", "liquidity"],
      "must_be_company": true
    },
    "actions": {
      "custom_sector": "DeFi",
      "tags": ["watchlist", "defi-protocol"],
      "priority": "high"
    }
  }'
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `name` | string (body) | -- | Rule name. **Required.** |
| `conditions` | object (body) | -- | When the rule matches. **Required.** See below. |
| `actions` | object (body) | -- | What to apply on match. **Required.** See below. |

#### Conditions

All conditions must match (AND logic). Within `bio_keywords`, any keyword triggers a match (OR logic). Unknown keys are rejected with a `400`.

| Field | Type | Description |
|-------|------|-------------|
| `bio_keywords` | string[] | Match if bio contains any of these keywords (case-insensitive) |
| `username_pattern` | string | Regex pattern to match against username |
| `sector_contains` | string | Match if AI-classified sector contains this string |
| `must_be_company` | boolean | `true` = only companies, `false` = only individuals |

#### Actions

| Field | Type | Description |
|-------|------|-------------|
| `custom_sector` | string | Override sector classification |
| `custom_entity_type` | string | Override entity type |
| `tags` | string[] | Tags to apply (e.g., `["watchlist", "competitor"]`) |
| `priority` | string | `"high"`, `"medium"`, or `"low"` |

### Response

Returns `201` with the created rule:

```json
{
  "id": "b0f6f6a2-4a3e-4a1e-9c1d-2f4e8a7b6c5d",
  "name": "DeFi Protocols",
  "conditions": {
    "bio_keywords": ["defi", "lending protocol", "liquidity"],
    "must_be_company": true
  },
  "actions": {
    "custom_sector": "DeFi",
    "tags": ["watchlist", "defi-protocol"],
    "priority": "high"
  },
  "active": true,
  "created_at": "2026-07-08T14:00:00.000Z"
}
```

---

## List Rules

`GET /v1/classify/rules` - **Free**

```bash
curl https://frontrun.vc/v1/classify/rules \
  -H "X-API-Key: your_api_key"
```

```json
{
  "count": 1,
  "rules": [
    {
      "id": "b0f6f6a2-4a3e-4a1e-9c1d-2f4e8a7b6c5d",
      "name": "DeFi Protocols",
      "conditions": { "bio_keywords": ["defi"], "must_be_company": true },
      "actions": { "custom_sector": "DeFi", "tags": ["watchlist"] },
      "active": true,
      "created_at": "2026-07-08T14:00:00.000Z"
    }
  ]
}
```

Only active rules are returned, newest first.

---

## Update a Rule

`PUT /v1/classify/rules/:id` - **Free**

Partial update - send only the fields you want to change. Set `"active": false` to disable a rule without deleting it.

```bash
curl -X PUT https://frontrun.vc/v1/classify/rules/b0f6f6a2-4a3e-4a1e-9c1d-2f4e8a7b6c5d \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"active": false}'
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string (body) | New rule name |
| `conditions` | object (body) | Replacement conditions object |
| `actions` | object (body) | Replacement actions object |
| `active` | boolean (body) | Enable/disable the rule |

Returns the updated rule object, or `404` if the rule doesn't exist.

---

## Delete a Rule

`DELETE /v1/classify/rules/:id` - **Free**

```bash
curl -X DELETE https://frontrun.vc/v1/classify/rules/b0f6f6a2-4a3e-4a1e-9c1d-2f4e8a7b6c5d \
  -H "X-API-Key: your_api_key"
```

```json
{
  "deleted": true,
  "id": "b0f6f6a2-4a3e-4a1e-9c1d-2f4e8a7b6c5d"
}
```

---

# Custom Tags

> Source: https://www.frontrun.vc/docs/endpoints/tags
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/tags.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Manually tag individual entities with your own tags, sectors, types, and notes. Tags are merged into `/follows/enriched` and `/classify` responses. All tag operations are **free**.

Limit: 10,000 tagged entities per account (100,000 on Enterprise). A `429` is returned at the cap.

---

## Add/Update Tags

`POST /v1/tags` - **Free**

Upserts by entity - posting again for the same entity updates the existing tag record.

```bash
curl -X POST https://frontrun.vc/v1/tags \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "stealth_ai_co",
    "tags": ["portfolio", "series-a"],
    "custom_sector": "AI Infrastructure",
    "notes": "Series A target Q2."
  }'
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `twitter_user_id` | string (body) | -- | Entity's X user ID. **Required unless `username` is set.** |
| `username` | string (body) | -- | Entity's X username. **Required unless `twitter_user_id` is set.** Must already exist in Frontrun's classification cache - a `404` is returned otherwise. |
| `tags` | string[] (body) | -- | Custom tags |
| `custom_sector` | string (body) | -- | Sector override |
| `custom_entity_type` | string (body) | -- | Entity type override |
| `notes` | string (body) | -- | Free-text notes |

### Response

Returns `201` with the tag record:

```json
{
  "id": "c2d8e1f0-7b6a-4c5d-8e9f-1a2b3c4d5e6f",
  "twitter_user_id": "1234567890",
  "username": "stealth_ai_co",
  "tags": ["portfolio", "series-a"],
  "custom_sector": "AI Infrastructure",
  "custom_entity_type": null,
  "notes": "Series A target Q2.",
  "updated_at": "2026-07-08T14:00:00.000Z"
}
```

---

## List Tags

`GET /v1/tags` - **Free**

```bash
# All tagged entities
curl "https://frontrun.vc/v1/tags" \
  -H "X-API-Key: your_api_key"

# Filter by tag
curl "https://frontrun.vc/v1/tags?tag=portfolio" \
  -H "X-API-Key: your_api_key"

# Filter by custom sector
curl "https://frontrun.vc/v1/tags?sector=DeFi" \
  -H "X-API-Key: your_api_key"
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `tag` | string (query) | -- | Only entities carrying this exact tag. |
| `sector` | string (query) | -- | Only entities whose `custom_sector` matches. Case-insensitive partial match. |

### Response

```json
{
  "count": 1,
  "tags": [
    {
      "id": "c2d8e1f0-7b6a-4c5d-8e9f-1a2b3c4d5e6f",
      "twitter_user_id": "1234567890",
      "username": "stealth_ai_co",
      "tags": ["portfolio", "series-a"],
      "custom_sector": "AI Infrastructure",
      "custom_entity_type": null,
      "notes": "Series A target Q2.",
      "updated_at": "2026-07-08T14:00:00.000Z"
    }
  ]
}
```

Sorted by most recently updated.

---

## Remove Tags

`DELETE /v1/tags/:twitter_user_id` - **Free**

Removes all custom tags, overrides, and notes for the entity.

```bash
curl -X DELETE https://frontrun.vc/v1/tags/1234567890 \
  -H "X-API-Key: your_api_key"
```

```json
{
  "deleted": true,
  "twitter_user_id": "1234567890"
}
```

Returns `404` if the entity has no tags.

---

# GET /v1/company/:handle

> Source: https://www.frontrun.vc/docs/endpoints/company
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/company.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Synthesized company overview from multiple sources. Returns profile data, sector classification, entity type, website summary, and recent activity.

**Cost:** 60 credits per call

```bash
curl "https://frontrun.vc/v1/company/stealth_ai_co" \
  -H "X-API-Key: your_api_key"
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `handle` | string (path) | -- | X username of the company. **Required.** |
| `include` | string (query) | -- | Comma-separated sections to bundle into this one call: `resources`, `founders`, `funding`. See below. |
| `max_credits` | integer (query) | -- | Cap what this call may cost. Checked against the worst case for the sections you asked for, before any work runs. See [Budgets & Cursors](/docs/reference/budgets-and-cursors). |

## Composite lookups with `include`

A full picture of one company used to be four calls at four prices. `include`
folds them into one round trip.

```bash
curl "https://frontrun.vc/v1/company/stealth_ai_co?include=resources,founders,funding&max_credits=300" \
  -H "X-API-Key: your_api_key"
```

Each section is priced at its standalone rate. Bundling is a latency win, not a
discount and not a surcharge.

| Section | Cost | Free when |
|---------|------|-----------|
| overview (always) | 60 credits | never |
| `resources` | 60 credits | never - always returns at least the X profile link |
| `founders` | 100 credits | **0 credits when no founders are found** |
| `funding` | 60 credits | **0 credits when no funding resolves** |

The zero-cost-on-empty behavior of `/founders` and `/funding` is preserved
exactly inside the composite. `cost_breakdown_credits` shows where the credits
actually went, and everything is charged in a single deduction, so a composite
never leaves you half-billed for a response you did not receive.

`include=founders` uses the same cached founder join as
`GET /v1/search?include_founders=true`: fast, batched, with a background
resolve kicked off on a cold miss. It does **not** perform the up-to-28-second
live discovery wait that `GET /v1/company/:handle/founders` does, so a cold
company returns `resolution_status: "resolving"` in this section. Call the
dedicated endpoint when you need the blocking resolve.

An unknown section name returns `400` with `error_code: "invalid_include"`.

### Composite response

```json
{
  "company": { "handle": "stealth_ai_co", "name": "StealthAI", "...": "..." },
  "resources": { "website": "https://stealthai.com", "twitter": "https://x.com/stealth_ai_co", "github": "https://github.com/stealthai" },
  "founders": { "company": "stealth_ai_co", "total_found": 2, "founders": [] },
  "funding": { "schema_version": "2026-07-29", "found": true, "latest_round": {}, "cost_credits": 60 },
  "included": ["resources", "founders", "funding"],
  "cost_breakdown_credits": {
    "company_overview": 60,
    "resources": 60,
    "founders": 100,
    "funding": 60
  },
  "cost_credits": 280,
  "max_cost_credits": 280,
  "balance_credits": 9260
}
```

The `funding` section is the same schema `GET /v1/company/:handle/funding`
returns, so one parser works either way. Its nested `cost_credits` is that
section's cost; the top-level `cost_credits` is the whole call.

## Response

```json
{
  "company": {
    "handle": "stealth_ai_co",
    "name": "StealthAI",
    "bio": "Automating enterprise workflows with LLMs",
    "website": "https://stealthai.com",
    "sector": "AI/ML",
    "entity_type": "startup",
    "about": "StealthAI builds AI agents that automate back-office workflows for mid-market enterprises. Founded in 2025, the company has processed over 2M tasks for 50+ customers.",
    "website_summary": "Product page describes an AI workflow automation platform with integrations for Salesforce, HubSpot, and Slack. Pricing starts at $500/mo.",
    "recent_activity": [
      {
        "type": "new_vc_follower",
        "date": "2026-03-25",
        "detail": "Followed by a]16z"
      },
      {
        "type": "profile_update",
        "date": "2026-03-20",
        "detail": "Bio updated to mention Series A"
      }
    ]
  },
  "cost_credits": 60,
  "balance_credits": 9540
}
```

| Field | Type | Description |
|-------|------|-------------|
| `entity_type` | string | One of `"startup"`, `"growth_company"`, `"enterprise"`, `"vc_fund"`, `"accelerator"`, `"media"`, `"individual"`. |
| `about` | string | AI-synthesized summary from bio, website, and social signals. |
| `recent_activity` | array | Notable recent events related to this company. |

---

# GET /v1/company/:handle/founders

> Source: https://www.frontrun.vc/docs/endpoints/company-founders
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/company-founders.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Founder intelligence for a company. Identifies founders via social graph analysis and enriches with LinkedIn data.

**Cost:** 100 credits per call

```bash
curl "https://frontrun.vc/v1/company/stealth_ai_co/founders" \
  -H "X-API-Key: your_api_key"
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `handle` | string (path) | -- | X username of the company. **Required.** |

## Response

```json
{
  "company": "stealth_ai_co",
  "company_name": "Stealth AI",
  "founders": [
    {
      "handle": "janesmith_ai",
      "name": "Jane Smith",
      "role": "CEO & Co-Founder",
      "bio": "Building Stealth AI. Previously ML lead at Google Brain. Stanford PhD.",
      "previous_companies": ["Google", "DeepMind"],
      "linkedin_url": "https://www.linkedin.com/in/janesmithai",
      "linkedin_headline": "Co-founder & CEO at Stealth AI",
      "confidence": "high",
      "discovered_via": "frontrun_v2",
      "evidence": []
    },
    {
      "handle": "bob_eng",
      "name": "Bob Chen",
      "role": "CTO",
      "bio": "Infrastructure. Ex-Stripe.",
      "previous_companies": ["Stripe", "Square"],
      "linkedin_url": null,
      "confidence": "medium",
      "discovered_via": "company_following",
      "evidence": []
    }
  ],
  "sources_used": ["pipeline_cache", "linkedin"],
  "total_found": 2,
  "cost_credits": 100,
  "balance_credits": 9440
}
```

| Field | Type | Description |
|-------|------|-------------|
| `confidence` | string | How sure we are that this person is a founder of the company. `high` when the match is verified (evidence-gated resolver or an explicit founder link), `medium` otherwise. Not a numeric score. |
| `discovered_via` | string | Which discovery layer produced this founder, for example `frontrun_v2`, `pipeline`, `company_following`, `tweet_search`. |
| `linkedin_url` | string | LinkedIn profile URL when a match was found, otherwise `null`. |
| `linkedin_headline` | string | LinkedIn headline. Only present when LinkedIn enrichment ran and matched. |
| `previous_companies` | array | Notable previous employers identified from LinkedIn and bio. Empty when no work history was resolved. |
| `sources_used` | array | The discovery layers that contributed to this response. |

Founders are returned sorted by `confidence` (high first). When no founders are found, the call is free: you get `"founders": []`, `"cost_credits": 0`, and a `resolution_status` of either `resolving` (live discovery is still running, retry in about a minute) or `none_found`.

---

# GET /v1/company/:handle/signals

> Source: https://www.frontrun.vc/docs/endpoints/company-signals
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/company-signals.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Social signal analysis for a company. Returns buzz score, sentiment, mention count, notable mentions, and tracked VC followers.

**Cost:** 16 credits per call. If no signal can be resolved (no mentions found **and** no tracked VC follows the company), you are not charged.

```bash
curl "https://frontrun.vc/v1/company/stealth_ai_co/signals" \
  -H "X-API-Key: your_api_key"
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `handle` | string (path) | -- | X username of the company. **Required.** |

## Response

```json
{
  "handle": "stealth_ai_co",
  "signals": {
    "buzz_score": 42,
    "sentiment": "positive",
    "mention_count": 42,
    "notable_mentions": [
      {
        "author": "pmarca",
        "text": "StealthAI is doing something really interesting with workflow automation",
        "date": "2026-03-26",
        "likes": 1200
      },
      {
        "author": "paulg",
        "text": "One of the most promising AI startups I've seen this quarter",
        "date": "2026-03-22",
        "likes": 890
      }
    ],
    "tracked_vc_followers": ["pmarca", "naval", "paulg"],
    "tracked_vc_count": 3
  },
  "cost_credits": 16,
  "balance_credits": 9884
}
```

| Field | Type | Description |
|-------|------|-------------|
| `buzz_score` | integer | Number of recent mentions found for the company. |
| `sentiment` | string | Overall read: `"positive"` (mentions carry real engagement), `"low_activity"` (fewer than 3 mentions), or `"neutral"`. |
| `mentions_unavailable` | boolean | Present and `true` only when the mention search failed upstream. The tracked-VC fields are still accurate; `buzz_score` and `sentiment` are not, so retry rather than reading a 0 as "nobody is talking about them". |
| `tracked_vc_followers` | array | Usernames of tracked VCs that follow this company. |
| `tracked_vc_count` | integer | Number of tracked VCs following this company. |

---

# GET /v1/company/:handle/resources

> Source: https://www.frontrun.vc/docs/endpoints/company-resources
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/company-resources.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Discovered links and resources for a company. Aggregates website, GitHub, documentation, community links, and bio links.

**Cost:** 60 credits per call

```bash
curl "https://frontrun.vc/v1/company/stealth_ai_co/resources" \
  -H "X-API-Key: your_api_key"
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `handle` | string (path) | -- | X username of the company. **Required.** |

## Response

```json
{
  "handle": "stealth_ai_co",
  "resources": {
    "website": "https://stealthai.com",
    "twitter": "https://x.com/stealth_ai_co",
    "github": "https://github.com/stealthai",
    "documentation": "https://docs.stealthai.com",
    "discord": "https://discord.gg/stealthai",
    "telegram": null,
    "bio_links": [
      "https://stealthai.com/careers",
      "https://stealthai.com/blog"
    ],
    "all_links": [
      "https://stealthai.com",
      "https://github.com/stealthai",
      "https://docs.stealthai.com",
      "https://discord.gg/stealthai",
      "https://stealthai.com/careers",
      "https://stealthai.com/blog"
    ]
  },
  "cost_credits": 60,
  "balance_credits": 9540
}
```

| Field | Type | Description |
|-------|------|-------------|
| `bio_links` | array | Links extracted from the account's X bio. |
| `all_links` | array | Deduplicated list of all discovered links across sources. |

Fields return `null` when no link is found for that platform.

---

# GET /v1/company/:handle/funding

> Source: https://www.frontrun.vc/docs/endpoints/company-funding
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/company-funding.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Funding and deal information for a company, cross-referenced with VC follow signals.

**Cost:** 60 credits per call. If no funding can be resolved, you are not charged.

```bash
curl "https://frontrun.vc/v1/company/stealth_ai_co/funding" \
  -H "X-API-Key: your_api_key"
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `handle` | string (path) | -- | X username of the company. **Required.** |

## Response

```json
{
  "handle": "stealth_ai_co",
  "name": "StealthAI",
  "funding": {
    "source": "fundable",
    "name": "StealthAI",
    "total_funding": "$12.0M",
    "num_rounds": 2,
    "rounds": [
      {
        "round": "Series A",
        "amount": "$10.0M",
        "amount_usd": 10000000,
        "date": "2026-03-15",
        "description": "Series A to scale enterprise AI workflows",
        "investors": 4
      },
      {
        "round": "Seed",
        "amount": "$2.0M",
        "amount_usd": 2000000,
        "date": "2025-06-02",
        "description": null,
        "investors": 3
      }
    ],
    "investors": ["a16z", "SV Angel"],
    "lead_investors": ["a16z"],
    "founders": ["Jane Doe"],
    "founded_on": "2024-11-01",
    "crunchbase_url": "https://www.crunchbase.com/organization/stealthai"
  },
  "vc_follow_signal": ["pmarca", "naval"],
  "cost_credits": 60,
  "balance_credits": 9540
}
```

| Field | Type | Description |
|-------|------|-------------|
| `funding` | object | Resolved funding profile for the company. |
| `funding.source` | string | Which data source resolved the funding. |
| `funding.total_funding` | string | Total raised across known rounds (e.g. `"$12.0M"`). `null` if unknown. |
| `funding.rounds` | array | Known rounds, each with `round`, `amount`, `amount_usd`, `date`, `description`, and `investors` (count). |
| `funding.lead_investors` | string[] | Lead investors, when known. |
| `funding.founders` | string[] | Founder names, when known. |
| `vc_follow_signal` | string[] | Your tracked accounts that follow this company - your own signal on the deal. |

Fields inside `funding` that the source can't resolve are `null` or empty arrays.

## No funding found

If no funding can be resolved for the handle, the response has `found: false` and **you are not charged**:

```json
{
  "handle": "stealth_ai_co",
  "name": "StealthAI",
  "found": false,
  "funding": null,
  "vc_follow_signal": ["pmarca"],
  "cost_credits": 0,
  "balance_credits": 9600
}
```

---

# GET /v1/vc/:handle/activity

> Source: https://www.frontrun.vc/docs/endpoints/vc-activity
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/vc-activity.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Activity profile for a tracked account - follow velocity, sector distribution, and recent follows.

**Cost:** 24 credits per call

```bash
curl "https://frontrun.vc/v1/vc/pmarca/activity?since=30d" \
  -H "X-API-Key: your_api_key"
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `username` | string (path) | -- | X username of the tracked account. **Required.** |
| `since` | string (query) | `"30d"` | Time window. Accepts days (`"7d"`, `"30d"`, `"90d"`) or ISO date. |

## Response

```json
{
  "username": "pmarca",
  "name": "Marc Andreessen",
  "profile_image_url": "https://pbs.twimg.com/...",
  "since": "2026-02-05T00:00:00.000Z",
  "current_following": 70,
  "new_follows_in_window": 12,
  "follows_per_week": 2.8,
  "sector_breakdown": {
    "AI/ML": 5,
    "Developer Tools": 3,
    "Fintech": 2,
    "Enterprise SaaS": 2
  },
  "recent_follows": [
    {
      "twitter_user_id": "1234567890",
      "username": "newai_startup",
      "name": "NewAI",
      "description": "Building the future of AI infrastructure",
      "verified": true,
      "classification": {
        "is_company": true,
        "sector": "AI/ML",
        "entity_type": "startup"
      }
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `follows_per_week` | number | Average new follows per week in the specified window. |
| `sector_breakdown` | object | Count of new follows grouped by sector. |

---

# GET /v1/vc/:handle/similar

> Source: https://www.frontrun.vc/docs/endpoints/vc-similar
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/vc-similar.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Find VCs with similar follow patterns. Computed from temporal follow graph overlap.

**Cost:** 60 credits per call

```bash
curl "https://frontrun.vc/v1/vc/pmarca/similar?min_overlap=0.2&limit=10" \
  -H "X-API-Key: your_api_key"
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `handle` | string (path) | -- | X username of the tracked VC. **Required.** |
| `min_overlap` | number (query) | `0.1` | Minimum overlap score (0–1) to include in results. |
| `limit` | integer (query) | `20` | Maximum results (max 50). |

## Response

```json
{
  "handle": "pmarca",
  "similar_accounts": [
    {
      "handle": "naval",
      "overlap_score": 0.72,
      "shared_follows": 34,
      "unique_follows": 18
    },
    {
      "handle": "paulg",
      "overlap_score": 0.58,
      "shared_follows": 27,
      "unique_follows": 31
    },
    {
      "handle": "chrisdixon",
      "overlap_score": 0.45,
      "shared_follows": 21,
      "unique_follows": 42
    }
  ],
  "cost_credits": 60,
  "balance_credits": 9540
}
```

| Field | Type | Description |
|-------|------|-------------|
| `overlap_score` | number | Similarity score (0–1) based on shared follow targets weighted by recency. |
| `shared_follows` | integer | Number of entities both VCs follow. |
| `unique_follows` | integer | Entities the similar VC follows that the queried VC does not. Useful for discovery. |

Results are sorted by `overlap_score` descending.

---

# GET /v1/feed

> Source: https://www.frontrun.vc/docs/endpoints/feed
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/feed.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Real-time activity feed across all tracked accounts. Filterable by event type, sector, and time window.

**Cost:** 16 credits per call

```bash
curl "https://frontrun.vc/v1/feed?event_type=convergence&hours=48&limit=20" \
  -H "X-API-Key: your_api_key"
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `event_type` | string (query) | -- | Filter by event type. Values: `"new_follow"`, `"convergence"`. |
| `hours` | integer (query) | `24` | Lookback window in hours. |
| `since` | string (query) | `"24h"` | Alternative time window. Accepts hours (`"12h"`) or days (`"7d"`). Overrides `hours` if both provided. |
| `sector` | string (query) | -- | Filter events to a specific sector. |
| `limit` | integer (query) | `50` | Maximum events returned (max 200). |
| `offset` | integer (query) | `0` | Pagination offset over the sorted event list. |
| `cursor` | string (query) | -- | Opaque watermark from a previous response's `next_cursor`. Resumes exactly where that run stopped, so a retry never double-counts or drops records. Overrides `since`. See [Budgets & Cursors](/docs/reference/budgets-and-cursors). |

## Response

```json
{
  "events": [
    {
      "type": "new_follow",
      "timestamp": "2026-03-28T14:32:00.000Z",
      "vc": {
        "handle": "pmarca",
        "name": "Marc Andreessen"
      },
      "target": {
        "handle": "stealth_ai_co",
        "name": "StealthAI",
        "sector": "AI/ML"
      },
      "classification": {
        "is_company": true,
        "entity_type": "startup",
        "sector": "AI/ML"
      }
    },
    {
      "type": "convergence",
      "timestamp": "2026-03-28T10:15:00.000Z",
      "target": {
        "handle": "dev_infra_xyz",
        "name": "DevInfra",
        "sector": "Developer Tools"
      },
      "accounts": ["pmarca", "naval", "paulg"],
      "signal_strength": 3
    }
  ],
  "total": 2,
  "cost_credits": 16,
  "balance_credits": 9884
}
```

| Field | Type | Description |
|-------|------|-------------|
| `type` | string | Event type: `"new_follow"` or `"convergence"`. |
| `accounts` | array | Only present on convergence events. List of VCs involved. |
| `signal_strength` | integer | Only present on convergence events. Number of VCs that converged on the target. |

---

# GET /v1/sectors

> Source: https://www.frontrun.vc/docs/endpoints/sectors
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/sectors.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Sector breakdown of all discovered entities across your tracked accounts.

**Cost:** 4 credits per call

```bash
curl "https://frontrun.vc/v1/sectors" \
  -H "X-API-Key: your_api_key"
```

## Parameters

No parameters.

## Response

Example, truncated to the top of each list:

```json
{
  "total_entities": 12480,
  "classified_entities": 6310,
  "sectors": [
    { "name": "AI", "count": 1042, "percentage": 17 },
    { "name": "DeFi", "count": 604, "percentage": 10 },
    { "name": "Infrastructure", "count": 528, "percentage": 8 },
    { "name": "Trading", "count": 461, "percentage": 7 },
    { "name": "payments_banking", "count": 388, "percentage": 6 },
    { "name": "Gaming", "count": 351, "percentage": 6 },
    { "name": "Social & Creator", "count": 297, "percentage": 5 },
    { "name": "Payments", "count": 214, "percentage": 3 },
    { "name": "Prediction Markets", "count": 142, "percentage": 2 },
    { "name": "RWA", "count": 118, "percentage": 2 },
    { "name": "Wallets & Identity", "count": 96, "percentage": 2 },
    { "name": "Security & Auditing", "count": 74, "percentage": 1 }
  ],
  "entity_types": [
    { "name": "person", "count": 4102 },
    { "name": "company", "count": 1348 },
    { "name": "project", "count": 271 },
    { "name": "unknown", "count": 208 },
    { "name": "media", "count": 141 },
    { "name": "vc_firm", "count": 96 },
    { "name": "community", "count": 62 },
    { "name": "institution", "count": 44 },
    { "name": "newsletter", "count": 38 }
  ],
  "cost_credits": 4,
  "balance_credits": 9992
}
```

## Sector names are data, not a fixed enum

There is no closed list of sectors. Sector names come from the classifier, so the vocabulary is data-driven and it grows. That means two things:

- **Call `/v1/sectors` to discover the exact strings for your own coverage.** The sectors in the example above are real values from the classification data, but yours depend on who you track. Do not hardcode a taxonomy from this page.
- **The same idea can appear under more than one spelling.** `RWA` and `rwa`, or `Social & Creator` and `social_creator`, are separate rows. Two naming conventions coexist in the data.

Sector values are matched **case-insensitively as substrings** by `/v1/search`, `/v1/follows/enriched`, and `/v1/feed`. So `?sector=pay` matches both `Payments` and `payments_banking`, and `?sector=rwa` matches `RWA` and `rwa`. Use a short stem when you want to catch every variant, and the full string when you want one specific bucket.

Noise labels (`unknown`, `general_crypto`, `other`, `n/a`, `none`, and empty) are filtered out of `sectors` before the response is built. They are not filtered out of `entity_types`, which is why `unknown` can appear there.

| Field | Type | Description |
|-------|------|-------------|
| `total_entities` | integer | Total unique entities discovered across all tracked accounts. |
| `classified_entities` | integer | Entities that have a classification record. Typically well under `total_entities`: anything not yet classified is not counted here. |
| `sectors[].count` | integer | Entities carrying this exact sector string. |
| `sectors[].percentage` | integer | Percentage of classified entities in this sector, rounded to a whole number. Percentages do not sum to 100 because noise sectors are filtered out. |
| `entity_types[].name` | string | Classified entity type, for example `person`, `company`, `project`, `media`, `vc_firm`. Also data-driven. Pass one as `entity_type` to `/v1/search` or `/v1/follows/enriched`. |

---

# GET /v1/discover

> Source: https://www.frontrun.vc/docs/endpoints/discover
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/discover.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Personalized account recommendations based on your tracked set and custom classification rules.

**Cost:** 60 credits per call

```bash
curl "https://frontrun.vc/v1/discover?sector=AI/ML&min_signal=0.5&limit=10" \
  -H "X-API-Key: your_api_key"
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `sector` | string (query) | -- | Filter recommendations to a specific sector. |
| `min_signal` | number (query) | `0.3` | Minimum signal score (0–1) to include. |
| `limit` | integer (query) | `20` | Maximum recommendations (max 50). |

## Response

```json
{
  "recommendations": [
    {
      "handle": "stealth_ai_co",
      "name": "StealthAI",
      "sector": "AI/ML",
      "followed_by": ["pmarca", "naval"],
      "signal_score": 0.87,
      "matched_rule": "ai_infrastructure",
      "reason": "Followed by 2 tracked VCs in the last 7 days. Matches your AI infrastructure classification rule."
    },
    {
      "handle": "dev_infra_xyz",
      "name": "DevInfra",
      "sector": "Developer Tools",
      "followed_by": ["paulg"],
      "signal_score": 0.64,
      "matched_rule": null,
      "reason": "High signal potential in Developer Tools. Recently followed by paulg."
    },
    {
      "handle": "climate_tech_co",
      "name": "ClimateTech",
      "sector": "Climate",
      "followed_by": ["naval", "chrisdixon"],
      "signal_score": 0.52,
      "matched_rule": "climate_focus",
      "reason": "Convergence signal from 2 VCs. Matches your climate focus rule."
    }
  ],
  "total": 3,
  "cost_credits": 60,
  "balance_credits": 9540
}
```

| Field | Type | Description |
|-------|------|-------------|
| `signal_score` | number | Composite signal score (0–1) based on VC follow patterns, convergence, and recency. |
| `matched_rule` | string \| null | Name of your custom classification rule that matched, if any. |
| `followed_by` | array | Tracked VCs that follow this account. |
| `reason` | string | Human-readable explanation of why this account is recommended. |

---

# Webhooks

> Source: https://www.frontrun.vc/docs/endpoints/webhooks
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/webhooks.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

Push-based delivery of signals. Register a URL and Frontrun POSTs events to it as they happen - no polling. Up to **10 active webhooks** per API key.

**Cost:** 40 credits to register a webhook, then 8 credits per delivered event. Listing, deleting, and viewing delivery history are free.

---

## Register a Webhook

`POST /v1/webhooks` - **40 credits**

```bash
curl -X POST https://frontrun.vc/v1/webhooks \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/frontrun",
    "events": ["new_follows", "convergence"],
    "filters": {
      "sectors": ["AI/ML"],
      "is_company_only": true
    },
    "secret": "whsec_your_signing_secret"
  }'
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `url` | string (body) | -- | HTTPS endpoint to receive events. **Required.** Private/loopback addresses are rejected. |
| `events` | string[] (body) | -- | Event types to subscribe to. **Required.** Values: `"new_follows"`, `"convergence"` |
| `filters` | object (body) | `{}` | Only deliver events matching these filters. See below. |
| `secret` | string (body) | -- | Optional signing secret. When set, deliveries include an HMAC-SHA256 signature. |

### Filters

| Field | Type | Applies to | Description |
|-------|------|------------|-------------|
| `tracked_accounts` | string[] | `new_follows` | Only fire for follows from these tracked accounts |
| `sectors` | string[] | both | Only entities whose sector matches (case-insensitive partial match) |
| `entity_types` | string[] | `new_follows` | Only entities whose type matches (e.g. `"startup"`) |
| `is_company_only` | boolean | both | Only fire for entities classified as companies |
| `min_convergence` | integer | `convergence` | Minimum tracked accounts converging (default 2) |

### Response

```json
{
  "id": "wh_9f3a2b1c",
  "url": "https://example.com/hooks/frontrun",
  "events": ["new_follows", "convergence"],
  "filters": {
    "sectors": ["AI/ML"],
    "is_company_only": true
  },
  "status": "active",
  "created_at": "2026-07-08T14:00:00.000Z",
  "cost_credits": 40,
  "balance_credits": 9960
}
```

A `400` is returned for an invalid URL or event type, or when you already have 10 active webhooks.

---

## Event deliveries

Each delivered event costs **8 credits**. Deliveries are `POST` requests with these headers:

| Header | Description |
|--------|-------------|
| `X-Frontrun-Event` | Event type (`new_follows` or `convergence`) |
| `X-Frontrun-Delivery-Id` | Unique delivery ID |
| `X-Frontrun-Signature` | `sha256=<hex>` - HMAC-SHA256 of the raw body using your `secret`. Only present if a secret was set. |

### `new_follows` payload

```json
{
  "event": "new_follows",
  "timestamp": "2026-07-08T14:05:00.000Z",
  "data": {
    "tracked_account": "pmarca",
    "new_follows_count": 1,
    "new_follows": [
      {
        "twitter_user_id": "1234567890",
        "username": "stealth_ai_co",
        "name": "StealthAI",
        "description": "Automating enterprise workflows with LLMs",
        "classification": {
          "is_company": true,
          "sector": "AI/ML",
          "entity_type": "startup",
          "confidence": "high"
        }
      }
    ]
  }
}
```

### `convergence` payload

```json
{
  "event": "convergence",
  "timestamp": "2026-07-08T14:05:00.000Z",
  "data": {
    "username": "stealth_ai_co",
    "name": "StealthAI",
    "description": "Automating enterprise workflows with LLMs",
    "followed_by": ["pmarca", "naval", "garrytan"],
    "convergence_score": 3,
    "classification": {
      "is_company": true,
      "sector": "AI/ML",
      "entity_type": "startup"
    }
  }
}
```

Respond with a `2xx` status within 10 seconds. Failed deliveries are retried with backoff; repeated consecutive failures pause the webhook.

---

## List Webhooks

`GET /v1/webhooks` - **Free**

```bash
curl https://frontrun.vc/v1/webhooks \
  -H "X-API-Key: your_api_key"
```

```json
{
  "count": 1,
  "webhooks": [
    {
      "id": "wh_9f3a2b1c",
      "url": "https://example.com/hooks/frontrun",
      "events": ["new_follows", "convergence"],
      "filters": { "sectors": ["AI/ML"], "is_company_only": true },
      "status": "active",
      "consecutive_failures": 0,
      "last_delivery_at": "2026-07-08T14:05:00.000Z",
      "created_at": "2026-07-08T14:00:00.000Z"
    }
  ]
}
```

---

## Delete a Webhook

`DELETE /v1/webhooks/:id` - **Free**

```bash
curl -X DELETE https://frontrun.vc/v1/webhooks/wh_9f3a2b1c \
  -H "X-API-Key: your_api_key"
```

```json
{
  "deleted": true,
  "id": "wh_9f3a2b1c"
}
```

---

## Delivery History

`GET /v1/webhooks/:id/deliveries` - **Free**

```bash
curl "https://frontrun.vc/v1/webhooks/wh_9f3a2b1c/deliveries?limit=50" \
  -H "X-API-Key: your_api_key"
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `id` | string (path) | -- | Webhook ID. **Required.** |
| `limit` | integer (query) | `50` | Maximum deliveries returned (max 200). |

### Response

```json
{
  "webhook_id": "wh_9f3a2b1c",
  "count": 2,
  "deliveries": [
    {
      "id": "del_7c1e4d9a",
      "event_type": "new_follows",
      "status_code": 200,
      "response_ms": 142,
      "attempt": 1,
      "delivered_at": "2026-07-08T14:05:00.000Z"
    },
    {
      "id": "del_5b0d3c8f",
      "event_type": "convergence",
      "status_code": 500,
      "response_ms": 310,
      "attempt": 2,
      "delivered_at": "2026-07-08T13:40:00.000Z"
    }
  ]
}
```

---