# Frontrun API — Full Documentation

> Generated 2026-05-07T15:42:45.736Z. Single-file dump of all docs at https://frontrun.vc/docs.

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://frontrun.vc/docs/llms.txt.

---

# Introduction

> Source: https://frontrun.vc/docs
> Raw markdown: https://frontrun.vc/docs/raw/index.md
> Full docs (single file): https://frontrun.vc/docs/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 |
|---|---|
| [`/docs/llms.txt`](/llms.txt) | [llmstxt.org](https://llmstxt.org) index — every page with a one-line summary and a link to its raw markdown |
| [`/docs/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

Hybrid model. Subscribe for monthly credits at standard rates, or pay-as-you-go at 2.5x rates on the free tier.

| Plan | Monthly cost | Credits included | Rate | MCP |
|---|---|---|---|---|
| **Free** | $0 | $0 | 2.5x standard | No |
| **Starter** | $49/mo | $25/mo | Standard | No |
| **Pro** | $99/mo | $75/mo | Standard | Yes |
| **Enterprise** | Custom | Unlimited | Custom | Yes |

Standard rates: $0.01 basic, $0.02 signal, $0.05 intelligence, $0.10 founder.

Every response includes `cost_cents` and `balance_cents` so you always know your spend.

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

---

## Quickstart

### Get your API key

Generate an API key from your [Frontrun dashboard](https://frontrun.vc/dashboard). Subscribers get monthly credits automatically; pay-as-you-go users load credits via the developer page.

### 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_cents": 10,
  "balance_cents": 4990,
  "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_cents": 5,
  "balance_cents": 4985,
  "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
        }
      ]
    }
  ]
}
```

---

# Authentication

> Source: https://frontrun.vc/docs/authentication
> Raw markdown: https://frontrun.vc/docs/raw/authentication.md
> Full docs (single file): https://frontrun.vc/docs/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** (recommended) — Starter ($49/mo) gets $25/mo credits, Pro ($99/mo) gets $75/mo credits. Credits renew each billing period.
- **Pay-as-you-go** — Load credits once via the developer page. Free tier pays 2.5x standard rates.

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

[Full pricing →](/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 balance",
  "required_cents": 5,
  "balance_cents": 0,
  "top_up": "https://frontrun.vc/api/billing"
}
```

Credit balance is insufficient for the requested operation. Load more credits 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.

---

# Use Cases

> Source: https://frontrun.vc/docs/use-cases
> Raw markdown: https://frontrun.vc/docs/raw/use-cases.md
> Full docs (single file): https://frontrun.vc/docs/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](/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](/integrations/mcp-server) and [Claude Code](/integrations/claude-code) for setup.

---

# GET /v1/status

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

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

**Cost:** Free

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

## Response

```json
{
  "balance": {
    "cents": 4850,
    "dollars": "48.50"
  },
  "tracked_accounts": 12,
  "usage_30d": {
    "total_calls": 347,
    "total_spent_cents": 1150,
    "total_spent_dollars": "11.50",
    "by_operation": {
      "follows_new": { "calls": 280, "cost_cents": 1400 },
      "track_setup": { "calls": 12, "cost_cents": 120 },
      "convergence": { "calls": 30, "cost_cents": 300 },
      "follows_snapshot": { "calls": 25, "cost_cents": 50 }
    }
  },
  "pricing": {
    "track_setup": 10,
    "follows_new": 5,
    "follows_snapshot": 2,
    "convergence": 10,
    "classification": 3
  }
}
```

## Response fields

| Field | Type | Description |
|-------|------|-------------|
| `balance` | object | Current credit balance in cents and dollars. |
| `tracked_accounts` | integer | Number of accounts currently being monitored. |
| `usage_30d` | object | Usage breakdown for the last 30 days, grouped by operation. |
| `pricing` | object | Current per-operation pricing in cents. |

---

# Track Accounts

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

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

---

## Add Account

`POST /v1/track`

**Cost:** $0.01

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_cents": 10,
  "balance_cents": 4990,
  "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 balance |
| 404 | X account not found |
| 409 | Already tracking this account |

---

## 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"
    }
  ]
}
```

---

# GET /v1/preview/:handle

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

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

**Cost:** $0.01 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_cents": 5,
  "balance_cents": 4900
}
```

| 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. |

---

# GET /v1/follows/new

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

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

**Cost:** $0.04 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. |

## Response

```json
{
  "since": "2026-03-05T04:00:00.000Z",
  "accounts_checked": 3,
  "total_new_follows": 5,
  "cost_cents": 5,
  "balance_cents": 4845,
  "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`.

---

# GET /v1/follows/snapshot

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

Returns the current follow list for a tracked account.

**Cost:** $0.01 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_cents": 2,
  "balance_cents": 4848,
  "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 balance |
| 404 | Not tracking this account |

---

# GET /v1/follows/enriched

> Source: https://frontrun.vc/docs/endpoints/enriched
> Raw markdown: https://frontrun.vc/docs/raw/endpoints/enriched.md
> Full docs (single file): https://frontrun.vc/docs/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:** $0.04 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. |

## Response

```json
{
  "since": "2026-03-07T04:00:00.000Z",
  "accounts_checked": 50,
  "total_new_follows": 12,
  "cost_cents": 5,
  "balance_cents": 4840,
  "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)

---

# GET /v1/convergence

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

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

**Cost:** $0.10 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_cents": 10,
  "balance_cents": 4840,
  "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://frontrun.vc/docs/endpoints/trending
> Raw markdown: https://frontrun.vc/docs/raw/endpoints/trending.md
> Full docs (single file): https://frontrun.vc/docs/llms-full.txt

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

**Cost:** $0.04 per call (+$0.04/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). |
| `classify` | string (query) | -- | Set to `"true"` to include AI classification. |

## Response

```json
{
  "since": "2026-02-28T00:00:00.000Z",
  "accounts_scanned": 50,
  "total": 25,
  "cost_cents": 5,
  "balance_cents": 4840,
  "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://frontrun.vc/docs/endpoints/search
> Raw markdown: https://frontrun.vc/docs/raw/endpoints/search.md
> Full docs (single file): https://frontrun.vc/docs/llms-full.txt

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

**Cost:** $0.01 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). |

## Response

```json
{
  "filters": {
    "sector": "AI/ML",
    "keyword": null,
    "entity_type": "startup"
  },
  "total": 23,
  "cost_cents": 3,
  "balance_cents": 4842,
  "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"
      }
    }
  ]
}
```

---

# Custom Classification

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

Build your own classification layer on top of Frontrun's AI. Define rules that auto-tag entities, manually tag companies, and query with your custom data merged in.

---

## Classification Rules

Rules auto-classify entities based on pattern matching. When you query `/follows/enriched`, matching entities get your custom tags, sectors, and types applied automatically.

### 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"
    }
  }'
