---
title: "Classify entities"
method: POST
path: "/classify"
tags: ["Classification"]
---

# Classify entities

`POST /classify`

## Request

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

Fetch classification on demand for up to 100 entities (by twitter_user_ids and/or usernames, combined max 100): AI classification with your custom rules and custom tags merged in. Served from the classification cache; entities not in the cache are silently omitted. Costs 16 credits per entity actually returned, so zero results cost 0 credits.

## Request body

- object: Provide twitter_user_ids and/or usernames (max 100 combined).
  - `twitter_user_ids` string[]: Entity X user IDs.
  - `usernames` string[]: Entity X usernames.
  - `handles` string[]: Alias for usernames.
  - `max_credits` integer: Ceiling on what this single call may cost, in credits. FAILS CLOSED: checked against the maximum the call could cost before any billable work runs, so if it would exceed the ceiling nothing is computed and nothing is charged (400, error_code max_credits_exceeded, with max_cost_credits telling you the real number). You are still billed only for what was actually computed, so a call that clears the ceiling usually lands under it. Relevant here because cost is 16 credits per entity found and the ceiling is 100 entities (1,600 credits).

## Response `200`

Classified entities.

- object
  - `total` integer
  - `results` object[]
    - `twitter_user_id` string
    - `username` string
    - `description` string
    - `classification` object
      - `is_company` boolean
      - `confidence` string
      - `sector` string
      - `entity_type` string
      - `sub_category` string
      - `tags` string[]
    - `custom` CustomData: Your custom tags and rule matches merged into the entity.
      - `tags` string[]
      - `sector` string: Custom sector override.
      - `entity_type` string: Custom entity type override.
      - `notes` string
      - `priority` string
      - `matched_rule` string: Name of the classification rule that matched.
  - `cost_credits` integer: Credits charged for this call.
  - `balance_credits` integer: Remaining credit balance after this call.
  - `max_cost_credits` integer: The most this call could have cost with the parameters you sent. Budget the next call against it. cost_credits is what you were actually charged.

## Other responses

- `401`: Missing, invalid, inactive, or expired API key.
- `402`: Insufficient credits for this operation. Top up from the developer page or enable auto-refill.
- `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)