Track Accounts

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

Add Account

POST /v1/track

Cost: Draws on your monthly usage (free if the account is already in the shared coverage pool)

Starts monitoring an X account for new follows.

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

Response

{
  "username": "pmarca",
  "tracking": true,
  "ready": true,
  "follow_count": 70,
  "usage_pct": 12,
  "usage_resets_at": "2026-11-01T00:00:00Z",
  "message": "Tracking active. New activity will appear shortly."
}

Errors

Add Accounts in Bulk

POST /v1/track

Cost: Draws on your monthly usage per account new to the platform. Accounts already in the shared coverage pool are free.

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

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

Request body

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

Response

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

{
  "batch": true,
  "results": [
    { "username": "pmarca", "status": "tracked", "tracking": true, "ready": true, "follow_count": 70, "new_introduction": false },
    { "username": "naval", "status": "already_tracked", "tracking": true, "ready": true, "error": "Already tracking this account" },
    { "username": "not_a_real_handle", "status": "not_found", "error": "Twitter account @not_a_real_handle not found" }
  ],
  "summary": { "submitted": 3, "tracked": 1, "already_tracked": 1, "not_found": 1 },
  "usage_pct": 12,
  "usage_resets_at": "2026-11-01T00:00:00Z"
}

Per-item status values

Limits worth knowing

• 50 handles per request. Larger batches return 400 with error_code: "batch_too_large".
• 10 new-account introductions per request. An introduction means a handle the platform has never seen, which costs us a live X lookup. Handles past the tenth come back deferred rather than failed, and the rest of the batch still processes. Handles already in the coverage pool do not count.
• The daily introduction cap is shared across the whole batch, not applied per item, and it is the same counter the single-handle endpoint uses.
• Your tracking limit applies to the batch too. Handles past it come back tracking_cap. With automatic expansion on, the cap is raised once for the whole batch (one charge), not once per handle.

Tracking limits

Keys created from a Frontrun account are held to the same tracking limit as the web app.

Accounts outside the network stay private to you: they never join the Frontrun Network.

Admin keys are exempt. Accounts already over their limit are never trimmed: everything you track keeps working, you just cannot add more until you are back under it.

Going past 250 on Pro

Turn on automatic expansion in Settings > Billing. Each account past 250 then costs $0.25 per month, billed the same way as the web app. A batch POST /v1/track raises the cap once for the whole batch, so you get one charge, not one per handle.

Swaps

You get 25 free swaps per rolling 7 days. A swap is untracking one account and tracking another: the slot frees immediately.

Past 25 swaps in a week, an account you untrack keeps its slot for 7 days before it frees up. Re-tracking the same account you just dropped is always free, it takes its own slot back.

Over the limit

A single-handle POST /v1/track returns 403:

{
  "error": "Tracking limit reached (250 accounts).",
  "error_code": "tracking_cap",
  "account_limit": 250,
  "tracking": 250,
  "swaps_this_week": 27,
  "free_swaps_per_week": 25,
  "held_slots": 2,
  "overage_hint": "Pro can go past 250 at $0.25 per account per month: turn on automatic expansion in Settings > Billing.",
  "hold_note": "You get 25 free swaps a week. Past that, an account you stop tracking keeps its slot for 7 days.",
  "next_slot_free_at": "2026-10-02T15:20:00.000Z"
}

In a batch, the handle's status is tracking_cap and the response carries a tracking_cap_note.

Remove Account

DELETE /v1/track/:username

Cost: Free

Stops monitoring an account.

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

Response

{
  "username": "pmarca",
  "tracking": false,
  "slot_freed": true,
  "free_swaps_left": 24,
  "free_swaps_per_week": 25,
  "slot_note": "Slot freed. 24 of 25 free swaps left this week."
}

The swap fields are returned for keys created from a Frontrun account. See Swaps.

List Tracked Accounts

GET /v1/track

Cost: Free

Returns all accounts you're currently monitoring.

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

Response

{
  "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"
    }
  ]
}