```

#### Conditions

All conditions must match (AND logic). Within `bio_keywords`, any keyword triggers a match (OR logic).

| 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"` |

### List Rules

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

### Update a Rule

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

### Delete a Rule

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

---

## Custom Tags

Manually tag individual entities with your own sectors, types, and notes.

### Add/Update Tags

`POST /v1/tags` — **Free**

```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."
  }'
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `twitter_user_id` | string | One of these | Entity's Twitter user ID |
| `username` | string | required | Entity's username |
| `tags` | string[] | No | Custom tags |
| `custom_sector` | string | No | Sector override |
| `custom_entity_type` | string | No | Entity type override |
| `notes` | string | No | Free-text notes |

### List Tags

`GET /v1/tags` — **Free**

```bash
# All tagged entities
curl ".../v1/tags"

# Filter by tag
curl ".../v1/tags?tag=portfolio"

# Filter by custom sector
curl ".../v1/tags?sector=DeFi"
```

### Remove Tags

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

---

## On-Demand Classification

`POST /v1/classify`

Classify specific entities with AI classification + your custom rules + your custom tags merged.

**Cost:** $0.04/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"]}'
```

```json
{
  "total": 2,
  "cost_cents": 6,
  "balance_cents": 4839,
  "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."
      }
    }
  ]
}
```

