# Raw enriched trades for a ticker

`GET https://flow-api.skylit.ai/v1/underlying/{ticker}/trades`

API: Flowseeker.

Returns the raw enriched trade rows that feed the chart bars and
the live feed. Supports rich filtering — sweep-only / multi-leg,
moneyness, premium floor, DTE / strike / expiration windows.
See `OptionTradeRow` below.

## Authentication

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

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `ticker` | path | string | yes | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `start` | query | string | no | Lower time bound — ISO 8601 (e.g. `2026-01-12T09:30:00Z`) or Unix seconds. Defaults to start-of-trading-day. |
| `end` | query | string | no | Upper time bound — ISO 8601 or Unix seconds. Defaults to now. |
| `limit` | query | integer | no |  (default `50`; min 1; max 500) |
| `only_sweeps` | query | boolean | no |  (default `false`) |
| `only_multi_leg` | query | boolean | no |  (default `false`) |
| `exclude_multi_leg` | query | boolean | no |  (default `false`) |
| `moneyness` | query | string | no |  (one of `ITM`, `ATM`, `OTM`) |
| `min_moneyness_pct` | query | number (double) | no |  |
| `max_moneyness_pct` | query | number (double) | no |  |
| `min_premium` | query | number (double) | no |  (min 0) |
| `min_dte` | query | integer | no |  |
| `max_dte` | query | integer | no |  |
| `min_strike` | query | number (double) | no |  |
| `max_strike` | query | number (double) | no |  |
| `expiration` | query | string (date) | no |  |

## Example request

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

## Responses

### 200

Filtered enriched trades.

Shape (placeholder values):

```json
{
  "data": [
    {
      "date": 0,
      "tsEvent": 0,
      "tsEventUs": 0,
      "instrumentId": 0,
      "rawSymbol": "SPY   250516C00580000",
      "ticker": "SPY",
      "expiration": 0,
      "strike": 0,
      "right": "C",
      "dte": 0,
      "price": 0,
      "size": 0,
      "side": "BB",
      "publisherId": 0,
      "bidPx": 0,
      "askPx": 0,
      "bidSz": 0,
      "askSz": 0,
      "neutralSz": 0,
      "totalPremium": 0,
      "spread": 0,
      "underlyingPrice": 0,
      "iv": 0,
      "moneyness": "ITM",
      "moneynessPercent": 0,
      "openInterest": 0,
      "prevOi": 0,
      "prevClose": 0,
      "prevCloseAge": 0,
      "priceChange": 0,
      "dailyVolume": 0,
      "sweepTrade": false,
      "blockTrade": false,
      "multiLeg": false,
      "ivDirection": -1,
      "ingestionTimestamp": 0,
      "prevIv": 0,
      "nextIv": 0,
      "premiumPercentile": 0,
      "flowScore": 0,
      "chainBidPct": 0,
      "chainAskPct": 0,
      "contractBidPct": 0,
      "contractAskPct": 0,
      "aggCount": 0,
      "aggTotalPremium": 0,
      "aggTotalSize": 0,
      "mlSibling": false,
      "strategyGroupId": "string",
      "strategyType": "string",
      "strategyLegCount": 0,
      "earningsDte": 0,
      "nextEarningsDate": 0,
      "cacheMiss": false,
      "sector": "string",
      "industry": "string"
    }
  ],
  "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."
  }
}
```

### 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."
  }
}
```