> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stratalerts.com/llms.txt
> Use this file to discover all available pages before exploring further.

# In-Force and Simultaneous Breaks

> Poll in-force setup alerts and simultaneous break events. Filter by timeframe, direction, and candle state. Use since_id for incremental polling.

The alerts endpoints expose two distinct alert types that StratAlerts generates in real time. In-force alerts fire when a setup becomes actionable — price is inside the trigger range on a given timeframe. Simultaneous break alerts fire when multiple index futures break the same direction within a detection window. Both endpoints share the `alerts:read` scope and support `since_id`-based incremental polling so you can efficiently retrieve only new events since your last request.

***

## GET /alerts/in-force

Returns in-force setup alerts. An alert is "in force" when price has entered the actionable range of a setup on a given timeframe. Filter by symbol, timeframe, direction, and candle state to narrow the result set.

**`GET https://app.stratalerts.com/api/market/v1/alerts/in-force`**

<Note>
  Requires scope: `alerts:read`
</Note>

### Request parameters

<ParamField query="symbols" type="string">
  Comma-separated list of ticker symbols to filter by (e.g., `AAPL,SPY`). When omitted, alerts for all symbols are returned.
</ParamField>

<ParamField query="window_minutes" type="number">
  How far back in time (in minutes) to look for alerts. When omitted, the server's default window applies.
</ParamField>

<ParamField query="limit" type="number">
  Maximum number of alert items to return. Server-side clamping applies.
</ParamField>

<ParamField query="since_id" type="number">
  Return only alerts with an ID greater than this value. Use the highest `id` from your last response to implement incremental polling without re-fetching previously seen alerts.
</ParamField>

<ParamField query="timeframe" default="all" type="string">
  Filter by timeframe. Pass `all` to return alerts across all timeframes, or a specific code such as `D`, `W`, `M`, `Q`, `Y`, `60`, `30`, `15`.
</ParamField>

<ParamField query="direction" default="all" type="string">
  Filter by alert direction. Valid values: `all`, `bullish`, `bearish`.
</ParamField>

<ParamField query="cc" default="all" type="string">
  Filter by candle state (CC field). Pass `all` to skip filtering, or a specific candle state string.
</ParamField>

### Response fields

<ResponseField name="items" type="object[]" required>
  Array of in-force alert objects.

  <Expandable title="in-force alert object">
    <ResponseField name="id" type="number" required>
      Unique alert ID. Use this value with `since_id` for incremental polling.
    </ResponseField>

    <ResponseField name="symbol" type="string" required>
      Ticker symbol.
    </ResponseField>

    <ResponseField name="timeframe" type="string" required>
      Timeframe on which the setup went in force (e.g., `D`, `W`, `60`).
    </ResponseField>

    <ResponseField name="direction" type="string" required>
      `bullish` or `bearish`.
    </ResponseField>

    <ResponseField name="shape" type="string" required>
      Setup shape label (e.g., `1-2U`, `2-1`).
    </ResponseField>

    <ResponseField name="price" type="number" required>
      Price at which the alert triggered.
    </ResponseField>

    <ResponseField name="triggered_at" type="string" required>
      ISO 8601 timestamp (UTC) when the alert fired.
    </ResponseField>

    <ResponseField name="cc" type="string" required>
      Candle state at the time of the alert.
    </ResponseField>
  </Expandable>
</ResponseField>

### Code examples

<CodeGroup>
  ```bash curl theme={null}
  curl -G "https://app.stratalerts.com/api/market/v1/alerts/in-force" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    --data-urlencode "timeframe=D" \
    --data-urlencode "direction=bullish" \
    --data-urlencode "window_minutes=60" \
    --data-urlencode "limit=50"
  ```

  ```python python theme={null}
  import requests

  last_seen_id = 0  # persist this between polls

  resp = requests.get(
      "https://app.stratalerts.com/api/market/v1/alerts/in-force",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params={
          "timeframe": "D",
          "direction": "bullish",
          "window_minutes": 60,
          "limit": 50,
          "since_id": last_seen_id,
      },
  )
  resp.raise_for_status()
  data = resp.json()

  for alert in data["items"]:
      print(alert["symbol"], alert["timeframe"], alert["shape"], alert["price"])
      last_seen_id = max(last_seen_id, alert["id"])
  ```

  ```javascript javascript theme={null}
  let lastSeenId = 0; // persist between polls

  const params = new URLSearchParams({
    timeframe: "D",
    direction: "bullish",
    window_minutes: "60",
    limit: "50",
    since_id: String(lastSeenId),
  });
  const resp = await fetch(
    `https://app.stratalerts.com/api/market/v1/alerts/in-force?${params}`,
    { headers: { Authorization: "Bearer YOUR_API_KEY" } }
  );
  const data = await resp.json();

  data.items.forEach((alert) => {
    console.log(alert.symbol, alert.timeframe, alert.shape, alert.price);
    lastSeenId = Math.max(lastSeenId, alert.id);
  });
  ```
</CodeGroup>

### Example response

```json theme={null}
{
  "items": [
    {
      "id": 98421,
      "symbol": "AAPL",
      "timeframe": "D",
      "direction": "bullish",
      "shape": "1-2U",
      "price": 214.32,
      "triggered_at": "2026-04-10T13:45:22Z",
      "cc": "2U"
    },
    {
      "id": 98398,
      "symbol": "SPY",
      "timeframe": "D",
      "direction": "bullish",
      "shape": "2-2U",
      "price": 532.10,
      "triggered_at": "2026-04-10T13:31:05Z",
      "cc": "2U"
    }
  ]
}
```

***

## GET /alerts/simultaneous-breaks

Returns simultaneous break alert events. A simultaneous break fires when multiple tracked index futures (ES, NQ, RTY, YM) all break the same direction within the detection window. Use this endpoint to identify moments when the broad market is moving in a coordinated fashion.

**`GET https://app.stratalerts.com/api/market/v1/alerts/simultaneous-breaks`**

