# GET /v1/companies

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

Your company catalog. Every company in your own daily reports, the companies your tracked accounts found in the last 30 days, and a one-time starter set of companies in your sectors, each row labelled with where it came from.

This is the recommended first call for any agent. It is never empty on day one.

**Cost:** Draws on your monthly usage.

**Access:** keys created from a Frontrun account only. A standalone key gets `400`.

```bash
curl "https://frontrun.vc/v1/companies?sector=AI&limit=50" \
  -H "X-API-Key: your_api_key"
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `sector` | string (query) | -- | Filter by sector. Case-insensitive substring match, e.g. `"AI"`, `"Robotics"`. |
| `since` | string (query) | -- | Only companies flagged since this point. Accepts `"7d"`, `"48h"`, or an ISO date. Filters on `flagged_at`. |
| `q` | string (query) | -- | Search handle, name, or description. |
| `source` | string (query) | -- | `"your_list"` for only your own companies, `"starter"` for only the starter set. Omit for both. |
| `limit` | integer (query) | `50` | Maximum results (max 200). |
| `offset` | integer (query) | `0` | Pagination offset. |

## Where each row comes from

Every row carries `source` and `via`.

| `source` | `via` | What it is |
|----------|-------|------------|
| `your_list` | `report` | A company from one of your own daily reports, net new from signup on. The two sample reports gifted at signup are not included. |
| `your_list` | `tracked_30d` | A company one of the accounts you **currently** track discovered in the last 30 days, dated by when that account first followed it. Tracking an account adds its last 30 days, not its all-time history. Untracking the account removes them. |
| `starter` | `onboarding` | A one-time snapshot of up to about 200 companies from the last 30 days in your sectors, deduped against your own list. |

Your own list comes first (report rows newest first, then `tracked_30d` rows), then the starter set.

### How the starter set is built

Your sectors are the ones you picked in onboarding. If you never picked any, they are inferred from your own companies, and if there is nothing to infer from, the set defaults to AI. The snapshot is built on your first call and only rebuilt if you change your onboarding sectors. It is a starting catalog, not a rolling feed, and it comes from the whole Frontrun network, not from your tracked accounts.

## Response

```json
{
  "companies": [
    {
      "username": "stealth_ai_co",
      "name": "StealthAI",
      "description": "Automating enterprise workflows with LLMs",
      "sector": "AI",
      "website": "https://stealthai.com",
      "profile_image_url": "https://pbs.twimg.com/profile_images/...",
      "followers": 412,
      "stage": null,
      "flagged_at": "2026-09-26",
      "tracked_followers": 3,
      "source": "your_list",
      "via": "report"
    },
    {
      "username": "dev_infra_xyz",
      "name": "DevInfra",
      "description": "Next-gen developer infrastructure",
      "sector": "Infrastructure",
      "website": "https://devinfra.xyz",
      "profile_image_url": "https://pbs.twimg.com/profile_images/...",
      "followers": 1180,
      "stage": null,
      "flagged_at": "2026-09-21T14:02:00.000Z",
      "tracked_followers": 2,
      "source": "your_list",
      "via": "tracked_30d"
    },
    {
      "username": "agent_ops_hq",
      "name": "AgentOps",
      "description": "Observability for AI agents",
      "sector": "AI",
      "website": "https://agentops.example",
      "profile_image_url": "https://pbs.twimg.com/profile_images/...",
      "followers": 860,
      "stage": "pre-seed",
      "flagged_at": "2026-09-12T09:30:00.000Z",
      "tracked_followers": null,
      "source": "starter",
      "via": "onboarding"
    }
  ],
  "total": 214,
  "counts": { "your_list": 38, "starter": 176 },
  "seed": {
    "chips": ["ai", "infra-devtools"],
    "chip_source": "lens",
    "window_days": 30,
    "seeded_at": "2026-09-20T17:45:00.000Z"
  },
  "has_more": true,
  "next_offset": 50,
  "usage_pct": 12,
  "usage_resets_at": "2026-11-01T00:00:00Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `companies[].flagged_at` | string | When the company reached you: the report date for `report` rows, the first follow by a tracked account for `tracked_30d` rows. |
| `companies[].tracked_followers` | integer | How many of **your** tracked accounts follow the company. `null` on starter rows. |
| `companies[].stage` | string | Estimated stage, when a starter row carries one. Otherwise `null`. |
| `companies[].source` | string | `"your_list"` or `"starter"`. |
| `companies[].via` | string | `"report"`, `"tracked_30d"`, or `"onboarding"`. |
| `total` | integer | Rows matching your filters, across both sources. |
| `counts` | object | Matching rows split into `your_list` and `starter`. |
| `seed` | object | How your starter set was built: `chips` (sectors), `chip_source` (`"lens"` from onboarding, `"inferred"` from your companies, or `"default"`), `window_days`, `seeded_at`. `null` if it has not been built yet. |
| `has_more` | boolean | More rows past this page. |
| `next_offset` | integer | The `offset` for the next page, or `null`. |

## Which startups are my accounts converging on?

Sort by `tracked_followers`. A company followed by several of your own tracked accounts is the startup version of a convergence signal, and every row here is already a company.

```python
import requests

response = requests.get(
    "https://frontrun.vc/v1/companies",
    headers={"X-API-Key": "your_api_key"},
    params={"source": "your_list", "since": "30d", "limit": 200}
)

companies = response.json()["companies"]
companies.sort(key=lambda c: c["tracked_followers"] or 0, reverse=True)

for c in companies[:10]:
    print(f"{c['name']} (@{c['username']}) - {c['tracked_followers']} of your accounts, flagged {c['flagged_at']}")
```

[`/v1/convergence`](/docs/endpoints/convergence) and [`/v1/trending`](/docs/endpoints/trending) return startups only, for what your accounts are converging on this week. This endpoint stays the full catalog and the first call.