# Bucketed market-wide net call premium / net put premium time series

`GET https://flow-api.skylit.ai/v1/market/tide`

API: Flowseeker. Credits: 3.

Returns the market-wide intraday "tide" — bucketed Net Call
Premium and Net Put Premium series with both per-bucket and
cumulative values, plus an SPY price overlay for context. Two
directional flavors are emitted per bar: the standard `ncp`/`npp`
(call-buying minus call-selling, etc.) and a `manualNcp`/
`manualNpp` variant with fewer exclusions applied, for callers
that need raw flow.

## Authentication

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

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `interval` | query | string | no | Trailing window length. Defaults to a single trading day (`1D`); multi-day intervals roll up history at the chosen bucket size. (one of `1D`, `2D`, `3D`, `5D`, `7D`, `14D`, `30D`, `45D`, `60D`, `90D`, `120D`, `180D`, `360D`; default `1D`) |
| `bucket` | query | string | no | Bucket size for the time series. (one of `1min`, `5min`, `15min`, `30min`, `1d`, `1w`; default `5min`) |
| `date` | query | string (date) | no | Trading date anchor (`YYYY-MM-DD`). Defaults to today. |
| `exclude_multi_leg` | query | boolean | no | Exclude multi-leg / spread trades from the directional totals. (default `false`) |
| `exclude_deep_itm` | query | boolean | no | Exclude deep in-the-money trades (`moneyness_percent < -20`) from the directional totals. (default `false`) |

## Example request

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

## Responses

### 200

Market tide bars.

Shape (placeholder values):

```json
{
  "data": {
    "interval": "string",
    "bucket": "string",
    "bars": [
      {
        "timestamp": 0,
        "timestampEnd": 0,
        "ncp": 0,
        "npp": 0,
        "ncpCumulative": 0,
        "nppCumulative": 0,
        "manualNcp": 0,
        "manualNpp": 0,
        "manualNcpCumulative": 0,
        "manualNppCumulative": 0,
        "callVolume": 0,
        "putVolume": 0,
        "totalVolume": 0,
        "spyPrice": 0,
        "isGap": false
      }
    ]
  },
  "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."
  }
}
```

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