API Documentation

Programmatic access to CEO performance metrics and company data

Subscribe — $99/month Unlimited API calls • Cancel anytime

Base URL

https://api.ceorater.com

Quick Navigation

Authentication Getting Started Get API Metadata List Companies Get Company by Ticker Search Companies Coverage Health Check Data Formats Field Reference Code Examples Error Responses

Getting Started

The CEORater API provides programmatic access to CEO performance metrics, compensation data, and proprietary scores for public company executives. Subscribe to get your API key and start making requests immediately.

Subscribe Now

Pricing: $99/month — unlimited API calls. Cancel anytime.

1. Subscribe & get your API key

After subscribing, you'll receive an API key starting with zpka_. Keep this key secure.

2. cURL example

curl -i "https://api.ceorater.com/v1/company/AAPL?format=raw" \
  -H "Authorization: Bearer zpka_your_api_key_here"

3. Minimal Python example

import requests

BASE_URL = "https://api.ceorater.com"
API_KEY = "zpka_your_api_key_here"

resp = requests.get(
    f"{BASE_URL}/v1/company/AAPL",
    params={"format": "raw"},
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=10,
)
resp.raise_for_status()
print(resp.json())

Authentication

All API requests require authentication using your API key in the Authorization header with a Bearer token:

Authorization: Bearer zpka_your_api_key_here

Your API key starts with zpka_ and is provided when you subscribe. Keep it secure and never expose it in client-side code.

401 Unauthorized: Returned when the API key is missing, invalid, or expired.

Endpoints

GET `/v1/meta`

Returns information about the current dataset.

Response Example:

{
  "count": 519,
  "last_loaded": "2026-01-07T08:00:00.000Z"
}

GET `/v1/companies`

Retrieve a paginated list of companies with CEO ratings.

Query Parameters:

Parameter	Type	Default	Description
`limit`	integer	50	Number of results (max: 2000)
`offset`	integer	0	Starting position for pagination
`format`	string	ui	Response format: `ui` or `raw`

Example Request:

GET /v1/companies?limit=20&offset=0&format=ui
x-api-key: your_api_key_here

Response Example:

{
  "items": [
    {
      "Company Name": "Apple Inc.",
      "Ticker": "AAPL",
      "Sector": "Technology",
      "Industry": "Computer Manufacturing",
      "CEO Name": "Tim Cook",
      "Founder (Y/N)": "N",
      "CEORaterScore": 87,
      "AlphaScore": 94,
      "CompScore": "C",
      "TSR During Tenure": "2,223%",
      "Avg. Annual TSR": "155%",
      "TSR vs. SPY": "1,564%",
      "Avg Annual TSR vs. SPY": "109%",
      "Compensation ($ millions)": "$74.6M",
      "CEO Compensation Cost / 1% Avg TSR": "$0.482M",
      "Tenure (years)": "14.4 years"
    }
  ],
  "total": 519,
  "offset": 0,
  "limit": 20
}

GET `/v1/company/:ticker`

Retrieve detailed information for a specific company.

Path Parameters:

ticker (string) - Stock ticker symbol (case-insensitive)

Query Parameters:

format (string) - Response format: ui or raw (default: ui)

Example Request:

GET /v1/company/AAPL?format=ui
x-api-key: your_api_key_here

Response Example (UI Format):

{
  "Company Name": "Apple Inc.",
  "Ticker": "AAPL",
  "Sector": "Technology",
  "Industry": "Computer Manufacturing",
  "CEO Name": "Tim Cook",
  "Founder (Y/N)": "N",
  "CEORaterScore": 87,
  "AlphaScore": 94,
  "CompScore": "C",
  "TSR During Tenure": "2,223%",
  "Avg. Annual TSR": "155%",
  "TSR vs. SPY": "1,564%",
  "Avg Annual TSR vs. SPY": "109%",
  "Compensation ($ millions)": "$74.6M",
  "CEO Compensation Cost / 1% Avg TSR": "$0.482M",
  "Tenure (years)": "14.4 years"
}

Response Example (Raw Format):

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

GET `/v1/search`

Search across company names, tickers, sectors, industries, and CEO names.

Query Parameters:

Parameter	Type	Required	Description
`q`	string	Yes	Search query (case-insensitive)
`format`	string	No	Response format: `ui` or `raw`

Coverage (Searchable Universe)

CEORater covers all S&P 500 component companies and their CEOs. The exact count may vary slightly as companies enter or exit the index, or as CEO transitions occur.

To retrieve the full list programmatically: Use the /v1/companies endpoint with limit=600 to fetch all available CEOs in a single request.

GET /v1/companies?limit=600&format=ui
Authorization: Bearer zpka_your_api_key_here

You can also use the /v1/search endpoint to find specific companies by name, ticker, sector, industry, or CEO name.

Note: Empty query returns empty results. Use the /v1/companies endpoint to retrieve all records.

Example Request:

GET /v1/search?q=apple&format=ui
x-api-key: your_api_key_here

GET `/status`

Check API status and data freshness. No authentication required

Response Example:

{
  "state": "ok",
  "last_loaded": "2026-01-07T08:00:00.000Z",
  "total": 519
}

