Custom Tags
Manually tag individual entities with your own tags, sectors, types, and notes. Tags are merged into /follows/enriched and /classify responses. All tag operations are free.
Limit: 10,000 tagged entities per account (100,000 on Enterprise). A 429 is returned at the cap.
Add/Update Tags
POST /v1/tags — Free
Upserts by entity — posting again for the same entity updates the existing tag record.
curl -X POST https://frontrun.vc/v1/tags \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"username": "stealth_ai_co",
"tags": ["portfolio", "series-a"],
"custom_sector": "AI Infrastructure",
"notes": "Series A target Q2."
}'Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
twitter_user_id | string (body) | -- | Entity's X user ID. Required unless username is set. |
username | string (body) | -- | Entity's X username. Required unless twitter_user_id is set. Must already exist in Frontrun's classification cache — a 404 is returned otherwise. |
tags | string[] (body) | -- | Custom tags |
custom_sector | string (body) | -- | Sector override |
custom_entity_type | string (body) | -- | Entity type override |
notes | string (body) | -- | Free-text notes |
Response
Returns 201 with the tag record:
{
"id": "c2d8e1f0-7b6a-4c5d-8e9f-1a2b3c4d5e6f",
"twitter_user_id": "1234567890",
"username": "stealth_ai_co",
"tags": ["portfolio", "series-a"],
"custom_sector": "AI Infrastructure",
"custom_entity_type": null,
"notes": "Series A target Q2.",
"updated_at": "2026-07-08T14:00:00.000Z"
}List Tags
GET /v1/tags — Free
# All tagged entities
curl "https://frontrun.vc/v1/tags" \
-H "X-API-Key: your_api_key"
# Filter by tag
curl "https://frontrun.vc/v1/tags?tag=portfolio" \
-H "X-API-Key: your_api_key"
# Filter by custom sector
curl "https://frontrun.vc/v1/tags?sector=DeFi" \
-H "X-API-Key: your_api_key"Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
tag | string (query) | -- | Only entities carrying this exact tag. |
sector | string (query) | -- | Only entities whose custom_sector matches. Case-insensitive partial match. |
Response
{
"count": 1,
"tags": [
{
"id": "c2d8e1f0-7b6a-4c5d-8e9f-1a2b3c4d5e6f",
"twitter_user_id": "1234567890",
"username": "stealth_ai_co",
"tags": ["portfolio", "series-a"],
"custom_sector": "AI Infrastructure",
"custom_entity_type": null,
"notes": "Series A target Q2.",
"updated_at": "2026-07-08T14:00:00.000Z"
}
]
}Sorted by most recently updated.
Remove Tags
DELETE /v1/tags/:twitter_user_id — Free
Removes all custom tags, overrides, and notes for the entity.
curl -X DELETE https://frontrun.vc/v1/tags/1234567890 \
-H "X-API-Key: your_api_key"{
"deleted": true,
"twitter_user_id": "1234567890"
}Returns 404 if the entity has no tags.