Docs
API Reference
Lists

Lists

Your own lists of accounts. These are the lists you see as tabs on Home in the app and can turn into reports. Build a list of the investors, scouts and operators whose follows you trust, then query any feed endpoint with scope=list:<id>. See Scopes.

Cost: free. Lists need an account API key.

GET /v1/lists

Your lists, oldest first.

curl "https://frontrun.vc/v1/lists" -H "X-API-Key: your_api_key"
{
  "lists": [
    {
      "id": "3f9c2a4e-...",
      "name": "AI seed investors",
      "feed": "accounts",
      "sectors": ["AI"],
      "max_followers": null,
      "min_tracking": 2,
      "created_at": "2026-10-19T15:02:11Z",
      "size": 48,
      "query_with": "scope=list:3f9c2a4e-..."
    }
  ],
  "total": 1,
  "network_scope": true
}

network_scope says whether your plan can query scope=network.

POST /v1/lists

Create a list.

curl -X POST "https://frontrun.vc/v1/lists" \
  -H "X-API-Key: your_api_key" -H "Content-Type: application/json" \
  -d '{ "name": "AI seed investors", "handles": ["tanayj", "stevejang"], "sectors": ["AI"], "min_tracking": 2 }'
FieldTypeDescription
namestring, requiredUp to 60 characters
handlesstring[]X handles, without @. Up to 5,000
feed"accounts" | "network"accounts (default) = the members' follows. network = the whole Frontrun network, narrowed by the list's sectors
sectorsstring[]Only companies in these sectors. Empty = all
max_followersnumberStored with the list and shown in the app's feed
min_trackingnumberDefault convergence threshold for this list

The response is 201 with the list. Handles we don't poll yet come back in not_polled, with a hint. Track them with POST /v1/track to get their follows:

{
  "list": { "id": "3f9c2a4e-...", "name": "AI seed investors", "size": 2, "query_with": "scope=list:3f9c2a4e-..." },
  "not_polled": ["someangel"],
  "hint": "1 member is outside the Frontrun network. Track it with POST /v1/track to get its follows."
}

GET /v1/lists/:id

One list and its members.

{
  "list": { "id": "3f9c2a4e-...", "name": "AI seed investors", "size": 2, "...": "..." },
  "members": [
    { "username": "tanayj", "name": "Tanay Jaipuria", "avatar_url": "https://...", "firm": "Wing VC", "in_network": true, "x_url": "https://x.com/tanayj" }
  ]
}

PATCH /v1/lists/:id

Rename a list or change its settings. Only the fields you send change: name, feed, sectors, max_followers, min_tracking (send null to clear a number).

Members

  • PUT /v1/lists/:id/members with { "handles": [...] } replaces the whole membership.
  • POST /v1/lists/:id/members with { "add": [...], "remove": [...] } edits it.

Both return { size, added, removed }, plus not_polled when some members are outside the network.

DELETE /v1/lists/:id

Deletes the list. Its tab in the app goes too, along with any reports built on it.

MCP

frontrun_lists, frontrun_list_get, frontrun_list_create, frontrun_list_update, frontrun_list_members, frontrun_list_delete. Scoped tools take a scope argument: "network" or "list:<id>".

GET /v1/preview/:handleGET /v1/companies