# Aggregated multi-exchange sweep activity

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

API: Flowseeker. Credits: 3.

Returns "logical sweeps" — multi-exchange splits of one large order
grouped by contract within a one-second execution window. Each row
carries the venue list, total contracts/premium, spread position,
moneyness bucket, and Skylit Flow Score / FlowBonus. The summary
block adds population-level Sweep Dominance Factor (SDF) and
bullish/bearish counts extrapolated from the full-day total.

## 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`). |
| `timeframe` | query | string | no | Trailing window. Currently only restricts the trading day; `5m`/`15m`/`1h`/`4h` reserved for future intraday filtering. (one of `5m`, `15m`, `1h`, `4h`, `1d`; default `1h`) |
| `min_premium` | query | number (double) | no |  |
| `option_type` | query | string | no |  (one of `call`, `put`, `all`; default `all`) |
| `moneyness` | query | string | no |  (one of `deep_itm`, `itm`, `atm`, `otm`, `deep_otm`, `all`; default `all`) |
| `min_dte` | query | integer | no |  (min 0) |
| `max_dte` | query | integer | no |  (min 0) |
| `min_strike` | query | number (double) | no |  |
| `max_strike` | query | number (double) | no |  |
| `expiration` | query | string (date) | no | Restrict to a single expiration date (`YYYY-MM-DD`). |
| `limit` | query | integer | no | Max sweep rows returned (server caps at 500). (default `100`; min 1; max 500) |
| `date` | query | string (date) | no |  |

## Example request

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

## Responses

### 200

Sweep activity for `{ticker}`.

Shape (placeholder values):

```json
{
  "data": {
    "ticker": "string",
    "sweeps": [
      {
        "timestamp": "string",
        "optionType": "CALL",
        "strike": 0,
        "expiration": "string",
        "dte": 0,
        "totalContracts": 0,
        "totalPremium": 0,
        "exchangeCount": 0,
        "exchanges": [
          "string"
        ],
        "executionTimeMs": 0,
        "spreadPosition": "AT_ASK",
        "moneyness": "DEEP_ITM",
        "scores": {
          "flowScore": 0,
          "flowBonus": 0
        }
      }
    ],
    "summary": {
      "totalSweeps": 0,
      "bullishSweeps": 0,
      "bearishSweeps": 0,
      "totalSweepPremium": 0,
      "sdf": 0,
      "returnedCount": 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."
  }
}
```