# RentSeek Evidence — Executive Compensation API

Get named-executive fiscal-year compensation rows from public company filings.

## Endpoint

```http
GET https://rentseek.ing/api/executive-compensation?ticker=AAPL&period=annual&limit=4
Authorization: Bearer <api-key>
```

`X-API-KEY: <api-key>` is equivalent.

## Authentication

Latest-FY reads and ticker listing do not require an API key. Unauthenticated
calls share the sandbox quota (60 requests/minute, fail-closed when the limiter
is unavailable) and are server-clamped to the latest fiscal year when no year
filter is sent.

Historical, range, or multi-FY depth requires a key. Generate one from
https://rentseek.ing/developers and send it as `Authorization: Bearer <api-key>` or
`X-API-KEY`. The first API key or OAuth grant for a user adds 100 lifetime
credits to the same user-scoped balance.

## Credits

- Latest-FY single-ticker request (`limit=1`, or `fiscal_year` equal to latest): **0 credits**.
- Historical, range-filtered, or multi-FY request: **1 credit per request**.
- Available-ticker lookup: **0 credits**.
- RentSeek 5xx responses, `304 Not Modified`, and idempotent retries: **0 additional credits**.

Every metered response includes `X-RentSeek-Credit-Cost`,
`X-RentSeek-Credits-Remaining`, and `X-RentSeek-Request-Id`. You may provide
`X-RentSeek-Request-Id` and reuse it when retrying the same operation.

## Query Parameters

- `ticker`: Ticker symbol. Required if `cik` is not provided.
- `cik`: SEC Central Index Key. Required if `ticker` is not provided.
- `period`: `annual`. Defaults to `annual`.
- `limit`: Maximum fiscal years to return. Defaults to `4`, max `100`. All executive rows for each included fiscal year are returned.
- `fiscal_year`, `fiscal_year_gte`, `fiscal_year_lte`, `fiscal_year_gt`, `fiscal_year_lt`: Fiscal-year filters.
- `year`: alias for `fiscal_year`. `from_year`: alias for `fiscal_year_gte`.
- Unauthenticated `year`, `fiscal_year`, or `from_year` requests return HTTP 400 JSON: `error` `older fiscal years require an API key`, `signup_url` `https://rentseek.ing/developers`, `free_tier` explaining the latest fiscal year is free, and `requested_fiscal_year`.
- Unsupported query parameters return HTTP 400.

## Response

When a filing reports only a combined pension and deferred earnings amount, the optional `pension_and_deferred_comp_earnings` field preserves it. Both `pension_change` and `deferred_comp_earnings` are then null because the split is not separately established.

```json
{
  "executive_compensation": [
    {
      "ticker": "AAPL",
      "cik": "0000320193",
      "company_name": "Apple Inc.",
      "fiscal_year": 2024,
      "reported_year": 2024,
      "period": "annual",
      "executive_id": "timcook",
      "executive_name": "Tim Cook",
      "executive_role": "Chief Executive Officer",
      "is_peo": true,
      "is_pfo": false,
      "reporting_currency": "USD",
      "salary": 3000000,
      "bonus": 0,
      "stock_awards": 60000000,
      "option_awards": 0,
      "non_equity_incentive": 12000000,
      "pension_change": 0,
      "other_comp": 1400000,
      "unknown_component": 0,
      "total_compensation": 76400000,
      "source": {
        "form": "DEF 14A",
        "accession": "0000320193-25-000008",
        "filing_date": "2025-01-10",
        "filing_url": "https://www.sec.gov/Archives/..."
      }
    }
  ]
}
```

This endpoint does not return pay ratio, pay-versus-performance/CAP adjustments, director compensation, insider trades, or market-cap/Yahoo-derived values.

## Error Responses

Public developer/provider API errors use the Financial Datasets-style flat envelope
`{ "error": string, "message": string }`. App-internal RentSeek APIs may use a
different nested error envelope.

An exhausted historical request returns HTTP 402:

```json
{
  "error": "Payment Required",
  "message": "Premium credit packs are launching soon. Your 100 free credits are exhausted; request early access at the developer hub.",
  "balance": 0,
  "purchase": {
    "status": "coming_soon",
    "request_access_url": "https://rentseek.ing/developers"
  },
  "retry": {
    "same_api_key": true
  }
}
```

## Available Tickers

```http
GET https://rentseek.ing/api/executive-compensation/tickers
```

No API key is required. Historical compensation still uses `Authorization: Bearer`
or `X-API-KEY`.

## Evidence Bundles

For a complete source-linked company payload, use the 3-credit dossier endpoint. To verify one deterministic claim, use the 1-credit claim endpoint or its public human receipt.

- [Dossier and Claim Docs](https://rentseek.ing/api/evidence.md)
- `https://rentseek.ing/api/v1/companies/AAPL/dossier`
- `https://rentseek.ing/api/v1/claims/{claimId}`
- `https://rentseek.ing/claims/{claimId}`

## MCP

The same executive compensation dataset is available through the remote MCP server at `https://rentseek.ing/mcp`.

- [MCP Server Docs](https://rentseek.ing/api/mcp.md)
- Authentication: OAuth 2.1 with dynamic client registration, or `X-API-KEY`
- Anonymous MCP calls are server-clamped to latest FY. OAuth and API-key calls share the user credit balance; multi-FY calls cost 1 credit.
- Tools: `get_executive_compensation`, `get_company_dossier`, `get_claim_evidence`, `list_material_changes`, `list_available_tickers`, `submit_feedback`, `request_api_key`

## OpenAPI Fragment

```yaml
openapi: 3.0.1
security:
  - {}
  - X-API-KEY: []
  - Bearer: []
paths:
  /api/executive-compensation:
    get:
      operationId: getExecutiveCompensation
      parameters:
        - name: ticker
          in: query
          schema:
            type: string
        - name: cik
          in: query
          schema:
            type: string
        - name: period
          in: query
          schema:
            type: string
            enum: [annual]
        - name: limit
          in: query
          schema:
            type: integer
            default: 4
            maximum: 100
      responses:
        "200":
          description: Executive compensation response
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "402":
          $ref: "#/components/responses/PaymentRequiredError"
        "404":
          $ref: "#/components/responses/NotFoundError"
components:
  securitySchemes:
    X-API-KEY:
      type: apiKey
      name: X-API-KEY
      description: API key for authentication. Equivalent to Authorization Bearer.
      in: header
    Bearer:
      type: http
      scheme: bearer
      description: Same rsk_live_ or rsk_test_ key as X-API-KEY.
  responses:
    UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
```

RentSeek Evidence is informational filing data, not investment advice.
