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

# Insider Transactions

> Get recent insider trading activity for a company

## Overview

Retrieve recent insider trading transactions for any publicly traded company. This endpoint provides information about stock purchases, sales, and other transactions by company insiders including executives, directors, and large shareholders.

<Info>
  This endpoint uses YFinance data. Insider trading data helps investors understand sentiment and potential future performance based on insider activity.
</Info>

## Parameters

<ParamField path="symbol" type="string" required>
  Stock ticker symbol (e.g., AAPL, MSFT, GOOGL, TSLA)
</ParamField>

## Response

<ResponseField name="symbol" type="string">
  The stock ticker symbol
</ResponseField>

<ResponseField name="company_name" type="string">
  Full company name
</ResponseField>

<ResponseField name="insider_transactions" type="array">
  Array of recent insider transactions

  <Expandable title="Transaction Object">
    <ResponseField name="insider" type="string">
      Name of the insider (executive, director, etc.)
    </ResponseField>

    <ResponseField name="relation" type="string">
      Relationship to company (e.g., "CEO", "Director", "10% Owner")
    </ResponseField>

    <ResponseField name="transaction" type="string">
      Type of transaction (e.g., "Sale", "Purchase", "Option Exercise")
    </ResponseField>

    <ResponseField name="cost" type="number">
      Transaction cost/price per share
    </ResponseField>

    <ResponseField name="shares" type="number">
      Number of shares involved in transaction
    </ResponseField>

    <ResponseField name="value" type="number">
      Total transaction value (shares × cost)
    </ResponseField>

    <ResponseField name="shares_owned_following" type="number">
      Total shares owned by insider after transaction
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total_transactions" type="number">
  Total number of transactions returned
</ResponseField>

<ResponseField name="timestamp" type="string">
  ISO timestamp of the response
</ResponseField>

<ResponseField name="source" type="string">
  Data source identifier ("YFinance")
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://stocks-dev.up.railway.app/api/v1/stock/AAPL/insider-transactions"
  ```

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

  response = requests.get("https://stocks-dev.up.railway.app/api/v1/stock/AAPL/insider-transactions")
  data = response.json()

  print(f"Insider Transactions for {data['company_name']}:")
  for transaction in data['insider_transactions'][:3]:  # Show first 3
      print(f"- {transaction['insider']}: {transaction['transaction']}")
      print(f"  Shares: {transaction['shares']:,} at ${transaction['cost']:.2f}")
      print(f"  Value: ${transaction['value']:,.2f}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://stocks-dev.up.railway.app/api/v1/stock/AAPL/insider-transactions');
  const data = await response.json();

  console.log(`Insider Transactions for ${data.company_name}:`);
  data.insider_transactions.slice(0, 3).forEach(transaction => {
      console.log(`- ${transaction.insider}: ${transaction.transaction}`);
      console.log(`  Shares: ${transaction.shares.toLocaleString()} at $${transaction.cost.toFixed(2)}`);
      console.log(`  Value: $${transaction.value.toLocaleString()}`);
  });
  ```

  ```php PHP theme={null}
  <?php
  $response = file_get_contents('https://stocks-dev.up.railway.app/api/v1/stock/AAPL/insider-transactions');
  $data = json_decode($response, true);

  echo "Insider Transactions for " . $data['company_name'] . ":\n";
  foreach (array_slice($data['insider_transactions'], 0, 3) as $transaction) {
      echo "- " . $transaction['insider'] . ": " . $transaction['transaction'] . "\n";
      echo "  Shares: " . number_format($transaction['shares']) . " at $" . $transaction['cost'] . "\n";
      echo "  Value: $" . number_format($transaction['value']) . "\n";
  }
  ?>
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "symbol": "AAPL",
  "company_name": "Apple Inc.",
  "insider_transactions": [
    {
      "insider": "Timothy D Cook",
      "relation": "CEO",
      "transaction": "Sale",
      "cost": 189.84,
      "shares": 511000,
      "value": 97049440,
      "shares_owned_following": 3204462
    },
    {
      "insider": "Katherine L Adams", 
      "relation": "Senior Vice President",
      "transaction": "Sale",
      "cost": 186.74,
      "shares": 25000,
      "value": 4668500,
      "shares_owned_following": 427334
    },
    {
      "insider": "Luca Maestri",
      "relation": "Chief Financial Officer", 
      "transaction": "Sale",
      "cost": 185.73,
      "shares": 96735,
      "value": 17969528,
      "shares_owned_following": 110673
    }
  ],
  "total_transactions": 10,
  "timestamp": "2025-06-28T19:30:15.123456",
  "source": "YFinance"
}
```

## Use Cases

<AccordionGroup>
  <Accordion title="Investment Research">
    * **Insider Sentiment**: Large sales by executives may indicate overvaluation
    * **Confidence Signals**: Insider purchases often signal confidence in company prospects
    * **Timing Analysis**: Track patterns in insider trading around earnings or events
  </Accordion>

  <Accordion title="Risk Assessment">
    * **Executive Behavior**: Monitor if leadership is reducing their holdings
    * **Diversification**: Understand if sales are for portfolio diversification
    * **Regulatory Compliance**: Track required disclosures and filings
  </Accordion>

  <Accordion title="Market Intelligence">
    * **Industry Trends**: Compare insider activity across sector competitors
    * **Compensation Analysis**: Understand stock-based compensation patterns
    * **Corporate Governance**: Monitor director and officer trading patterns
  </Accordion>
</AccordionGroup>

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid Symbol (404)">
    ```json theme={null}
    {
      "error": "Failed to fetch insider transactions for INVALID"
    }
    ```
  </Accordion>

  <Accordion title="No Data Available (200)">
    ```json theme={null}
    {
      "symbol": "NEWCO",
      "company_name": "New Company Inc.",
      "insider_transactions": "No insider transaction data available",
      "timestamp": "2025-06-28T19:30:15.123456",
      "source": "YFinance"
    }
    ```
  </Accordion>

  <Accordion title="Rate Limited (429)">
    ```json theme={null}
    {
      "error": "Rate limit exceeded",
      "detail": "YFinance rate limited. Please try again later.",
      "retry_after": 60
    }
    ```
  </Accordion>
</AccordionGroup>

## Important Notes

<Warning>
  **Data Limitations**: Insider trading data depends on SEC filings and may have delays. Not all transactions may be immediately available.
</Warning>

<Info>
  **Regulatory Context**: Insider transactions are regulated by the SEC and must be reported within specific timeframes. This data reflects publicly disclosed transactions only.
</Info>

<Tip>
  **Analysis Tips**:

  * Focus on patterns rather than individual transactions
  * Consider the insider's role and typical trading behavior
  * Look at transaction timing relative to company events
</Tip>

## MCP Protocol Usage

For AI agents using the Model Context Protocol:

```json theme={null}
{
  "method": "tools/call",
  "params": {
    "name": "get_insider_transactions",
    "arguments": {
      "symbol": "AAPL"
    }
  }
}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Stock Quote" icon="chart-line" href="/api-reference/stock/quote">
    Get current stock price and market data
  </Card>

  <Card title="Company Overview" icon="building" href="/api-reference/stock/overview">
    Get comprehensive company information
  </Card>

  <Card title="Analyst Recommendations" icon="star" href="/api-reference/stock/recommendations">
    Get analyst buy/sell recommendations
  </Card>

  <Card title="Government Trades" icon="bank" href="/api-reference/fmp/government-trades">
    Track Congressional and Senate trading activity
  </Card>
</CardGroup>