Data Formats

UI Format (Default)

Human-readable format with formatted values:

Percentages with % symbol
Money with $ and M suffix
Tenure with years suffix
CompScore as letter grade (A-F)

Raw Format

Machine-readable format with numeric values:

All ratios as decimals (e.g., 21.40 for 2,140%)
Money values as pure numbers
Boolean for founder status
Null values for missing data

Field Reference

UI Format Field	Raw Format Field	Description	Example
Company Name	`companyName`	Company Name	"Apple Inc."
Ticker	`ticker`	Ticker Symbol	"AAPL"
Sector	`sector`	Sector	"Technology"
Industry	`industry`	Industry	"Computer Manufacturing"
CEO Name	`ceo`	Current CEO Name	"Tim Cook"
Founder (Y/N)	`founderCEO`	Founder CEO (Y/N)	"N" / false
CEORaterScore	`ceoraterScore`	Overall Rating (0-100)	87
AlphaScore	`alphaScore`	Alpha Performance (0-100)	94
CompScore	`compScore`	Compensation Efficiency (A-F)	"C"
TSR During CEO Tenure	`tsrMultiple`	Total Shareholder Return (TSR)	"2,223%" / 22.23
Avg. Annual TSR	`avgAnnualTsrRatio`	Average Annual TSR	"155%" / 1.55
TSR vs. SPY	`tsrVsSpyRatio`	TSR vs. SPY	"1,564%" / 15.64
Avg Annual TSR vs. SPY	`avgAnnualVsSpyRatio`	Avg Annual TSR vs. SPY	"109%" / 1.09
CEO Compensation ($ millions)	`compensationMM`	Total CEO Compensation	"$74.6M" / 74.6
CEO Compensation / 1% Avg TSR	`compPer1PctTsrMM`	CEO Compensation Cost per Percentage Point TSR	"$0.482M" / 0.482
Tenure (years)	`tenureYears`	CEO Tenure	"14.4 years" / 14.4

Code Examples

JavaScript / Fetch

const API_KEY = 'zpka_your_api_key_here';
const BASE_URL = 'https://api.ceorater.com';

async function searchCompanies(query) {
  const response = await fetch(
    `${BASE_URL}/v1/search?q=${encodeURIComponent(query)}`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );
  return response.json();
}

// Usage
const results = await searchCompanies('apple');
console.log(results.items);

Swift / iOS

struct CEORaterAPI {
    let baseURL = "https://api.ceorater.com"
    let apiKey = "zpka_your_api_key_here"
    
    func getCompany(ticker: String) async throws -> Company {
        let url = URL(string: "\(baseURL)/v1/company/\(ticker)?format=raw")!
        var request = URLRequest(url: url)
        request.addValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
        
        let (data, _) = try await URLSession.shared.data(for: request)
        return try JSONDecoder().decode(Company.self, from: data)
    }
}

Python

import requests

API_KEY = 'zpka_your_api_key_here'
BASE_URL = 'https://api.ceorater.com'

def list_companies(limit=50, offset=0):
    response = requests.get(
        f'{BASE_URL}/v1/companies',
        headers={'Authorization': f'Bearer {API_KEY}'},
        params={'limit': limit, 'offset': offset, 'format': 'raw'}
    )
    return response.json()

# Usage
data = list_companies(limit=20)
print(f"Total companies: {data['total']}")

cURL

# Search for companies
curl -X GET "https://api.ceorater.com/v1/search?q=technology" \
  -H "Authorization: Bearer zpka_your_api_key_here"

# Get specific company
curl -X GET "https://api.ceorater.com/v1/company/AAPL?format=raw" \
  -H "Authorization: Bearer zpka_your_api_key_here"

Error Responses

401 Unauthorized

{
  "error": "Missing or invalid API key"
}

404 Not Found

{
  "error": "Not found"
}

400 Bad Request

{
  "ok": false,
  "error": "Expected array at top level"
}

Additional Information

Data Refresh: Dataset updates daily (weekdays, after market close)
CORS: Enabled for all origins

Support

For API access, technical support, or feature requests, please contact:

Email: [email protected]

Web: https://www.ceorater.com/support.html

Manage Subscription: Billing Portal (via Paddle)

API Documentation

Base URL

Quick Navigation

Getting Started

1. Subscribe & get your API key

2. cURL example

3. Minimal Python example

Authentication

Endpoints

GET /v1/meta

Response Example:

GET /v1/companies

Query Parameters:

Example Request:

Response Example:

GET /v1/company/:ticker

Path Parameters:

Query Parameters:

Example Request:

Response Example (UI Format):

Response Example (Raw Format):

GET /v1/search

Query Parameters:

Coverage (Searchable Universe)

Example Request:

GET /status

Response Example:

Data Formats

UI Format (Default)

Raw Format

Field Reference

Code Examples

JavaScript / Fetch

Swift / iOS

Python

cURL

Error Responses

401 Unauthorized

404 Not Found

400 Bad Request

Additional Information

Support

GET `/v1/meta`

GET `/v1/companies`

GET `/v1/company/:ticker`

GET `/v1/search`

GET `/status`