---
title: "Track an account"
method: POST
path: "/track"
tags: ["Tracking"]
---

# Track an account

`POST /track`

## Request

- Base URL: `https://frontrun.vc/v1`
- URL: `https://frontrun.vc/v1/track`
- Auth: API key in header `X-API-Key`

Add an X account (typically an investor) to your tracked set so its new follows feed every signal endpoint (/follows/new, /follows/enriched, /convergence, /trending, /feed, /discover). Costs 4 credits when the account is new to the platform (a follow baseline is fetched); accounts already in the shared coverage pool are added free. Returns 201 with `ready` indicating whether a follow baseline already exists; while ready=false the account produces no signal until its first snapshot completes. Handles that fail to resolve on X return 404 and are never billed. New-account introductions are capped per key per day by tier (free 20, starter 100, pro 250, enterprise 2000); adding accounts already in the coverage pool does not count against the cap. Batch: send `usernames` (alias `handles`) as an array of up to 50 handles instead of a single `username` to track them in one call. The single-username shape is unchanged. The batch path always answers 200 with a per-item result because partial success is normal; read each item's `status` rather than the HTTP code. You are charged per account actually NEW to the platform, not per item submitted. At most 10 new-account introductions are attempted per request (handles beyond that return status "deferred" - resubmit them), and the per-tier daily introduction cap is shared across the whole batch. Account keys are held to the same tracking limit as the web app: Starter 100, Pro 250, custom plan caps apply, Enterprise its own cap; admin keys are exempt. Accounts already over their limit are never trimmed, they just cannot add more. Pro users who turned on automatic expansion (Settings > Billing) go past 250 at $0.25 per account per month, billed like the web app; a batch raises the cap once for the whole batch (one charge). You get 25 free swaps per rolling 7 days (untrack one account, track another, the slot frees immediately). Past that, an account you stop tracking keeps its slot for 7 days before it frees up; re-tracking that same account is always free. Over the limit, a single handle returns 403 with error_code "tracking_cap" (account_limit, tracking, swaps_this_week, free_swaps_per_week, held_slots, overage_hint, and when slots are held hold_note and next_slot_free_at); in a batch that handle's status is "tracking_cap" and the response carries tracking_cap_note.

## Request body

- object
  - `username` string: X username to track (with or without @).
  - `usernames` string[]: Batch form: X usernames to track (with or without @). Max 50 per request; duplicates are collapsed. Mutually exclusive with `username`.
  - `handles` string[]: Alias for `usernames`.
  - `max_credits` integer: Batch form only. Ceiling on what this call may cost, in credits. FAILS CLOSED before any upstream lookup: over the ceiling, nothing is tracked and nothing is charged (400, error_code max_credits_exceeded). Only handles new to the platform bill, so the actual charge is usually well under the ceiling.

## Response `200`

Batch result. Always 200 when an array was submitted, including when some items failed.

- object
  - `batch` boolean
  - `results` object[]
    - `username` string
    - `status` 'tracked' | 'already_tracked' | 'not_found' | 'invalid' | 'deferred' | 'intro_cap' | 'insufficient_credits' | 'tracking_cap' | 'tracked_limit' | 'upstream_unavailable' | 'failed'
    - `tracking` boolean
    - `ready` boolean
    - `follow_count` integer
    - `new_introduction` boolean: True when this handle was new to the platform, which is the only case that bills.
    - `cost_credits` integer
    - `error` string
  - `summary` object: Counts keyed by status, plus `submitted`.
  - `cost_credits` integer: Total charged across the batch.
  - `max_cost_credits` integer
  - `balance_credits` integer
  - `deferred_note` string
  - `intro_cap_note` string
  - `tracking_cap_note` string

## Other responses

- `201`: Tracking registered.
- `400`: Missing or invalid username, batch too large, or max_credits exceeded.
- `401`: Missing, invalid, inactive, or expired API key.
- `402`: Insufficient credits for this operation. Top up from the developer page or enable auto-refill.
- `403`: Tracking limit reached (error_code "tracking_cap").
- `404`: X account not found.
- `409`: Already tracking this account.
- `429`: Rate limit or daily credit cap reached. Retry after the indicated reset time.

---

[API](https://skmtc.dev/frontrun/apis/frontrun-api.md) · [All operations](https://skmtc.dev/frontrun/apis/frontrun-api/llms.txt) · [OpenAPI document](https://skmtc.dev/frontrun/apis/frontrun-api/revisions/6880b29e94c9?raw)