# Raw enriched trades for a contract

`GET https://api.skylit.ai/v1/contract/{symbol}/trades`

API: Flowseeker.

Same enriched trade shape as `/v1/underlying/{ticker}/trades`,
scoped to a single OPRA contract. Because the contract is fixed,
chain-level filters (moneyness, strike, DTE, expiration) do not
apply here.

**Paging.** Trades come largest premium first. When a page is full,
`meta.nextCursor` is set: pass it back as `cursor` with the same
`start`, `end` and filters for the next page. No gaps or repeats; no
`nextCursor` means the window is exhausted. Splitting the time window
instead re-reads overlapping ranges and gets an `X-Skylit-Hint`
response header.

## Authentication

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

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `symbol` | path | string | yes | OPRA option symbol in URL-safe form: `{ticker}__{YYMMDD}{C\|P}{strike×1000, 8 digits}` — the ticker and the 15-character contract block are joined by a **double underscore** (`__`). For example, an AAPL $250 call expiring 2026-01-17 is `AAPL__260117C00250000`. (A space-padded 21-char OCC form such as `AAPL 260117C00250000` is also accepted on some endpoints, but the `__` form is canonical and works across all contract routes.) |
| `cursor` | query | string | no | `meta.nextCursor` from the previous page, passed back unchanged with the same filters. Opaque; an invalid value returns `400`. |
| `start` | query | string | no | Lower time bound — RFC 3339 or Unix seconds. Defaults to start-of-trading-day. |
| `end` | query | string | no | Upper time bound — RFC 3339 or Unix seconds. Defaults to now. |
| `limit` | query | integer | no |  (default `50`; min 1; max 500) |
| `only_sweeps` | query | boolean | no |  |
| `only_multi_leg` | query | boolean | no |  |
| `exclude_multi_leg` | query | boolean | no |  |
| `min_premium` | query | number (double) | no |  (min 0) |

## Example request

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

## Responses

### 200

Enriched trades for the contract.

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,
      "crossTrade": 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",
    "nextCursor": "string",
    "nextEndTime": "string"
  }
}
```

### 400

Request validation failed.

invalidParam:

```json
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid value 'bogus' for 'timeframe'. Allowed: 5m, 15m, 1h, 4h, 1d."
  }
}
```

### 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

Unknown, revoked or expired API key (the gateway's `forbidden`), the account's API access is suspended (`account_suspended`) or blocked (`account_blocked`). Not retryable.

badKey:

```json
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Access to this API has been disallowed"
  }
}
```

accountSuspended:

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

### 404

Unknown ticker or contract (`SYMBOL_NOT_FOUND`), or no data for the requested window. Not charged.

unknownSymbol:

```json
{
  "error": {
    "code": "SYMBOL_NOT_FOUND",
    "message": "Unknown ticker 'ZZZZQ'."
  }
}
```

noData:

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

### 429

Either the key exceeded its requests-per-minute limit (`X-RateLimit-Limit`; no `Retry-After`, wait until `X-RateLimit-Reset`), or the account is over one of the API's own limits, such as the query budget (queries running at once, fresh queries per second): `TOO_MANY_CONCURRENT_QUERIES` or `RATE_LIMITED` with `Retry-After`. Not charged; retry after the wait.

tooFast:

```json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded."
  }
}
```

queryBudget:

```json
{
  "error": {
    "code": "TOO_MANY_CONCURRENT_QUERIES",
    "message": "This account already has 16 queries running on the shared query engine across all servers (limit ch.concurrent.customer). Cached answers are not affected. Retry after Retry-After; to backfill a day, follow meta.nextCursor instead of splitting time windows. See https://www.skylit.ai/docs/api-reference/rate-limits-and-retries",
    "retry_after": 1,
    "docs_url": "https://www.skylit.ai/docs/api-reference/errors#too_many_concurrent_queries"
  }
}
```

### 500

Unexpected server error (`INTERNAL_ERROR`, `DATABASE_ERROR`). Not charged; safe to retry with exponential backoff.

internal:

```json
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}
```

### 503

Underlying data source temporarily unavailable, the credit balance could not be verified (`credit_check_failed`), or the API is paused for maintenance (`api_paused`, with a `Retry-After` header and a `retry_after` field in seconds). Not charged; 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."
  }
}
```

### 504

The request did not complete within 25 seconds. Not charged; narrow the window or retry.

tooSlow:

```json
{
  "error": {
    "code": "GATEWAY_TIMEOUT",
    "message": "The request took too long and was not completed. It was not charged; narrow the request or retry."
  }
}
```