---

# GET /v1/company/:handle

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

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

**Cost:** $0.10 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.** |

## 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_cents": 15,
  "balance_cents": 4800
}
```

| 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://frontrun.vc/docs/endpoints/company-founders
> Raw markdown: https://frontrun.vc/docs/raw/endpoints/company-founders.md
> Full docs (single file): https://frontrun.vc/docs/llms-full.txt

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

**Cost:** $0.25 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
{
  "handle": "stealth_ai_co",
  "founders": [
    {
      "handle": "janesmith_ai",
      "name": "Jane Smith",
      "role": "CEO & Co-founder",
      "background": "Former ML lead at Google Brain. PhD in Computer Science from Stanford.",
      "previous_companies": ["Google", "DeepMind"],
      "linkedin_summary": "Serial AI entrepreneur with 12 years in machine learning infrastructure. Led a team of 40 at Google Brain before founding StealthAI.",
      "confidence": 0.95
    },
    {
      "handle": "bob_eng",
      "name": "Bob Chen",
      "role": "CTO & Co-founder",
      "background": "Ex-Stripe senior engineer. Built payments infrastructure at scale.",
      "previous_companies": ["Stripe", "Square"],
      "linkedin_summary": "Infrastructure engineer specializing in distributed systems. 8 years building fintech platforms.",
      "confidence": 0.88
    }
  ],
  "cost_cents": 25,
  "balance_cents": 4775
}
```

| Field | Type | Description |
|-------|------|-------------|
| `confidence` | number | Confidence score (0–1) that this person is a founder of the company. Based on social graph signals, bio mentions, and mutual follows. |
| `linkedin_summary` | string | Enriched summary from LinkedIn profile data. May be `null` if no LinkedIn match found. |
| `previous_companies` | array | Notable previous employers identified from LinkedIn and bio. |

---

# GET /v1/company/:handle/signals

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

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

**Cost:** $0.04 per call

```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": 0.73,
    "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_cents": 10,
  "balance_cents": 4850
}
```

| Field | Type | Description |
|-------|------|-------------|
| `buzz_score` | number | Normalized buzz score (0–1) based on mention velocity and engagement. |
| `sentiment` | string | Overall sentiment: `"positive"`, `"neutral"`, or `"negative"`. |
| `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://frontrun.vc/docs/endpoints/company-resources
> Raw markdown: https://frontrun.vc/docs/raw/endpoints/company-resources.md
> Full docs (single file): https://frontrun.vc/docs/llms-full.txt

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

**Cost:** $0.10 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_cents": 5,
  "balance_cents": 4900
}
```

| 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://frontrun.vc/docs/endpoints/company-funding
> Raw markdown: https://frontrun.vc/docs/raw/endpoints/company-funding.md
> Full docs (single file): https://frontrun.vc/docs/llms-full.txt

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

**Cost:** $0.10 per call

```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",
  "funding": {
    "name": "StealthAI",
    "amount": "$12M",
    "round": "Series A",
    "date": "2026-03-15",
    "lead_investors": ["a16z"],
    "other_investors": ["Sequoia Scout", "SV Angel"]
  },
  "vc_follow_signal": [
    {
      "vc_handle": "pmarca",
      "followed_at": "2026-02-28",
      "days_before_announcement": 15
    },
    {
      "vc_handle": "naval",
      "followed_at": "2026-03-01",
      "days_before_announcement": 14
    }
  ],
  "cost_cents": 15,
  "balance_cents": 4800
}
```

| Field | Type | Description |
|-------|------|-------------|
| `funding` | object | Most recent funding round. `null` if no known funding. |
| `vc_follow_signal` | array | Tracked VCs that followed this company, with timing relative to the funding announcement. |
| `days_before_announcement` | integer | How many days before the public funding announcement the VC follow was detected. Negative means after. |

