Skip to main content
Proxy statements (DEF 14A) contain detailed executive compensation tables. This tutorial shows how to retrieve structured compensation data and compare the latest two disclosures for an issuer without manually reading proxy filings.

Prerequisites

  • An SEC API key (set as SECAPI_API_KEY)
  • Basic familiarity with REST APIs
  • (Optional) Python 3.8+ or Node.js 18+ for SDK examples

Step 1 — Retrieve compensation for a single company

Use /v1/compensation to get the latest executive compensation data for a company.

curl

curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/compensation?ticker=AAPL"

Python

import os

from secapi_client import SecApiClient

client = SecApiClient(api_key=os.environ["SECAPI_API_KEY"])

comp = client.compensation(ticker="AAPL")

for executive in comp["data"]:
    print(f"{executive['executiveName']} ({executive['roleTitle']})")
    print(f"  Salary:       ${executive['salaryUsd'] or 0:>14,.0f}")
    print(f"  Bonus:        ${executive['bonusUsd'] or 0:>14,.0f}")
    print(f"  Stock Awards: ${executive['stockAwardsUsd'] or 0:>14,.0f}")
    print(f"  Total:        ${executive['totalUsd'] or 0:>14,.0f}")
    print()

JavaScript

import { SecApiClient } from "@secapi/sdk-js";

const client = new SecApiClient({
  apiKey: process.env.SECAPI_API_KEY!,
});

const comp = await client.compensation({ ticker: "AAPL" });

for (const exec of comp.data) {
  console.log(`${exec.executiveName} (${exec.roleTitle})`);
  console.log(`  Salary:       $${(exec.salaryUsd ?? 0).toLocaleString()}`);
  console.log(`  Bonus:        $${(exec.bonusUsd ?? 0).toLocaleString()}`);
  console.log(`  Stock Awards: $${(exec.stockAwardsUsd ?? 0).toLocaleString()}`);
  console.log(`  Total:        $${(exec.totalUsd ?? 0).toLocaleString()}`);
  console.log();
}

Expected output

Tim Cook (Chief Executive Officer)
  Salary:       $    3,000,000
  Bonus:        $            0
  Stock Awards: $   40,000,000
  Total:        $   63,209,000

Luca Maestri (SVP, Chief Financial Officer)
  Salary:       $    1,000,000
  Bonus:        $            0
  Stock Awards: $   20,000,000
  Total:        $   26,900,000

Step 2 — Compare the latest two disclosures

The /v1/compensation/compare endpoint compares the latest two executive compensation disclosures for one issuer.

curl

curl -H "x-api-key: $SECAPI_API_KEY" \
  -H "content-type: application/json" \
  -X POST \
  -d '{"ticker":"AAPL","limit":10}' \
  "https://api.secapi.ai/v1/compensation/compare"

Python

comparison = client.compare_compensation(ticker="AAPL", limit=10)

print(f"{'Executive':<25} {'Latest':>15} {'Prior':>15}")
print("-" * 55)

for entry in comparison["rows"]:
    print(f"{entry['executiveName']:<25} ${entry['currentTotalUsd'] or 0:>14,.0f} ${entry['previousTotalUsd'] or 0:>14,.0f}")

JavaScript

const comparison = await client.compareCompensation({ ticker: "AAPL", limit: 10 });

console.log("Executive                 Latest          Prior");
console.log("-".repeat(55));

for (const entry of comparison.rows) {
  console.log(
    `${entry.executiveName.padEnd(25)} $${(entry.currentTotalUsd ?? 0).toLocaleString().padStart(14)} $${(entry.previousTotalUsd ?? 0).toLocaleString().padStart(14)}`
  );
}

Expected output

Executive                 Latest          Prior
-------------------------------------------------------
Tim Cook                  $   63,209,000 $   49,000,000
Luca Maestri              $   26,900,000 $   26,100,000

Step 3 — Analyze compensation composition

Break down the mix of salary, equity, and performance-based pay to understand how compensation is structured.

Python

comp = client.compensation(ticker="MSFT")

for executive in comp["data"][:3]:  # top 3 executives
    total = executive["totalUsd"] or 1
    salary_pct = ((executive["salaryUsd"] or 0) / total) * 100
    equity_pct = ((executive["stockAwardsUsd"] or 0) / total) * 100
    other_pct = 100 - salary_pct - equity_pct

    print(f"{executive['executiveName']} ({executive['roleTitle']})")
    print(f"  Total: ${executive['totalUsd'] or 0:,.0f}")
    print(f"  Salary:  {salary_pct:5.1f}%  |  Equity: {equity_pct:5.1f}%  |  Other: {other_pct:5.1f}%")
    print()

Expected output

Satya Nadella (Chairman and Chief Executive Officer)
  Total: $48,500,000
  Salary:    5.2%  |  Equity:  82.5%  |  Other:  12.3%

Amy Hood (EVP, Chief Financial Officer)
  Total: $25,300,000
  Salary:    3.9%  |  Equity:  79.1%  |  Other:  17.0%

Bradford Smith (Vice Chair and President)
  Total: $22,100,000
  Salary:    4.5%  |  Equity:  77.3%  |  Other:  18.2%

Next steps

  • Track compensation trends: Pull historical data to see how executive pay has changed year over year.
  • Screen by pay ratio: Combine compensation data with employee count from 10-K filings to calculate CEO-to-median-worker pay ratios.
  • Build peer benchmarks: Group companies by sector and market cap to create meaningful compensation benchmarks.
See the Compensation Workflows guide for additional patterns.