# Marketbeat — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Track comprehensive stock market data including real-time overviews, analyst ratings, earnings reports, insider trades, and institutional ownership across thousands of companies. Search stocks, analyze financial statements and profitability metrics, monitor short interest, explore options chains, and stay updated with market headlines and competitor analysis.

**Category:** Finance & Markets | **Website:** [marketbeat.com/](https://marketbeat.com/) | **Docs:** [parse.bot/marketplace/7efa2b5b-c2ed-4d9d-99d4-0f3e152f73f3/marketbeat-com-api](https://parse.bot/marketplace/7efa2b5b-c2ed-4d9d-99d4-0f3e152f73f3/marketbeat-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-marketbeat-com-api-7efa2b5b/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_analyst_ratings

Get historical monthly analyst rating counts and breakdown. Returns time series data with buy, hold, sell, strong buy counts and total ratings per month, typically covering 3 years of history.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `exchange` | string | No | Stock exchange (e.g. 'NYSE', 'NASDAQ'). |
| `ticker` | string | Yes | Stock ticker symbol (e.g. 'AAPL'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-marketbeat-com-api-7efa2b5b/get_analyst_ratings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"exchange":"<string>","ticker":"<string>"}'
```

### get_competitors

Get competitor comparison data for a stock. Returns multiple comparison tables covering earnings/valuation, profitability, and analyst sentiment. Each section compares the stock against its primary competitor with detailed financial metrics.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `exchange` | string | No | Stock exchange (e.g. 'NYSE', 'NASDAQ'). |
| `ticker` | string | Yes | Stock ticker symbol (e.g. 'AAPL'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-marketbeat-com-api-7efa2b5b/get_competitors \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"exchange":"<string>","ticker":"<string>"}'
```

### get_earnings

Get earnings estimates and historical earnings data including EPS estimates (low, high, average), number of analyst estimates, revenue estimates, and company revenue guidance. Covers both quarterly and fiscal year estimates.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `exchange` | string | No | Stock exchange (e.g. 'NYSE', 'NASDAQ'). |
| `ticker` | string | Yes | Stock ticker symbol (e.g. 'AAPL'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-marketbeat-com-api-7efa2b5b/get_earnings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"exchange":"<string>","ticker":"<string>"}'
```

### get_financial_statements

Get financial statements including annual and quarterly income statements, cash flow statements, balance sheets, and metrics/ratios. Each statement is a table with metrics as rows and time periods as columns, covering approximately 10 years of annual data or recent quarters.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `exchange` | string | No | Stock exchange (e.g. 'NYSE', 'NASDAQ'). |
| `ticker` | string | Yes | Stock ticker symbol (e.g. 'AAPL'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-marketbeat-com-api-7efa2b5b/get_financial_statements \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"exchange":"<string>","ticker":"<string>"}'
```

### get_insider_trades

Get recent insider transactions for a stock including transaction dates, insider names, buy/sell actions, share counts, average share prices, and total transaction values.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `exchange` | string | No | Stock exchange (e.g. 'NYSE', 'NASDAQ'). |
| `ticker` | string | Yes | Stock ticker symbol (e.g. 'AAPL'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-marketbeat-com-api-7efa2b5b/get_insider_trades \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"exchange":"<string>","ticker":"<string>"}'
```

### get_institutional_ownership

Get institutional ownership data including top institutional holders, their share positions, market value, portfolio percentage, quarterly change in shares, and ownership percentage in company.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `exchange` | string | No | Stock exchange (e.g. 'NYSE', 'NASDAQ'). |
| `ticker` | string | Yes | Stock ticker symbol (e.g. 'AAPL'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-marketbeat-com-api-7efa2b5b/get_institutional_ownership \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"exchange":"<string>","ticker":"<string>"}'
```

### get_marketrank

Get MarketRank scores and component details for a stock. Includes overall percentile score and individual category scores for Analyst Opinion, Earnings and Valuation, Short Interest, Dividend, News/Social Media, and Company Ownership.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `exchange` | string | No | Stock exchange (e.g. 'NYSE', 'NASDAQ'). |
| `ticker` | string | Yes | Stock ticker symbol (e.g. 'AAPL'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-marketbeat-com-api-7efa2b5b/get_marketrank \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"exchange":"<string>","ticker":"<string>"}'
```

### get_options_chain

Get options chain data for a stock including calls and puts with expiration dates, strike prices, close prices, volume, open interest, implied volatility, delta, and number of trades.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `exchange` | string | No | Stock exchange (e.g. 'NYSE', 'NASDAQ'). |
| `ticker` | string | Yes | Stock ticker symbol (e.g. 'AAPL'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-marketbeat-com-api-7efa2b5b/get_options_chain \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"exchange":"<string>","ticker":"<string>"}'
```

### get_profitability_metrics

Get key profitability, valuation, debt, and other financial metrics for a stock. Returns a flat key-value mapping of metrics including EPS, P/E Ratio, Net Margins, Return on Equity, Debt-to-Equity Ratio, Market Cap, Book Value, Beta, and analyst price targets.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `exchange` | string | No | Stock exchange (e.g. 'NYSE', 'NASDAQ'). |
| `ticker` | string | Yes | Stock ticker symbol (e.g. 'AAPL'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-marketbeat-com-api-7efa2b5b/get_profitability_metrics \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"exchange":"<string>","ticker":"<string>"}'
```

### get_short_interest

Get short interest statistics and historical short interest data for a stock. Summary includes current short interest, change vs previous month, days to cover, and percent of float shorted. History contains periodic reports with shares sold short, dollar volume, and price on report date.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `exchange` | string | No | Stock exchange (e.g. 'NYSE', 'NASDAQ'). |
| `ticker` | string | Yes | Stock ticker symbol (e.g. 'AAPL'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-marketbeat-com-api-7efa2b5b/get_short_interest \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"exchange":"<string>","ticker":"<string>"}'
```

### get_stock_forecast

Get analyst forecast data including consensus rating breakdown over time periods, consensus comparison against sector and S&P 500, and a summary of analyst opinions. Breakdown shows Strong Buy, Buy, Hold, Sell counts and price targets across current, 1-month, 3-month, and 1-year windows.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `exchange` | string | No | Stock exchange (e.g. 'NYSE', 'NASDAQ'). |
| `ticker` | string | Yes | Stock ticker symbol (e.g. 'AAPL'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-marketbeat-com-api-7efa2b5b/get_stock_forecast \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"exchange":"<string>","ticker":"<string>"}'
```

### get_stock_headlines

Get recent news headlines for a stock from various sources. Each headline includes the title, URL, relative date, and source domain. Typically returns the most recent 5-10 headlines.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `exchange` | string | No | Stock exchange (e.g. 'NYSE', 'NASDAQ'). |
| `ticker` | string | Yes | Stock ticker symbol (e.g. 'AAPL'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-marketbeat-com-api-7efa2b5b/get_stock_headlines \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"exchange":"<string>","ticker":"<string>"}'
```

### get_stock_overview

Get comprehensive stock overview including current price, day change, key stats, company description, and company calendar for a given ticker. Key stats include P/E ratio, market cap, dividend yield, volume, and price ranges. Company calendar shows earnings dates and dividends.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `exchange` | string | No | Stock exchange (e.g. 'NYSE', 'NASDAQ', 'BATS', 'NYSEARCA'). |
| `ticker` | string | Yes | Stock ticker symbol (e.g. 'AAPL'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-marketbeat-com-api-7efa2b5b/get_stock_overview \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"exchange":"<string>","ticker":"<string>"}'
```

### search_stocks

Search for stock tickers by company name or symbol. Returns matching stocks with ticker, exchange, name, and URL path. Also returns related MarketBeat articles when available.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword such as a company name or ticker symbol (e.g. 'AAPL' or 'Apple'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-marketbeat-com-api-7efa2b5b/search_stocks \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```