# Levels.fyi API — tech salary & compensation scraper: total comp, base, stock and bonus by company, role, level, location and years of experience, plus percentile bands (P10/P25/P50/P75/P90), the median offer and individual anonymized salary submissions from Levels.fyi (levels.fyi) — company role catalog and role-to-company coverage included, no API key required

> The flagship action: full Levels.fyi compensation breakdown for one company + role. Returns the level ladder (L3/L4/…), per-level averages (base / stock / bonus / total), the percentile bands (P10/P25/P50/P75/P90 for total-comp, base, bonus and stock), the median offer (with years of experience), the role's sub-specializations and a sample of recent salary submissions. Pass an optional `location` to scope to a metro.
> ReefAPI engine `levels-fyi` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/levels-fyi/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /levels-fyi/v1/company/salaries — 1 credit
The flagship action: full Levels.fyi compensation breakdown for one company + role. Returns the level ladder (L3/L4/…), per-level averages (base / stock / bonus / total), the percentile bands (P10/P25/P50/P75/P90 for total-comp, base, bonus and stock), the median offer (with years of experience), the role's sub-specializations and a sample of recent salary submissions. Pass an optional `location` to scope to a metro.

**Parameters:**
- `company` (string, required) — Company name or Levels.fyi slug ('google', 'Goldman Sachs', 'stripe', 'nvidia'). A name is auto-slugified; if you already have the slug from company/search, pass it directly.
- `role` (string, required) — Job family / role ('software-engineer', 'product-manager', 'data-scientist', 'hardware-engineer'). Use company/roles to list the exact roles a company reports.
- `location` (string, optional) — Optional metro/location slug to scope comp to one area ('new-york-city-area', 'seattle-area', 'bay-area'). Omit for the company-wide (United States) figures.

**Returns:** company{id,slug,name,…}, role, location, percentiles{total_comp,base_salary,bonus,stock_grant each p10..p90}, median{level,total_compensation,base_salary,years_of_experience,…}, levels[]{titles,order,percent_workforce}, averages[]{level,total_compensation,base_salary,stock_grant,bonus,sample_count}, related_roles[]{title,title_slug,salary_count}, sample_submissions[]

**Example request body:**
```json
{
  "company": "google",
  "role": "software-engineer"
}
```

### POST /levels-fyi/v1/company/roles — 1 credit
Resolve a company to its Levels.fyi profile (id, slug, website, employee count, HQ, vesting schedule…) plus the catalog of job-family role slugs you can query for it. Use this to confirm a company's slug and pick a role slug to feed into company/salaries. NOTE: the role list is the full Levels.fyi job-family catalog (the roles available to query) — for the roles a company actually has reported data for, read `related_roles` from a company/salaries response.

**Parameters:**
- `company` (string, required) — Company name or Levels.fyi slug ('google', 'Goldman Sachs', 'stripe', 'nvidia'). A name is auto-slugified; if you already have the slug from company/search, pass it directly.

**Returns:** company{id,slug,name,website,employee_count,hq_city,vesting_schedule,…}, available_roles[]{slug,name,category,description}

**Example request body:**
```json
{
  "company": "stripe"
}
```

### POST /levels-fyi/v1/company/search — 1 credit
Find companies on Levels.fyi by name. Returns matching companies with the slug and a ready-to-use salaries URL — feed the slug into company/roles or company/salaries.

**Parameters:**
- `query` (string, required) — Company name (or part of it) to search for.
- `limit` (integer, optional, default 20) — Max companies to return (1–100).

**Returns:** companies[]{name, slug, salaries_url}

**Example request body:**
```json
{
  "query": "goldman"
}
```

### POST /levels-fyi/v1/role/companies — 1 credit
For a given role/title, list every company that reports compensation data for it on Levels.fyi (the role's coverage), plus the country-wide median total-comp and the full job-family catalog. Useful for 'which companies pay for <role>' and leaderboard-style discovery.

**Parameters:**
- `role` (string, required) — Role / job-family slug ('software-engineer', 'product-manager', 'data-scientist').
- `limit` (integer, optional, default 200) — Max companies to return (1–2000).

**Returns:** role, median_total_compensation, companies[]{name}, job_families[]{slug,name,category}

**Example request body:**
```json
{
  "role": "software-engineer"
}
```

### POST /levels-fyi/v1/submissions — 1 credit
Paginated individual salary submissions for a company + role — the raw anonymized datapoints behind the averages: level, focus, years of experience, location, base / stock / bonus / total comp and offer date. 50 per page; page with `page`.

**Parameters:**
- `company` (string, required) — Company name or Levels.fyi slug ('google', 'Goldman Sachs', 'stripe', 'nvidia'). A name is auto-slugified; if you already have the slug from company/search, pass it directly.
- `role` (string, required) — Job family / role ('software-engineer', 'product-manager', 'data-scientist', 'hardware-engineer'). Use company/roles to list the exact roles a company reports.
- `location` (string, optional) — Optional metro/location slug to scope comp to one area ('new-york-city-area', 'seattle-area', 'bay-area'). Omit for the company-wide (United States) figures.
- `page` (integer, optional, default 1) — Submission page (50 per page). Page until meta.total_pages.

**Returns:** submissions[]{uuid, level, title, focus_tag, years_of_experience, location, base_salary, total_compensation, stock_grant_annual, bonus_annual, offer_date, currency} + meta{page, total_pages, total}

**Example request body:**
```json
{
  "company": "google",
  "role": "software-engineer"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=levels-fyi
- Human docs page: https://reefapi.com/docs/levels-fyi
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt