API Documentation

Production API for CEO Performance Data & Analytics. CEORater covers S&P 500 CEOs.

Start API Subscription — $99/month Unlimited API calls • Instant key access after checkout • Redirects to Developer Portal • Cancel anytime

Base URL

https://api.ceorater.com

Quick Navigation

Getting Started Authentication Get API Metadata List CEOs Get CEO by Ticker Search CEOs Coverage Data Formats Field Reference Code Examples Error Responses Trust & Governance OpenAPI Spec ↗

Getting Started

The CEORater API provides direct access to CEO Performance Data & Analytics. CEORater covers S&P 500 CEOs. Start in under 2 minutes:

Start API Subscription

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

1Subscribe & Complete Payment

Click Start API Subscription and complete secure checkout with Paddle.

2Open the Developer Portal

After payment, you'll be redirected to the CEORater API Developer Portal. Log in with the same email used at checkout.

https://ceorater-api-main-7ef1acf.zuplo.site

3Copy Key & Run First Call

In the portal, go to Settings → API Keys, copy your zpka_... key, then run:

4Test Your API Key

Run this command in your terminal or command prompt (replace zpka_your_api_key_here with your actual key):

curl -H "Authorization: Bearer zpka_your_api_key_here" https://api.ceorater.com/v1/meta

You should receive JSON including total company count and latest update timestamp.

Security: Keep your API key server-side only. Do not expose it in client-side code or public repos.

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/ceo/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 available in the Developer Portal after subscribing. 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": 517,
  "last_loaded": "2026-01-17T08:00:00.000Z",
  "base_url": "https://api.ceorater.com",
  "docs_url": "https://www.ceorater.com/api-docs.html",
  "api_version": "1.1.0",
  "request_id": "2f9c2870f486d294"
}

GET `/v1/ceos`

Retrieve a paginated list of CEOs with performance 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/ceos?limit=20&offset=0&format=ui
Authorization: Bearer zpka_your_api_key_here

Response Example (UI format):

{
  "items": [
    {
      "Company Name": "Apple Inc.",
      "Ticker": "AAPL",
      "Sector": "Technology",
      "Industry": "Computer Manufacturing",
      "CEO Name": "Tim Cook",
      "Founder (Y/N)": "N",
      "CEORaterScore": 87,
      "AlphaScore": 94,
      "RevenueCAGRScore": 72,
      "Revenue CAGR (Adj.)": "4.2%",
      "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": 517,
  "offset": 0,
  "limit": 20
}

GET `/v1/ceo/:ticker`

Retrieve detailed CEO performance data for a specific company ticker symbol.

Path Parameters:

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

Query Parameters:

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

Example Request:

GET /v1/ceo/AAPL?format=raw
Authorization: Bearer zpka_your_api_key_here

Response Example (raw format):

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

GET `/v1/search`

Search CEOs by company name, ticker, sector, industry, or CEO name.

Query Parameters:

Parameter	Type	Description
`q`	string	Search query (required, returns 400 if missing)
`format`	string	Response format: `ui` or `raw` (default: ui)

Example Request:

GET /v1/search?q=technology&format=raw
Authorization: Bearer zpka_your_api_key_here

Response Example (raw format):

{
  "q": "technology",
  "count": 45,
  "items": [
    { "companyName": "Apple Inc.", "ticker": "AAPL", ... },
    { "companyName": "Microsoft Corp.", "ticker": "MSFT", ... }
  ]
}

Coverage

CEORater covers 517 CEOs across the S&P 500 constituent companies.

Use the /v1/meta endpoint to get the current company count and last data refresh timestamp.

Data Formats

Most endpoints support two response formats via the format query parameter:

`format=ui` (default)

Human-readable labels and formatted values:

• Percentages: "155%"
• Money: "$74.6M"
• Duration: "14.4 years"

`format=raw`

Machine-readable camelCase keys and numeric values:

• Ratios: 1.55
• Millions: 74.6
• Years: 14.4

Field Reference

UI Label	Raw Key	Description	Example (UI / Raw)
CEO Name	`ceo`	Current CEO full name	"Tim Cook"
Founder (Y/N)	`founderCEO`	Whether the CEO is a company founder	"Y" or "N" / true or false
Company Name	`companyName`	Full company name	"Apple Inc."
Ticker	`ticker`	Stock symbol	"AAPL"
CEORaterScore	`ceoraterScore`	Proprietary overall CEO rating (0-100)	87
AlphaScore	`alphaScore`	Performance vs. market (0-100)	94
RevenueCAGRScore	`revenueCagrScore`	Revenue growth rating (0-100)	72
Revenue CAGR (Adj.)	`revenueCagr`	Tenure-adjusted Revenue CAGR	"4.2%" / 0.042
CompScore	`compScore`	Compensation efficiency grade (A-F)	"C"
TSR During Tenure	`tsrMultiple`	Total Shareholder Return	"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/ceo/\(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_ceos(limit=50, offset=0):
    response = requests.get(
        f'{BASE_URL}/v1/ceos',
        headers={'Authorization': f'Bearer {API_KEY}'},
        params={'limit': limit, 'offset': offset, 'format': 'raw'}
    )
    return response.json()

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

cURL

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

# Get specific CEO
curl -H "Authorization: Bearer zpka_your_api_key_here" "https://api.ceorater.com/v1/ceo/AAPL?format=raw"

# List CEOs (paginated)
curl -H "Authorization: Bearer zpka_your_api_key_here" "https://api.ceorater.com/v1/ceos?limit=50&offset=0&format=raw"

# Get metadata
curl -H "Authorization: Bearer zpka_your_api_key_here" "https://api.ceorater.com/v1/meta"

Error Responses

401 Unauthorized

{
  "ok": false,
  "code": "UNAUTHORIZED",
  "error": "Missing or invalid API key",
  "request_id": "2f9c2870f486d294"
}

404 Not Found

{
  "ok": false,
  "code": "NOT_FOUND",
  "error": "Not found",
  "request_id": "2f9c2870f486d294"
}

400 Bad Request

{
  "ok": false,
  "code": "BAD_REQUEST",
  "error": "Query parameter q is required.",
  "request_id": "2f9c2870f486d294"
}

429 Rate Limited

{
  "ok": false,
  "code": "RATE_LIMITED",
  "error": "Rate limit exceeded. Please retry later.",
  "request_id": "2f9c2870f486d294"
}

Additional Information

Data Refresh: Dataset updates daily (weekdays, after market close)
Versioning: Breaking changes are introduced on new major versions with advance notice.
Observability: Every response includes an X-Request-Id header for support troubleshooting.
CORS: Enabled for all origins

Trust & Governance

Institutional onboarding materials and legal terms:

Methodology: https://www.ceorater.com/methodology.html
Privacy Policy: https://www.ceorater.com/privacy.html
Terms of Service: https://www.ceorater.com/terms.html
Support: https://www.ceorater.com/support.html

Platform providers: Zuplo (API key management), Auth0 (API authentication), Paddle (Billing management).

Support

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

Email: support@ceorater.com

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

Developer Portal: https://ceorater-api-main-7ef1acf.zuplo.site

Manage Subscription: Billing Portal (via Paddle)

API Documentation

Base URL

Quick Navigation

Getting Started

1Subscribe & Complete Payment

2Open the Developer Portal

3Copy Key & Run First Call

4Test Your API Key

Minimal Python Example

Authentication

Endpoints

GET /v1/meta

Response Example:

GET /v1/ceos

Query Parameters:

Example Request:

Response Example (UI format):

GET /v1/ceo/:ticker

Path Parameters:

Query Parameters:

Example Request:

Response Example (raw format):

GET /v1/search

Query Parameters:

Example Request:

Response Example (raw format):

Coverage

Data Formats

format=ui (default)

format=raw

Field Reference

Code Examples

JavaScript / Fetch

Swift / iOS

Python

cURL

Error Responses

401 Unauthorized

404 Not Found

400 Bad Request

429 Rate Limited

Additional Information

Trust & Governance

Support

GET `/v1/meta`

GET `/v1/ceos`

GET `/v1/ceo/:ticker`

GET `/v1/search`

`format=ui` (default)

`format=raw`