# 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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/marketbeat/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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/credits/marketbeat/get-analyst-ratings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/marketbeat/get-competitors \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/marketbeat/get-earnings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/marketbeat/get-financial-statements \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/marketbeat/get-insider-trades \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/marketbeat/get-institutional-ownership \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/marketbeat/get-marketrank \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/marketbeat/get-options-chain \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/marketbeat/get-profitability-metrics \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/marketbeat/get-short-interest \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/marketbeat/get-stock-forecast \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/marketbeat/get-stock-headlines \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/marketbeat/get-stock-overview \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/marketbeat/search-stocks \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.