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

# Setups

> Retrieve active Strat setups for any combination of symbols and timeframes. Filter to a subset or pull the full tracked universe in one paginated request.

## Query current active setups across symbols

The setups endpoint returns the currently active setup records — the same data that populates the Setups Table in the StratAlerts UI. Each item represents one setup on one timeframe for one symbol, and includes candle state, in-force status, P3 and PMG indicators, setup shape, and sector classification. You can scope the results to specific symbols or timeframes, or omit filters to retrieve the full active universe up to your `limit`.

**`GET https://app.stratalerts.com/api/market/v1/setups/current`**

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

## Request parameters

<ParamField query="symbols" type="string">
  Comma-separated list of ticker symbols to filter by (e.g., `AAPL,MSFT,SPY`). When provided, only setups for those symbols are returned. Symbols are normalized to uppercase. Maximum 250.
</ParamField>

<ParamField query="timeframes" type="string">
  Comma-separated list of timeframe codes to filter by (e.g., `D,W,M`). When provided, only setups on those timeframes are returned. Valid timeframe codes: `15`, `30`, `60`, `4H`, `D`, `W`, `M`, `Q`, `Y`.
</ParamField>

<ParamField query="limit" default="100" type="number">
  Maximum number of setup rows to return. Results are ordered by symbol then timeframe before the limit is applied.
</ParamField>

## Response fields

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

  <Expandable title="setup object">
    <ResponseField name="symbol" type="string" required>
      Ticker symbol.
    </ResponseField>

    <ResponseField name="timeframe" type="string" required>
      Timeframe code (e.g., `D`, `W`, `60`).
    </ResponseField>

    <ResponseField name="shape" type="string" required>
      Human-readable setup shape label combining the C2-C1 sequence (e.g., `1-2U`, `2D-3`, `1-2D`).
    </ResponseField>

    <ResponseField name="in_force" type="boolean" required>
      `true` if the setup is currently in force — price has crossed the trigger level and the trade is active.
    </ResponseField>

    <ResponseField name="p3" type="boolean" required>
      `true` if a P3 (potential 3) scenario is present — the current candle is an outside bar.
    </ResponseField>

    <ResponseField name="pmg" type="number | null">
      The Potential Max Gain price level for this setup, or `null` if not applicable.
    </ResponseField>

    <ResponseField name="continuation" type="boolean" required>
      `true` if the setup is a continuation — the C1 and CC candles are both the same directional 2 candle.
    </ResponseField>

    <ResponseField name="sector" type="string" required>
      GICS sector of the underlying symbol.
    </ResponseField>
  </Expandable>
</ResponseField>

<Tip>
  Results are ordered alphabetically by symbol, then by timeframe, before the `limit` is applied. If you need a specific subset, always pass `symbols` and/or `timeframes` to avoid truncation.
</Tip>

## Code examples

<CodeGroup>
  ```bash curl theme={null}
  curl -G "https://app.stratalerts.com/api/market/v1/setups/current" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    --data-urlencode "symbols=AAPL,MSFT" \
    --data-urlencode "timeframes=D,W" \
    --data-urlencode "limit=50"
  ```

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

  resp = requests.get(
      "https://app.stratalerts.com/api/market/v1/setups/current",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params={"symbols": "AAPL,MSFT", "timeframes": "D,W", "limit": 50},
  )
  resp.raise_for_status()
  data = resp.json()

  for setup in data["items"]:
      in_force = "IN FORCE" if setup["in_force"] else ""
      print(f"{setup['symbol']} {setup['timeframe']} {setup['shape']} {in_force}")
  ```

  ```javascript javascript theme={null}
  const params = new URLSearchParams({
    symbols: "AAPL,MSFT",
    timeframes: "D,W",
    limit: "50",
  });
  const resp = await fetch(
    `https://app.stratalerts.com/api/market/v1/setups/current?${params}`,
    { headers: { Authorization: "Bearer YOUR_API_KEY" } }
  );
  const data = await resp.json();

  data.items.forEach(({ symbol, timeframe, shape, in_force }) => {
    const flag = in_force ? "IN FORCE" : "";
    console.log(symbol, timeframe, shape, flag);
  });
  ```
</CodeGroup>

## Example response

```json theme={null}
{
  "items": [
    {
      "symbol": "AAPL",
      "timeframe": "D",
      "shape": "1-2U",
      "in_force": true,
      "p3": false,
      "pmg": null,
      "continuation": false,
      "sector": "Information Technology"
    },
    {
      "symbol": "AAPL",
      "timeframe": "W",
      "shape": "1-2D",
      "in_force": false,
      "p3": true,
      "pmg": 210.00,
      "continuation": false,
      "sector": "Information Technology"
    },
    {
      "symbol": "MSFT",
      "timeframe": "D",
      "shape": "2U-2U",
      "in_force": false,
      "p3": false,
      "pmg": null,
      "continuation": true,
      "sector": "Information Technology"
    }
  ]
}
```

## Error codes

| 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 `states:read` scope.   |

Error responses use the following shape:

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