ceorater

# CEORater Skill

Query CEO performance data for S&P 500 and major U.S. public companies via the CEORater API.

## Prerequisites

1. Get an API key at https://www.ceorater.com/api-docs.html ($99/month per user)
2. Set the environment variable: `CEORATER_API_KEY=zpka_your_key_here`

**Licensing Note:** Self-serve API access permits individual research and analysis. Integrating CEORater data into proprietary firm models, AI/ML training, or building products requires an Enterprise Agreement — contact sales@ceorater.com.

## Available Metrics

| Metric | Range | Description |
|--------|-------|-------------|
| CEORaterScore | 0-100 | Composite CEO effectiveness rating |
| AlphaScore | 0-100 | Performance vs. market benchmark |
| RevenueCAGRScore | 0-100 | Tenure-adjusted revenue growth percentile |
| CompScore | A-F | Compensation efficiency grade |
| TSR During Tenure | % | Total Stock Return during CEO tenure |
| TSR vs. S&P 500 | % | Performance relative to S&P 500 (SPY) |
| CEO Compensation | $M | Total compensation from most recent proxy filing |
| Revenue CAGR | % | Tenure-adjusted compound annual revenue growth |

## API Endpoints

### Get Company by Ticker
```bash
curl -H "Authorization: Bearer $CEORATER_API_KEY" \
  "https://api.ceorater.com/v1/company/AAPL?format=raw"
```

### Search Companies
```bash
curl -H "Authorization: Bearer $CEORATER_API_KEY" \
  "https://api.ceorater.com/v1/search?q=technology&format=raw"
```

### List All Companies
```bash
curl -H "Authorization: Bearer $CEORATER_API_KEY" \
  "https://api.ceorater.com/v1/companies?limit=100&format=raw"
```

### Health Check (no auth required)
```bash
curl "https://api.ceorater.com/status"
```

## Usage Instructions

When the user asks about CEO performance, ratings, or executive compensation:

1. **Single company lookup:** Use the `/v1/company/{ticker}` endpoint
2. **Sector/industry analysis:** Use `/v1/search?q={query}` 
3. **Bulk data:** Use `/v1/companies?limit=N`

Always use `format=raw` for numeric values suitable for calculations.

### Example Queries

- "What's the CEORaterScore for Apple?" → GET /v1/company/AAPL
- "Show me technology sector CEOs" → GET /v1/search?q=technology
- "Who are the top-rated CEOs?" → GET /v1/companies, sort by ceoraterScore
- "Compare Tim Cook vs Satya Nadella" → GET /v1/company/AAPL and /v1/company/MSFT

## Response Format (raw)

```json
{
  "companyName": "Apple Inc.",
  "ticker": "AAPL",
  "sector": "Technology",
  "industry": "Computer Manufacturing",
  "ceo": "Tim Cook",
  "founderCEO": false,
  "ceoraterScore": 87,
  "alphaScore": 93.5,
  "revenueCagrScore": 75.2,
  "revenueCagr": 0.042,
  "compScore": "C",
  "tsrMultiple": 22.23,
  "tenureYears": 14.4,
  "avgAnnualTsrRatio": 1.55,
  "compPer1PctTsrMM": 0.482,
  "tsrVsSpyRatio": 15.64,
  "avgAnnualVsSpyRatio": 1.09,
  "compensationMM": 74.6
}
```

## Error Handling

| Code | Meaning |
|------|---------|
| 401 | Missing or invalid API key |
| 404 | Ticker not found |
| 400 | Bad request parameters |

## Helper Script

For convenience, use `{baseDir}/scripts/ceorater.sh`:

```bash
# Get single company
{baseDir}/scripts/ceorater.sh get AAPL

# Search
{baseDir}/scripts/ceorater.sh search "healthcare"

# List top N
{baseDir}/scripts/ceorater.sh list 20
```

## Data Coverage

- 516 CEOs as of February 2026, including all S&P 500 constituents
- Updated daily after U.S. market close (typically by 6:30 PM EST)
- Safe to cache responses for up to 24 hours

## More Information

- Documentation: https://www.ceorater.com/api-docs.html
- Agent manifest: https://www.ceorater.com/.well-known/agent.json
- Support: support@ceorater.com
- Enterprise sales: sales@ceorater.com