# 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:** Draws on your monthly usage.

```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"` |
| `industry` | string (query) | -- | Taxonomy industry (the market served). `"AI"` for any AI-native company, or one of `"B2B Software"`, `"Developer Tools"`, `"Fintech"`, `"Crypto"`, `"Consumer"`, `"Gaming"`, `"Commerce"`, `"Healthcare"`, `"Bio"`, `"Industrials"`, `"Aerospace & Defense"`, `"Energy"`, `"Hardware"`, `"Security"`, `"Education"`, `"Real Estate"`. Implies `scope=catalog`. Admin preview. |
| `sub` | string (query) | -- | Taxonomy sub-industry, e.g. `"Robotics"`, `"Payments"`, `"DeFi"`, `"Legal"`. `GET /v1/sectors` lists them with counts. |
| `ai` | string (query) | -- | Kind of AI company: `"Foundation Models & Research"`, `"AI Infra & Compute"`, `"Agent Infra"`, `"Training Data & Annotation"`, `"Evals & RL Environments"`, `"Agent Builders"`, `"General Assistants"`, `"Vertical Agents"`, `"Coding Agents"`, `"Voice AI"`, `"Generative Media"`, `"Physical AI"`, `"AI Security & Safety"`; `"any"` or `"none"`. |
| `buyer` | string (query) | -- | `"Enterprise"`, `"SMB"`, `"Developers"`, `"Consumers"`, `"Government"`, `"Crypto users"`. |
| `crypto` | boolean (query) | -- | `true` = onchain / token component. |
| `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 **usage per company that resolves**; companies with no cached founders are free. |
| `max_credits` | integer (query) | -- | Optional spend ceiling for this call; usage scales with `limit` when `include_founders=true`. 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,
  "usage_pct": 12,
  "usage_resets_at": "2026-11-01T00:00:00Z",
  "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"
      }
    }
  ]
}
```

## Starter results

For keys created from a Frontrun account, the response can add a separate `starter_results` array and a `starter_note`: up to 25 matches for the same `keyword` and `sector` from your starter set, the last 30 days of companies in your sectors. This works in the default mode and with `scope=catalog`.

- Only on the first page (`offset` 0).
- Not added when `entity_type` is set, or when `min_followers` / `max_followers` is set.
- Handles already in `results` are dropped.

Starter rows are **never mixed into `results`**. Every starter row has `source: "starter"` and comes from the whole Frontrun network, not from your tracked accounts.

```json
{
  "total": 2,
  "results": [ ... ],
  "starter_results": [
    {
      "username": "agent_ops_hq",
      "name": "AgentOps",
      "description": "Observability for AI agents",
      "sector": "AI",
      "followers": 860,
      "flagged_at": "2026-09-12T09:30:00.000Z",
      "source": "starter",
      "via": "onboarding",
      "x_url": "https://x.com/agent_ops_hq"
    }
  ],
  "starter_note": "starter_results: the last 30 days of companies in your sectors, from the whole Frontrun network, not from accounts you track. They are here so a new account is not empty and fade out as your own list grows. GET /v1/companies lists both."
}
```

To page through your own companies and the starter set together, use [`GET /v1/companies`](/docs/endpoints/companies).