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

# Instruments

> Look up instrument metadata — name, exchange, sector, asset type, and active status — for one symbol or an entire batch of up to 250 tickers at once.

## Search and retrieve ticker metadata

The instruments endpoints give you structured metadata for any symbol in the StratAlerts universe. Use the list endpoint to search or filter by symbol, then use the detail endpoint when you need a single record by exact ticker. Both endpoints require the `metadata:read` scope and return the same object shape.

***

## GET /instruments

Returns a paginated list of instruments. You can filter by a comma-separated set of symbols, run a prefix/substring search, or simply page through the full universe.

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

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

### Request parameters

<ParamField query="symbols" type="string">
  Comma-separated list of ticker symbols to retrieve. Symbols are normalized to uppercase. Maximum 250. When provided alongside `search`, only symbols that also match the search string are returned.
</ParamField>

<ParamField query="search" type="string">
  Substring filter applied to the symbol field (case-insensitive). Useful for finding symbols when you only know part of the ticker.
</ParamField>

<ParamField query="limit" default="50" type="number">
  Maximum number of instruments to return. Clamped to the range `1–200`.
</ParamField>

### Response fields

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

  <Expandable title="instrument object">
    <ResponseField name="symbol" type="string" required>
      Ticker symbol, uppercased (e.g., `AAPL`).
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Full company or instrument name.
    </ResponseField>

    <ResponseField name="market" type="string" required>
      Asset class: `stocks`, `futures`, `crypto`, or empty string if unknown.
    </ResponseField>

    <ResponseField name="exchange" type="string" required>
      Primary exchange abbreviation (e.g., `NASDAQ`, `NYSE`).
    </ResponseField>

    <ResponseField name="type" type="string" required>
      Instrument type string from the underlying data provider (e.g., `CS` for common stock).
    </ResponseField>

    <ResponseField name="sector" type="string" required>
      GICS sector name, or empty string for instruments without sector classification.
    </ResponseField>

    <ResponseField name="active" type="boolean" required>
      `true` if the symbol is actively tracked and receiving data.
    </ResponseField>
  </Expandable>
</ResponseField>

### Code examples

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

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

  resp = requests.get(
      "https://app.stratalerts.com/api/market/v1/instruments",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params={"symbols": "AAPL,MSFT,NVDA", "limit": 10},
  )
  resp.raise_for_status()
  data = resp.json()
  for instrument in data["items"]:
      print(instrument["symbol"], instrument["name"])
  ```

  ```javascript javascript theme={null}
  const resp = await fetch(
    "https://app.stratalerts.com/api/market/v1/instruments?symbols=AAPL,MSFT,NVDA&limit=10",
    { headers: { Authorization: "Bearer YOUR_API_KEY" } }
  );
  const data = await resp.json();
  data.items.forEach(({ symbol, name }) => console.log(symbol, name));
  ```
</CodeGroup>

### Example response

```json theme={null}
{
  "items": [
    {
      "symbol": "AAPL",
      "name": "Apple Inc.",
      "market": "stocks",
      "exchange": "NASDAQ",
      "type": "CS",
      "sector": "Information Technology",
      "active": true
    },
    {
      "symbol": "MSFT",
      "name": "Microsoft Corporation",
      "market": "stocks",
      "exchange": "NASDAQ",
      "type": "CS",
      "sector": "Information Technology",
      "active": true
    }
  ]
}
```

***

## GET /instruments/{symbol}

Returns a single instrument by its exact ticker symbol. The symbol in the path is normalized to uppercase before lookup.

**`GET https://app.stratalerts.com/api/market/v1/instruments/{symbol}`**

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

### Path parameters

<ParamField path="symbol" type="string" required>
  The ticker symbol to look up (e.g., `AAPL`). Case-insensitive — the server normalizes to uppercase.
</ParamField>

### Response fields

Returns a single instrument object with the same fields as the list response above: `symbol`, `name`, `market`, `exchange`, `type`, `sector`, and `active`.

### Code examples

<CodeGroup>
  ```bash curl theme={null}
  curl "https://app.stratalerts.com/api/market/v1/instruments/AAPL" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

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

  resp = requests.get(
      "https://app.stratalerts.com/api/market/v1/instruments/AAPL",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
  )
  resp.raise_for_status()
  instrument = resp.json()
  print(instrument["symbol"], instrument["sector"])
  ```

  ```javascript javascript theme={null}
  const resp = await fetch(
    "https://app.stratalerts.com/api/market/v1/instruments/AAPL",
    { headers: { Authorization: "Bearer YOUR_API_KEY" } }
  );
  const instrument = await resp.json();
  console.log(instrument.symbol, instrument.sector);
  ```
</CodeGroup>

### Example response

```json theme={null}
{
  "symbol": "AAPL",
  "name": "Apple Inc.",
  "market": "stocks",
  "exchange": "NASDAQ",
  "type": "CS",
  "sector": "Information Technology",
  "active": true
}
```

***

## 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 `metadata:read` scope.      |
| 404         | `unknown_symbol`       | The requested symbol was not found (detail endpoint only). |

Error responses use the following shape:

```json theme={null}
{
  "error": {
    "code": "unknown_symbol",
    "message": "unknown symbol"
  }
}
```