<Note>
  Requires scope: `alerts:read`
</Note>

### Request parameters

<ParamField query="window_minutes" type="number">
  How far back in time (in minutes) to look for simultaneous break events. When omitted, the server's default window applies.
</ParamField>

<ParamField query="limit" type="number">
  Maximum number of events to return.
</ParamField>

<ParamField query="since_id" type="number">
  Return only events with an ID greater than this value. Use for incremental polling.
</ParamField>

<ParamField query="timeframe" default="all" type="string">
  Filter by timeframe. Pass `all` or a specific timeframe code (e.g., `D`, `W`).
</ParamField>

<ParamField query="direction" default="all" type="string">
  Filter by break direction. Valid values: `all`, `bullish`, `bearish`.
</ParamField>

<ParamField query="threshold" default="all" type="string">
  Filter by the number of participating instruments. Pass `all` to return all events, or a numeric string (`2`, `3`, `4`) to filter by the exact break count.
</ParamField>

### Response fields

<ResponseField name="items" type="object[]" required>
  Array of simultaneous break alert objects.

  <Expandable title="simultaneous break object">
    <ResponseField name="id" type="number" required>
      Unique event ID. Use with `since_id` for incremental polling.
    </ResponseField>

    <ResponseField name="timeframe" type="string" required>
      Timeframe on which the simultaneous break was detected.
    </ResponseField>

    <ResponseField name="direction" type="string" required>
      `bullish` or `bearish`.
    </ResponseField>

    <ResponseField name="threshold" type="number" required>
      Number of index futures that broke in the same direction (2, 3, or 4).
    </ResponseField>

    <ResponseField name="symbols" type="string[]" required>
      List of the symbol tickers that participated in the break.
    </ResponseField>

    <ResponseField name="triggered_at" type="string" required>
      ISO 8601 timestamp (UTC) when the event fired.
    </ResponseField>
  </Expandable>
</ResponseField>

### Code examples

<CodeGroup>
  ```bash curl theme={null}
  curl -G "https://app.stratalerts.com/api/market/v1/alerts/simultaneous-breaks" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    --data-urlencode "direction=bullish" \
    --data-urlencode "threshold=3" \
    --data-urlencode "window_minutes=120"
  ```

  ```python python theme={null}
  import requests

  resp = requests.get(
      "https://app.stratalerts.com/api/market/v1/alerts/simultaneous-breaks",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params={"direction": "bullish", "threshold": "3", "window_minutes": 120},
  )
  resp.raise_for_status()
  data = resp.json()

  for event in data["items"]:
      symbols = ", ".join(event["symbols"])
      print(f"{event['triggered_at']} — {event['threshold']}/4 {event['direction']} ({symbols})")
  ```

  ```javascript javascript theme={null}
  const params = new URLSearchParams({
    direction: "bullish",
    threshold: "3",
    window_minutes: "120",
  });
  const resp = await fetch(
    `https://app.stratalerts.com/api/market/v1/alerts/simultaneous-breaks?${params}`,
    { headers: { Authorization: "Bearer YOUR_API_KEY" } }
  );
  const data = await resp.json();

  data.items.forEach(({ triggered_at, threshold, direction, symbols }) => {
    console.log(`${triggered_at} — ${threshold}/4 ${direction} (${symbols.join(", ")})`);
  });
  ```
</CodeGroup>

### Example response

```json theme={null}
{
  "items": [
    {
      "id": 4112,
      "timeframe": "D",
      "direction": "bullish",
      "threshold": 3,
      "symbols": ["ES1!", "NQ1!", "YM1!"],
      "triggered_at": "2026-04-10T13:35:00Z"
    },
    {
      "id": 4089,
      "timeframe": "D",
      "direction": "bullish",
      "threshold": 4,
      "symbols": ["ES1!", "NQ1!", "RTY1!", "YM1!"],
      "triggered_at": "2026-04-10T09:32:15Z"
    }
  ]
}
```

***

## Error codes

Both alerts endpoints use the same error format.

| HTTP status | Error code             | Meaning                                               |
| ----------- | ---------------------- | ----------------------------------------------------- |
| 401         | `missing_api_key`      | No API key was provided or the key format is invalid. |
| 403         | `inactive_entitlement` | Your account does not have an active API entitlement. |
| 403         | `missing_scope`        | Your API key does not have the `alerts:read` scope.   |

Error responses use the following shape:

```json theme={null}
{
  "error": {
    "code": "missing_scope",
    "message": "missing scope"
  }
}
```

<Tip>
  For real-time delivery, use the WebSocket channels `alerts.in_force` and `alerts.simultaneous_breaks` instead of polling. The REST endpoints are best suited for backfilling missed events or building an alert history log.
</Tip>