How to Access Institutional Holdings and Short Interest Data with the Mboum API

Analyzing where "smart money" is moving and gauging market sentiment are critical components of algorithmic trading and financial analysis. Institutional holdings reveal the confidence level of major funds, while short interest data provides insight into bearish sentiment and potential short squeeze scenarios.

By integrating the Mboum API, developers can programmatically access these datasets to build screeners, dashboards, or trading bots.

You can obtain your API key here:
https://mboum.com/pages/api

The Endpoints

To analyze the complete market picture for a specific equity, we will utilize two specific endpoints from the Stocks collection.

1. Institutional Holdings

To retrieve data regarding ownership percentages and active positions by large funds, use the following endpoint:

GET /v2/institutional-holdings

This provides a summary of shares held, as well as a breakdown of increased, decreased, and new positions.

Documentation:
https://docs.mboum.com/#stocks-options-get-api-v2-institutional-holdings

Parameters

• Key Parameter: ticker (e.g., GME, TSLA)

• Optional Parameter: type (filters by TOTAL, INCREASED, NEW, etc.)

2. Short Interest

To access data regarding shares sold short, days to cover, and settlement dates, use the following endpoint:

GET /v2/short-interest

High short interest relative to the float is a primary indicator used to identify potential volatility.

Documentation:
https://docs.mboum.com#stocks-options-GETapi-v2-markets-stock-short-interest

Parameters

• Key Parameter: ticker (e.g., GME)

Python Example

The following script demonstrates how to fetch both institutional ownership summary data and the latest short interest figures for GameStop (GME).

import requests
import json

# Configuration
auth_key = "YOUR_AUTH_KEY"
symbol = "GME"

headers = {
    'Authorization': f'Bearer {auth_key}'
}

def get_institutional_data(ticker):
    url = "https://api.mboum.com/v2/markets/stock/institutional-holdings"
    params = {
        'ticker': ticker,
        'type': 'TOTAL'
    }
    response = requests.get(url, headers=headers, params=params)
    if response.status_code == 200:
        return response.json()
    return None

def get_short_data(ticker):
    url = "https://api.mboum.com/v2/markets/stock/short-interest"
    params = {
        'ticker': ticker,
        'type': 'STOCKS'
    }
    response = requests.get(url, headers=headers, params=params)
    if response.status_code == 200:
        return response.json()
    return None

# Fetch Data
holdings = get_institutional_data(symbol)
short_interest = get_short_data(symbol)

# Parse and Print Institutional Summary
if holdings and 'body' in holdings:
    summary = holdings['body'].get('ownershipSummary', {})
    pct_held = summary.get('SharesOutstandingPCT', {}).get('value', 'N/A')
    print(f"--- {symbol} Institutional Holdings ---")
    print(f"Percentage Held: {pct_held}")

# Parse and Print Latest Short Interest
if short_interest and 'body' in short_interest:
    # The API returns a list; the first item is the most recent settlement date
    latest_short = short_interest['body'][0]
    print(f"\n--- {symbol} Short Interest Data ---")
    print(f"Settlement Date: {latest_short.get('settlementDate')}")
    print(f"Short Interest: {latest_short.get('interest')}")
    print(f"Days To Cover: {latest_short.get('daysToCover')}")

Understanding the Response

The API returns structured JSON data. Below is a breakdown of the critical fields you will encounter when analyzing the responses.

Institutional Holdings Response

The GET /v2/institutional-holdings endpoint returns a nested object. The ownershipSummary object is particularly useful for a high-level overview.

• SharesOutstandingPCT – The percentage of the total float held by institutions

• TotalHoldingsValue – The total market value of these holdings (in millions)

• activePositions – A breakdown of holders who have Increased, Decreased, or Held their positions

Short Interest Response

The GET /v2/short-interest endpoint returns an array of historical short data objects. The index 0 represents the most recent report.

• settlementDate – The date on which the short interest was reported

• interest – The total number of shares currently sold short

• avgDailyShareVolume – The average number of shares traded daily

• daysToCover – A ratio calculated by dividing interest by avgDailyShareVolume. This indicates how many days it would take for short sellers to cover their positions if price action turns against them

Practical Use Cases

Short Squeeze Detection

By monitoring the daysToCover and raw interest fields, traders can identify stocks where short sellers are over-leveraged. If daysToCover is high (typically above 10) and the stock price begins to rise, short sellers may be forced to buy back shares to close positions, fueling a rapid price increase.

Analyzing Institutional Confidence

The SharesOutstandingPCT field in the institutional holdings data serves as a proxy for long-term market confidence. High institutional ownership often suggests stability and lower volatility, as funds tend to hold for longer periods. Conversely, a sudden drop in the Decreased Positions count within the activePositions object can signal that institutions are liquidating assets.

Conclusion

Combining institutional ownership data with short interest metrics provides a comprehensive view of market positioning. This data allows investors to see both the long-term confidence of major funds and the bearish bets placed against a stock.

To start integrating this data into your financial applications:

Get your free API key:
https://mboum.com/pages/api