---
title: "Detailed scoring for a single trade"
method: GET
path: "/v1/score/{trade_id}"
tags: ["Scoring"]
---

# Detailed scoring for a single trade

`GET /v1/score/{trade_id}`

Returns sentiment, urgency, and confidence scores for an individual
trade plus a spread-level breakdown and full trade context (ticker,
strike, expiration, sweep/block flags, moneyness). Used to drill
into a single row from `/v1/flow/{ticker}`.

The `trade_id` path parameter accepts three formats: the canonical
`flow_{hex}_{idx}` id returned by the flow feed, a bare hex
timestamp (`188afe42c3a77af2`), or a raw nanosecond integer.

## Path parameters

- `trade_id` string, required

## Response `200`

Trade scoring breakdown.

- TradeScoreSuccess
  - `data` TradeScoreResponse, required
    - `tradeId` string, required
    - `scores` TradeScores, required
      - `sentiment` integer, required
      - `urgency` integer, required
      - `confidence` number, required
    - `interpretation` TradeInterpretation, required
      - `direction` 'bullish' | 'bearish' | 'neutral', required
      - `intent` string, required — Intent classification (e.g. `opening_long_call`, `closing_short_put`, `aggressive_call_buy`, `passive_call_sell`). Returned as a stable `snake_case` token; new values may be added as classification improves.
      - `description` string, required — One-sentence human-readable explanation of the trade.
    - `spreadAnalysis` SpreadAnalysis, required
      - `bid` number, required
      - `ask` number, required
      - `mid` number, required
      - `tradePrice` number, required
      - `positionInSpread` 'above_ask' | 'at_ask' | 'below_ask' | 'mid' | 'above_bid' | 'at_bid' | 'below_bid' | 'no_bbo', required — Discrete bucket label inferred from the canonical side code (`A`/`AA`/`BA` → ask-side, `B`/`BB`/`AB` → bid-side, `M` → mid, `N` → no BBO).
      - `spreadWidth` number, required
      - `spreadPct` number, required
    - `tradeContext` TradeContext, required
      - `ticker` string, required
      - `timestamp` string, date-time, required
      - `optionType` 'call' | 'put', required
      - `strike` number, required
      - `expiration` string, date, required
      - `premium` number, required
      - `size` integer, required
      - `underlyingPrice` number, required
      - `tradeType` 'sweep' | 'block' | 'regular', required
      - `dte` integer, required
      - `moneyness` 'deep_itm' | 'itm' | 'atm' | 'otm' | 'deep_otm', required
      - `moneynessPct` number, required
  - `meta` Meta, required
    - `timestamp` string, date-time, required — Server-side timestamp the response was generated at.
    - `requestId` string, required — Short opaque ID for log correlation.

## Other responses

- `400` — Request validation failed.
- `401` — Missing or invalid API key.
- `402` — The account's shared Skylit credit balance is lower than this route's cost. Top up to continue. Carries `X-Credits-Remaining: 0`.
- `403` — API key revoked/expired, monthly quota exceeded, or the account's API access is suspended (`account_suspended`).
- `404` — Unknown resource (ticker / sector / window with no data).
- `429` — Per-minute rate limit exceeded.
- `503` — Underlying data source temporarily unavailable, or the credit balance could not be verified (`credit_check_failed`). Safe to retry.

---

[API](https://skmtc.net/skylit/apis/flowseeker-skylit-public-api.md) · [All operations](https://skmtc.net/skylit/apis/flowseeker-skylit-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/skylit/flowseeker-skylit-public-api/revisions/3280190b1b24/schema)