---

# GET /v1/vc/:handle/activity

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

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

**Cost:** $0.06 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://frontrun.vc/docs/endpoints/vc-similar
> Raw markdown: https://frontrun.vc/docs/raw/endpoints/vc-similar.md
> Full docs (single file): https://frontrun.vc/docs/llms-full.txt

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

**Cost:** $0.10 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_cents": 15,
  "balance_cents": 4800
}
```

| 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://frontrun.vc/docs/endpoints/feed
> Raw markdown: https://frontrun.vc/docs/raw/endpoints/feed.md
> Full docs (single file): https://frontrun.vc/docs/llms-full.txt

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

**Cost:** $0.04 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). |

## 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_cents": 10,
  "balance_cents": 4850
}
```

| 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://frontrun.vc/docs/endpoints/sectors
> Raw markdown: https://frontrun.vc/docs/raw/endpoints/sectors.md
> Full docs (single file): https://frontrun.vc/docs/llms-full.txt

Sector breakdown of all discovered entities across your tracked accounts.

**Cost:** $0.01 per call

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

## Parameters

No parameters.

## Response

```json
{
  "total_entities": 4280,
  "classified_entities": 3150,
  "sectors": [
    {
      "name": "AI/ML",
      "count": 892,
      "percentage": 28.3
    },
    {
      "name": "Crypto/Web3",
      "count": 614,
      "percentage": 19.5
    },
    {
      "name": "Developer Tools",
      "count": 487,
      "percentage": 15.5
    },
    {
      "name": "Fintech",
      "count": 341,
      "percentage": 10.8
    },
    {
      "name": "Enterprise SaaS",
      "count": 298,
      "percentage": 9.5
    },
    {
      "name": "Healthcare",
      "count": 195,
      "percentage": 6.2
    },
    {
      "name": "Consumer",
      "count": 168,
      "percentage": 5.3
    },
    {
      "name": "Climate",
      "count": 89,
      "percentage": 2.8
    },
    {
      "name": "Cybersecurity",
      "count": 66,
      "percentage": 2.1
    }
  ],
  "entity_types": [
    { "name": "startup", "count": 1820 },
    { "name": "growth_company", "count": 540 },
    { "name": "individual", "count": 380 },
    { "name": "vc_fund", "count": 210 },
    { "name": "enterprise", "count": 105 },
    { "name": "media", "count": 55 },
    { "name": "accelerator", "count": 40 }
  ],
  "cost_cents": 5,
  "balance_cents": 4900
}
```

| Field | Type | Description |
|-------|------|-------------|
| `total_entities` | integer | Total unique entities discovered across all tracked accounts. |
| `classified_entities` | integer | Entities that have been classified with a sector. |
| `sectors[].percentage` | number | Percentage of classified entities in this sector. |

---

# GET /v1/discover

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

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

**Cost:** $0.10 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_cents": 15,
  "balance_cents": 4800
}
```

| 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. |

---

# MCP Server

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

The Frontrun MCP server gives AI agents native access to the Frontrun API. 29 tools, version 2.3.2. Everything 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 (29)

### 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_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 |
| `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 |

## 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/ML 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)

---

# OpenClaw

> Source: https://frontrun.vc/docs/integrations/openclaw
> Raw markdown: https://frontrun.vc/docs/raw/integrations/openclaw.md
> Full docs (single file): https://frontrun.vc/docs/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 AI/ML or Crypto 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, @a]16zcrypto
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/ML 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

| 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_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_vc_activity` | Activity profile: velocity, sectors |
| `frontrun_search` | Search by sector, keyword, type |
| `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_delete_rule` | Delete a rule |
| `frontrun_tag` | Tag an entity |
| `frontrun_list_tags` | List tagged entities |

---

## 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.

---

# Claude Code

> Source: https://frontrun.vc/docs/integrations/claude-code
> Raw markdown: https://frontrun.vc/docs/raw/integrations/claude-code.md
> Full docs (single file): https://frontrun.vc/docs/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

### 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_vc_activity` | Account velocity, sectors, recent follows |
| `frontrun_search` | Find entities by sector, keyword, or type |
| `frontrun_enriched_follows` | New follows with AI + custom rules merged |

