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

# Compare Executive Compensation

> Compare executive compensation disclosures using the SEC API. Pull salary, bonus, stock awards, and total comp data. Includes curl, Python, and JavaScript examples.

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

```bash theme={null}
curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/compensation?ticker=AAPL"
```

### Python

```python theme={null}
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

```ts theme={null}
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

```bash theme={null}
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

```python theme={null}
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

```ts theme={null}
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

```python theme={null}
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](/compensation-workflows) guide for additional patterns.