# Detailed scoring for a single trade

`GET https://flow-api.skylit.ai/v1/score/{trade_id}`

API: Flowseeker. Credits: 1.

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.

## Authentication

Send your Skylit API key as a bearer token: `Authorization: Bearer <key>`. No other header is accepted.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `trade_id` | path | string | yes | Trade id (`flow_{hex}_{idx}`, bare hex timestamp, or raw nanos). |

## Example request

```bash
curl "https://flow-api.skylit.ai/v1/score/flow_188afe42c3a77af2_0" \
  -H "Authorization: Bearer $SKYLIT_API_KEY"
```

## Responses

### 200

Trade scoring breakdown.

Shape (placeholder values):

```json
{
  "data": {
    "tradeId": "flow_188afe42c3a77af2_0",
    "scores": {
      "sentiment": 0,
      "urgency": 0,
      "confidence": 0
    },
    "interpretation": {
      "direction": "bullish",
      "intent": "string",
      "description": "string"
    },
    "spreadAnalysis": {
      "bid": 0,
      "ask": 0,
      "mid": 0,
      "tradePrice": 0,
      "positionInSpread": "above_ask",
      "spreadWidth": 0,
      "spreadPct": 0
    },
    "tradeContext": {
      "ticker": "string",
      "timestamp": "string",
      "optionType": "call",
      "strike": 0,
      "expiration": "string",
      "premium": 0,
      "size": 0,
      "underlyingPrice": 0,
      "tradeType": "sweep",
      "dte": 0,
      "moneyness": "deep_itm",
      "moneynessPct": 0
    }
  },
  "meta": {
    "timestamp": "string",
    "requestId": "d7574836"
  }
}
```

### 400

Request validation failed.

invalidParam:

```json
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid parameter 'timeframe': must be one of [1m, 5m, 15m, 1h, 4h, 1d, 1w, 1M]"
  }
}
```

### 401

Missing or invalid API key.

missingKey:

```json
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}
```

### 402

The account's shared Skylit credit balance is lower than this route's cost. Top up to continue. Carries `X-Credits-Remaining: 0`.

Headers: `X-Credits-Remaining`.

outOfCredits:

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "Out of credits. Top up to continue making requests."
  }
}
```

### 403

API key invalid, revoked or expired, or the account's API access is suspended (`account_suspended`).

accountSuspended:

```json
{
  "error": {
    "code": "account_suspended",
    "message": "API access has been suspended for this account. Contact support."
  }
}
```

### 404

Unknown resource (ticker / sector / window with no data).

noData:

```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "No trades found for AAPL on 2026-05-27 with timeframe 1d"
  }
}
```

### 429

Per-minute rate limit exceeded.

Headers: `Retry-After`.

tooFast:

```json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit of 100 req/min exceeded. Retry after 18s."
  }
}
```

### 503

Underlying data source temporarily unavailable, or the credit balance could not be verified (`credit_check_failed`). Safe to retry.

ingestionLag:

```json
{
  "error": {
    "code": "UNAVAILABLE",
    "message": "Live feed is degraded; please retry in a few seconds."
  }
}
```

creditCheckFailed:

```json
{
  "error": {
    "code": "credit_check_failed",
    "message": "Could not verify credit balance. Please retry."
  }
}
```