### 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_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_delete_rule` | Remove a rule |
| `frontrun_tag` | Manually tag an entity |
| `frontrun_list_tags` | List all custom-tagged entities |
| `frontrun_classify` | Run on-demand classification |

---

## 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.
```

---

# Cursor

> Source: https://frontrun.vc/docs/integrations/cursor
> Raw markdown: https://frontrun.vc/docs/raw/integrations/cursor.md
> Full docs (single file): https://frontrun.vc/docs/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.
```

---

# Python

> Source: https://frontrun.vc/docs/integrations/python
> Raw markdown: https://frontrun.vc/docs/raw/integrations/python.md
> Full docs (single file): https://frontrun.vc/docs/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']}")
```

---

# JavaScript

> Source: https://frontrun.vc/docs/integrations/javascript
> Raw markdown: https://frontrun.vc/docs/raw/integrations/javascript.md
> Full docs (single file): https://frontrun.vc/docs/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}`);
}
```

---

# Pricing

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

Frontrun has a **hybrid pricing model**. Subscribe for monthly API credits at standard rates, or pay-as-you-go on the free tier at 2.5x rates.

---

## Plans

| Plan | Monthly cost | API credits included | API rate | MCP access | Overage discount |
|---|---|---|---|---|---|
| **Free** | $0 | $0 | 2.5x standard | No | None |
| **Starter** | $49/mo | $25/mo | Standard | No | None |
| **Pro** | $99/mo | $75/mo | Standard | Yes | 20% off |
| **Enterprise** | Custom | Unlimited | Custom | Yes | N/A |

**Monthly credits do not roll over** — unused credits expire at the end of each billing period.

---

## What each plan includes

### Free
- Pay-as-you-go at **2.5x standard rates**
- $35/day spend cap
- 60 requests/minute
- Web app: 25 tracked accounts

### Starter — $49/mo
- **$25/month in API credits** (expires monthly)
- Standard rates (see table below)
- $50/day cap on overage
- 120 requests/minute
- Web app: 100 tracked accounts, reports, Pipeline CRM

### Pro — $99/mo
- **$75/month in API credits** (expires monthly)
- Standard rates, **20% off overages**
- **MCP access** (Claude Code, Cursor, Claude Desktop)
- $200/day cap on overage
- 300 requests/minute
- Web app: 250 tracked accounts, full history, advanced analytics

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

---

## Standard API rates

Applies to Starter, Pro, and Enterprise. Free tier pays 2.5x these rates.

### 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 — $0.01

| 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 — $0.04

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

### Intelligence — $0.06–$0.10

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

### Premium — $0.25

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

### Webhooks

| Operation | Cost |
|-----------|------|
| Webhook setup | $0.10 |
| Per delivery | $0.02 |

---

## Which plan should I pick?

**"I just want to try it"** → Free. 2.5x rates, $35/day cap.

**"I check signals a few times a week"** → Starter at $49/mo. $25 credits covers ~625 basic, ~625 signal, or ~250 intelligence calls per month.

**"I'm building an agent or automated pipeline"** → Pro at $99/mo. $75 credits + MCP access + 20% overage discount.

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

---

## Monthly cost examples

**Casual user on Starter** — web dashboard plus occasional API calls

| Usage | Calls/mo | Cost |
|-------|----------|------|
| Feed 2x/day | 60 | $2.40 |
| New follows 1x/day | 30 | $1.20 |
| Convergence 1x/day | 30 | $3.00 |
| Company lookups | 15 | $1.50 |
| Search | 20 | $0.20 |
| **API total** | | **~$8** |
| **Starter subscription** | | **$49** |

Remaining $17 in credits for the month. Same usage on Free (2.5x) would cost ~$20/mo — Starter is only worth it once the web app perks or heavier API volume kick in.

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

| Usage | Calls/mo | Cost |
|-------|----------|------|
| Feed hourly | 720 | $28.80 |
| Enriched follows 10x/day | 300 | $12.00 |
| Convergence 5x/day | 150 | $15.00 |
| Company endpoints | 200 | $20.00 |
| Founders | 100 | $25.00 |
| Search/discover | 200 | $12.00 |
| **API total** | | **~$113** |
| **Pro subscription** | | **$99** |

$75 credits covers the first $75 of usage; remaining $38 billed at 20% overage discount (~$30). Total: **~$129/mo all-in**.

---

## How billing works

1. **Subscribe or load credits** — Subscribe for monthly credits, or top up pay-as-you-go
2. **Monthly credits applied first** — Subscribers use monthly allocation before top-up balance
3. **Monthly credits expire** — Unused monthly credits reset each billing period
4. **Top-up never expires** — Funds you load yourself stay in your balance indefinitely
5. **Track spend** — Every response includes `cost_cents` and `balance_cents`
6. **Top up** — A `402` response means insufficient balance

```json
{
  "data": [...],
  "cost_cents": 2,
  "balance_cents": 9898
}
```

---

# Parameters & Limits

> Source: https://frontrun.vc/docs/reference/parameters
> Raw markdown: https://frontrun.vc/docs/raw/reference/parameters.md
> Full docs (single file): https://frontrun.vc/docs/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 | Values | Description |
|-------|--------|-------------|
| `sector` | DeFi, AI, Infrastructure, Gaming, Trading, Payments, etc. | Primary sector |
| `entity_type` | company, project, person, fund, vc | Entity classification |
| `is_company` | true/false | Whether entity is an organization |
| `confidence` | high, medium, low | Classification confidence |

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

### 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_cents": 10,
  "balance_cents": 9890
}
```

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

