---
title: "Add or update custom tags"
method: POST
path: "/tags"
tags: ["Classification"]
---

# Add or update custom tags

`POST /tags`

## Request

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

Tag an entity with your own tags, custom sector, custom entity type, and notes. Tags are merged into /follows/enriched and /classify responses and matched by the `tag` filter. Upserts on the entity, so repeat calls update the record. Identify the entity by twitter_user_id or username (username is resolved via the classification cache and returns 404 if unknown). Free, costs 0 credits. Limit 10,000 tagged entities (100,000 on Enterprise).

## Request body

- object
  - `twitter_user_id` string: Entity X user ID (this or username required).
  - `username` string: Entity X username (resolved via the classification cache).
  - `tags` string[]
  - `custom_sector` string
  - `custom_entity_type` string
  - `notes` string

## Response `201`

Tag record created or updated.

- TagRecord
  - `id` string
  - `twitter_user_id` string
  - `username` string
  - `tags` string[]
  - `custom_sector` string
  - `custom_entity_type` string
  - `notes` string
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `400`: twitter_user_id or username required.
- `401`: Missing, invalid, inactive, or expired API key.
- `404`: Entity not found in the classification cache.
- `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)