Track Accounts

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

Add Account

POST /v1/track

Cost: 4 credits

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

Field	Type	Required	Description
`username`	string	Yes	X username to track. Leading `@` is stripped automatically.

Response

{
  "username": "pmarca",
  "tracking": true,
  "ready": true,
  "follow_count": 70,
  "cost_credits": 4,
  "balance_credits": 9996,
  "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 credits
404	X account not found
409	Already tracking this account

Add Accounts in Bulk

POST /v1/track

Cost: 4 credits 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

Field	Type	Required	Description
`usernames`	string[]	Yes	X usernames to track. Max 50 per request. `handles` is accepted as an alias. Duplicates are collapsed.
`max_credits`	integer	No	Cap what this call may cost. See Budgets & Cursors.

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, "cost_credits": 0 },
    { "username": "naval", "status": "already_tracked", "tracking": true, "ready": true, "error": "Already tracking this account", "cost_credits": 0 },
    { "username": "not_a_real_handle", "status": "not_found", "error": "Twitter account @not_a_real_handle not found", "cost_credits": 0 }
  ],
  "summary": { "submitted": 3, "tracked": 1, "already_tracked": 1, "not_found": 1 },
  "cost_credits": 0,
  "max_cost_credits": 40,
  "balance_credits": 9996
}

Per-item status values

Status	Meaning
`tracked`	Added. `new_introduction: true` means it was new to the platform and billed.
`already_tracked`	You were already tracking it. Free.
`not_found`	The handle does not resolve on X. Never billed.
`invalid`	Empty or malformed handle.
`deferred`	Not attempted: this request had already used its 10 new-account introductions. Resubmit just these handles.
`intro_cap`	The daily new-account introduction limit for your tier was reached (free 20, starter 100, pro 250, enterprise 2000). Accounts already in the coverage pool are unlimited.
`insufficient_credits`	Balance ran out partway through the batch.
`tracked_limit`	Your plan's tracked-account quota is full.
`upstream_unavailable`	X was temporarily unreachable for this handle. Retry it.
`failed`	Server-side failure for this handle. Retry it.

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.

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
}

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

GET /v1/status GET /v1/preview/:handle