---

# Errors & Status Codes

> Source: https://frontrun.vc/docs/reference/errors
> Raw markdown: https://frontrun.vc/docs/raw/reference/errors.md
> Full docs (single file): https://frontrun.vc/docs/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 credit balance |
| `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 spend 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 balance

```json
{
  "error": "Insufficient balance",
  "required_cents": 10,
  "balance_cents": 3,
  "top_up": "https://frontrun.vc/api/billing"
}
```

The response tells you exactly how much is needed vs. available. Top up your balance 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 spend cap reached:**

```json
{
  "error": "Daily spend cap reached",
  "daily_spent_cents": 5000,
  "daily_cap_cents": 5000,
  "resets_at": "2026-03-12T00:00:00.000Z"
}
```

The daily spend cap (default $50) 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"
}
```

### 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 balance |
| `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` (spend 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 |

---

# Rate Limits

> Source: https://frontrun.vc/docs/reference/rate-limits
> Raw markdown: https://frontrun.vc/docs/raw/reference/rate-limits.md
> Full docs (single file): https://frontrun.vc/docs/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 spend cap** (dollar ceiling).

## Request-count limits

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

## Daily spend cap

| Tier | Daily cap |
|------|-----------|
| Free | $35/day |
| Starter | $50/day |
| Pro | $200/day |
| Enterprise | None |

Paid tiers have a daily dollar cap to prevent runaway agent costs. When the cap is reached, the API returns `429`:

```json
{
  "error": "Daily spend cap reached",
  "daily_spent_cents": 20000,
  "daily_cap_cents": 20000,
  "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](/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](/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.

---

# Security

> Source: https://frontrun.vc/docs/reference/security
> Raw markdown: https://frontrun.vc/docs/raw/reference/security.md
> Full docs (single file): https://frontrun.vc/docs/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 spend cap

Every API key has a daily spend cap (default: **$50/day**). 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_cents": 10,
  "balance_cents": 490
}
```

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)

---