ROIC.ai is a financial data API covering stock prices, financial statements, earnings call transcripts, financial ratios, and company data across 68,000+ tickers and 70+ global exchanges. This guide documents the full product: authentication, response formats, every endpoint category, exact pricing across all four tiers, and the complete 36-tool MCP server with setup steps for every supported client.
Table of Contents
- Overview
- Data Coverage
- Account Setup and API Keys
- Authentication
- Base URL and First Request
- Response Format
- Pagination
- Error Codes
- Rate Limits
- Full Endpoint Reference
- Pricing — All Four Plans
- MCP Server
- MCP Tool Reference (36 Tools)
- MCP Setup by Client
- Self-Hosting the MCP Server
- SDKs
- Known Limitations
- Reference Links
Overview
ROIC.ai ( @vladcx ) operates as a REST API (api.roic.ai) with a parallel MCP server (mcp.roic.ai) that exposes the same data to AI assistants as callable tools. Both interfaces draw from the same underlying dataset and the same per-plan limits.
Published scale figures:
| Metric | Value |
|---|---|
| Financial statement history | 40+ years |
| Tickers covered | 68,000+ |
| Quarters of data per company | 120+ |
| Earnings call transcript history | 17+ years |
| Global exchanges | 70+ |
| Advertised uptime | 99.9% |
| Advertised response time | Sub-200ms |
Commercial redistribution rights (shipping the data inside a product you sell) are available only on the Enterprise plan.
Data Coverage
The API is organized into four data groups.
Fundamentals
- Income statement (annual + quarterly revenue, net income, EPS, EBITDA)
- Balance sheet (assets, liabilities, equity, debt, cash positions)
- Cash flow statement (operating, investing, financing, CapEx, free cash flow)
- Pre-computed financial ratios and valuation metrics
Earnings
- Earnings calendar (scheduled + reported, filterable by ticker/date)
- Consensus estimates vs. reported actuals
- EPS surprise history (beat/miss with calculated surprise size)
- Full call transcripts — raw and edited versions, organized by fiscal quarter
- Call audio and slide decks (where available)
- SEC filings tied to earnings events
Market Data
- Historical daily OHLCV and VWAP, adjusted or unadjusted for splits/dividends
- Latest daily price (single ticker or market-wide snapshot)
- Stock splits (forward and reverse, with ratios and execution dates)
- Forex rates for 4,000+ currency pairs, historical and latest
Company Data
- Company profiles (identity, classification, market cap, CEO, exchange listings)
- Company logos (WebP or PNG, sized on request)
- Sector and industry classification with ticker counts per category
- SEC-sourced fiscal-year employee headcount history
Account Setup and API Keys
- Go to roic.ai/signup
- Create an account — no credit card required for the Free plan
- Open your dashboard and copy your API key
- The same key authenticates both API v2 and v3 requests
Authentication
Every request uses exactly one of two authentication methods. Supplying both on the same request returns 401 Unauthorized, even when both values are the correct key.
Method 1: Query parameter
curl "https://api.roic.ai/v3.0.0/company/profile/NASDAQ:AAPL?apikey=YOUR_API_KEY"
Suitable for quick testing in a browser or terminal. Not recommended for production, since query parameters are commonly logged by servers, proxies, and browser history.
Method 2: Bearer token (recommended)
curl "https://api.roic.ai/v3.0.0/company/profile/NASDAQ:AAPL" \
-H "Authorization: Bearer $ROIC_API_KEY"
This is the documented method for production applications, server-side code, and scripts.
Key storage rules per the docs: store the key in an environment variable or secrets manager; never commit it to source control; never expose it in client-side browser code.
Base URL and First Request
https://api.roic.ai
Every v3 endpoint path begins with /v3.0.0. Example — company profile for Apple:
curl "https://api.roic.ai/v3.0.0/company/profile/NASDAQ:AAPL?apikey=YOUR_API_KEY"
A successful call returns 200 OK, a Request-Id response header (used for support/debugging), and the resource object directly.
Response Format
Single-resource responses
Returned as an unwrapped object — not nested under a data key:
{
"id": "tkr_cO46h8pgSu9Qqy",
"object": "v3.reference.ticker",
"symbol": "NASDAQ:AAPL",
"ticker": "AAPL"
}
Nullable fields are present with a null value when no data is available, rather than being omitted.
Exception: stock prices, forex prices, and forex pairs do not include id or object fields. A per-row ID would duplicate data already present in the request, so these resources are addressed by symbol and date instead:
{
"symbol": "NASDAQ:AAPL",
"date": "2026-07-17",
"close": 212.41
}
List responses
Returned as a data array with pagination URLs:
{
"data": [],
"next_page_url": "/v3.0.0/tickers?limit=50&page=page_v1_opaque_token",
"previous_page_url": null
}
- First page:
previous_page_urlisnull - Last page:
next_page_urlisnull - Price-history list endpoints put the shared
symbolandcurrencyonce on the envelope rather than repeating them on every row; these fields remain present even whendatais empty
Binary response (one exception)
GET /v3.0.0/company/logo/{identifier} returns raw WebP or PNG bytes instead of JSON, with Content-Type, ETag, and Cache-Control headers. Conditional requests can return 304 Not Modified with an empty body. Logo failures still return the standard JSON error envelope.
Pagination
Most list endpoints use cursor-based pagination.
Request the first page without a page parameter:
curl "https://api.roic.ai/v3.0.0/tickers?limit=50" \
-H "Authorization: Bearer $ROIC_API_KEY"
Follow the returned next_page_url:
curl "https://api.roic.ai/v3.0.0/tickers?limit=50&page=page_v1_opaque_token" \
-H "Authorization: Bearer $ROIC_API_KEY"
Rules:
- Page tokens are opaque — never decode, edit, or construct one manually. Each token is bound to the specific endpoint, filters, sort order, and
limitthat generated it. - Tokens expire after one hour.
- Changing a filter, sort order, or page size requires starting a new request without a
pageparameter. - Query-authenticated clients must re-append
?apikey=on every followed page URL — returned page URLs never carry credentials. - The API uses stable keyset ordering, but underlying data can change between requests; store results locally if a reproducible dataset is required.
- A small number of endpoints (e.g., the metric-definition list) are unpaginated — they return every matching record in one response and don't accept
limit,page, ororder; both page URLs are alwaysnullon these.
Error Codes
All errors use one consistent envelope:
{
"error": {
"type": "invalid_request_error",
"code": "resource_missing",
"message": "The requested resource does not exist.",
"request_id": "req_0af7651916cd43dd8448eb211c80319c"
}
}
Application logic should branch on type and code — not the human-readable message, which is not guaranteed to stay stable in wording. The optional param field, when present, identifies which request value needs to change.
| HTTP Status | type |
Meaning |
|---|---|---|
| 400 | invalid_request_error |
Invalid parameter, body, or page token |
| 401 | authentication_error |
Missing, conflicting, malformed, or unknown credentials |
| 402 | payment_required_error |
Current plan does not include access to this resource |
| 404 | invalid_request_error |
Resource or v3 route does not exist |
| 409 | conflict_error |
Request conflicts with existing state |
| 429 | rate_limit_error |
Request limit exceeded |
| 500 | api_error |
Unexpected server-side failure |
| 503 | api_error |
A required dependency is unavailable |
Error responses carry Cache-Control: no-store and must not be cached. Every response — success or failure — includes a Request-Id header.
Documented retry policy:
-
429→ wait for the duration inRetry-After -
500/503→ capped exponential backoff with jitter - Validation or authentication errors → correct the request before retrying; retrying unmodified requests will not succeed
Rate Limits
v2 and v3 requests draw from the same quota per API key, enforced on a sliding 60-second window. An authenticated request is counted against the quota before parameter validation runs, so even an invalid request consumes one call if the limit has not been reached.
| Plan | Requests/minute | History available |
|---|---|---|
| Free | 5 | 2 years |
| Individual | 300 | 5 years |
| Professional | Unlimited | All available (40+ years) |
| Enterprise | Unlimited | All available (40+ years) |
Rate-limit response headers
Present on most metered responses, but not guaranteed on every call:
| Header | Meaning |
|---|---|
X-RateLimit-Limit |
Enforced limit for the current window |
X-RateLimit-Remaining |
Requests remaining after this one |
X-RateLimit-Reset |
Unix timestamp when the oldest request exits the window |
429 response example
{
"error": {
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded for the free plan. Retry in 42 seconds or update your plan.",
"request_id": "req_0af7651916cd43dd8448eb211c80319c"
}
}
Full Endpoint Reference
Tickers
| Endpoint | Purpose |
|---|---|
| List all tickers | Paginated catalog of all tickers |
| Retrieve a ticker | Single ticker resource |
| Search tickers | Resolve company name/symbol to ticker resources |
Company
| Endpoint | Purpose |
|---|---|
| Company profile | CEO, sector, industry, market cap, exchange listings, description |
| Company employees | Fiscal-year headcount history (SEC-sourced) |
| Company logo | Binary WebP/PNG, supports conditional requests |
Earnings Calls
| Endpoint | Purpose |
|---|---|
| List earnings calls | All available calls by year/quarter/date |
| Raw transcript | Unedited call transcript |
| Edited transcript | Cleaned/formatted transcript |
| Call audio | Audio file for the call |
| Slide decks | Presentation materials from the call |
| Filings | SEC filings tied to the earnings event |
Calendar
| Endpoint | Purpose |
|---|---|
| Earnings calendar | Scheduled and reported earnings with estimates/actuals/surprises |
Stock Prices
| Endpoint | Purpose |
|---|---|
| Historical prices | Daily OHLCV with date-range filtering |
| Latest price | Most recent quote, single ticker |
| List all latest stock prices | Market-wide latest-price snapshot |
Stock Splits
| Endpoint | Purpose |
|---|---|
| List stock splits | Market-wide or per-ticker split events |
Financial Statements
| Endpoint | Purpose |
|---|---|
| Income statement | Revenue, net income, EPS, EBITDA |
| Balance sheet | Assets, liabilities, equity, debt |
| Cash flow statement | Operating/investing/financing cash flow, CapEx, FCF |
Financial Ratios
| Endpoint | Purpose |
|---|---|
| Profitability ratios | ROE, ROA, ROIC, margins |
| Credit & debt ratios | Debt/EBITDA, debt/equity, interest coverage |
| Liquidity ratios | Current, quick, cash ratio, Altman Z-Score |
| Working capital ratios | Turnover ratios, cash conversion cycle |
| Yield analysis | FCF yield, shareholder yield, capital yield |
Valuation
| Endpoint | Purpose |
|---|---|
| Enterprise value | Market cap, EV, EV/Sales, EV/EBITDA |
| Valuation multiples | P/E, P/B, P/S, P/CF, EV multiples |
| Per-share data | EPS, revenue, book value, cash flow per share |
Forex
| Endpoint | Purpose |
|---|---|
| List forex pairs | Currency-pair catalog |
| Historical forex prices | Daily OHLC history for one pair |
| Latest forex price | Latest rate for one pair |
| List all latest forex prices | Latest rate, every pair |
Bulk Downloads (paid plans only)
| Endpoint | Purpose |
|---|---|
| Bulk fundamentals | Mass financial-statement export |
| Bulk earnings calls | Mass transcript export |
| Bulk stock prices | Mass price-history export |
Reference Data
| Endpoint | Purpose |
|---|---|
| Exchanges | All exchanges with ticker counts |
| Exchange trading hours | Full trading-session history per exchange |
| Exchange holidays | Holiday calendar per exchange |
| Markets | Markets with country codes and symbol counts |
| Sectors | All sectors with ticker counts |
| Industries | All industries with ticker counts |
| Countries | All countries with ticker counts |
Full interactive documentation and the OpenAPI spec: roic.ai/api/docs
Pricing — All Four Plans
Billed monthly or annually; annual billing includes 2 free months.
| Feature | Free | Individual | Professional | Enterprise |
|---|---|---|---|---|
| Price/month | $0 | $29 | $89 | Custom |
| Requests/minute | 5 | 300 | Unlimited | Unlimited |
| Historical data | 2 years | 5 years | All available (40+ yrs) | All available (40+ yrs) |
| Market coverage | Worldwide | Worldwide | Worldwide | Worldwide |
| Annual financials | 2 years | 5 years | 40+ years | 40+ years |
| Quarterly financials | No | 20 quarters | 160+ quarters | 160+ quarters |
| Financial ratios | 2 years | 5 years | 40+ years | 40+ years |
| Valuation metrics | 2 years | 5 years | 40+ years | 40+ years |
| Stock prices | 2 years | 5 years | All available | All available |
| Batch stock prices | No | Yes | Yes | Yes |
| Stock splits | 2 years | 5 years | All available | All available |
| Forex | 2 years | 5 years | All available | All available |
| Earnings call transcripts | 2 quarters | 2 quarters | All available | All available |
| Earnings calendar | No | No | Yes | Yes |
| Bulk downloads | No | No | Yes | Yes |
| Exchange calendars | No | Yes | Yes | Yes |
| MCP server access | Yes | Yes | Yes | Yes |
| Commercial-use license | No | No | No | Yes |
| Invoicing / multi-user access | No | No | No | Yes |
| Dedicated support | No | No | No | Yes |
All four tiers include company profile data, ticker search, and reference data (sectors, industries, countries, exchanges) at no additional cost.
Note on earnings transcripts: both Free and Individual are capped at 2 quarters of call transcripts. Full transcript history (17+ years) is only unlocked on Professional and Enterprise, alongside the 40-year financial history.
MCP Server
ROIC.ai runs a hosted MCP (Model Context Protocol) server exposing 36 read-only tools to AI assistants. An assistant connected to the server selects the appropriate tool(s) based on a natural-language request, subject to the connected account's plan limits.
Server URL:
https://mcp.roic.ai/mcp
MCP server access is included on every plan, including Free. Plan limits (requests/minute, history depth) apply identically whether data is requested through the REST API or through MCP tool calls. Some calendar, exchange-schedule, and bulk-feed tools require a paid plan regardless of access method.
| Plan | Requests/minute | History via MCP |
|---|---|---|
| Free | 5 | 2 years |
| Individual | 300 | 5 years |
| Professional | Unlimited | All available |
| Enterprise | Unlimited | All available |
MCP Tool Reference (36 Tools)
Tickers & Discovery
| Tool | Description |
|---|---|
search_tickers |
Search by ticker symbol or company name |
list_tickers |
List tickers with listing status, filterable by listed
|
search_ticker_by_identifier |
Look up a ticker by CIK, CUSIP, or ISIN |
Company Information
| Tool | Description |
|---|---|
get_company_profile |
CEO, employees, sector, industry, description |
list_employee_counts |
Historical fiscal-year employee counts |
get_company_news |
Recent news articles, paginated and date-filterable |
Earnings Calls and Calendar
| Tool | Description |
|---|---|
list_earnings_calendar |
Scheduled/reported earnings with estimates, actuals, surprises |
get_latest_earnings_call |
Most recent call transcript |
list_earnings_calls |
List all available calls by year, quarter, date |
get_earnings_call_transcript |
Specific transcript by year and quarter |
Stock Prices and Splits
| Tool | Description |
|---|---|
get_stock_prices |
Historical OHLCV with date-range filtering |
get_latest_stock_price |
Most recent price for one ticker |
list_latest_stock_prices |
Latest quote for every ticker, filterable by exchange |
list_stock_splits |
Market-wide or per-ticker split events |
Financial Statements
| Tool | Description |
|---|---|
get_income_statement |
Revenue, gross profit, operating income, net income, EPS, EBITDA, margins |
get_balance_sheet |
Assets, liabilities, equity, shares outstanding, debt |
get_cash_flow |
Operating/investing/financing cash flows, CapEx, free cash flow |
Financial Ratios
| Tool | Description |
|---|---|
get_profitability_ratios |
ROE, ROA, ROIC, margins, effective tax rate, payout ratio |
get_credit_ratios |
Debt/EBITDA, debt/equity, interest coverage |
get_liquidity_ratios |
Current ratio, quick ratio, cash ratio, Altman Z-Score |
get_working_capital_ratios |
Receivable/inventory/payable turnover, cash conversion cycle |
get_yield_analysis |
FCF yield, shareholder yield, capital yield |
Valuation & Metrics
| Tool | Description |
|---|---|
get_enterprise_value |
Market cap, enterprise value, EV/Sales, EV/EBITDA |
get_valuation_multiples |
P/E, P/B, P/S, P/CF, EV multiples (last/avg/high/low) |
get_per_share_data |
EPS, revenue, EBITDA, book value, cash flow per share |
Reference Data
| Tool | Description |
|---|---|
list_exchanges |
All exchanges with ticker counts |
get_exchange_trading_hours |
Full trading-session history for one exchange |
get_exchange_holidays |
Holiday calendar for one exchange |
list_markets |
Markets with country codes, exchanges, symbol counts |
list_sectors |
All sectors with ticker counts |
list_industries |
All industries with ticker counts |
list_countries |
All countries with ticker counts |
Forex
| Tool | Description |
|---|---|
list_forex_pairs |
Currency-pair catalog with base, quote, synthetic status |
get_forex_prices |
Historical daily OHLC rates, one pair |
get_latest_forex_price |
Latest daily rate, one pair |
list_latest_forex_prices |
Latest rate for every pair, filterable by currency |
Example natural-language queries
Tell me about Apple's business. What do they do, who's the CEO,
and how many employees do they have?
Routes to get_company_profile.
Compare Microsoft and Google's profitability over the last 3 years.
Show me their margins and ROE.
Routes to get_profitability_ratios, called once per ticker.
What did Apple's management say about AI in their latest earnings call?
Routes to get_latest_earnings_call.
Is Tesla overvalued? Show me its P/E ratio, EV/EBITDA, and
price-to-sales compared to the last 5 years.
Routes to get_valuation_multiples with a historical range.
Show me Amazon's stock price performance for January 2025.
Routes to get_stock_prices with date filters.
Which sectors have the most publicly traded companies?
Routes to list_sectors.
MCP Setup by Client
ChatGPT
- Open Settings → Apps → Advanced settings
- Toggle Developer mode on
- Click Create to open the New App configuration window
- Fill in: Name
Roic AI, Connection type Server URL, URLhttps://mcp.roic.ai/mcp - Check "I understand and want to continue", click Create
- Click Sign in with Roic AI and authorize in the browser tab that opens
- In a new chat, click + → More → Roic AI to attach the tool
Claude Code (CLI)
claude mcp add --transport http roicai https://mcp.roic.ai/mcp
Verify the connection:
claude mcp list
Claude (desktop/web)
- Profile icon (bottom-left) → Customize
- Connectors → Add custom connector
- Name:
Roic AI; Remote MCP server URL:https://mcp.roic.ai/mcp - Click Add, wait for the connection check, then click Connect
- Authorize in the browser window that opens
- Review Tool permissions (default may be "Needs approval"; can be changed to "Always allow")
- Start a new chat and confirm the connector is active via the
+icon
VS Code
- Open Command Palette (
Cmd+Shift+P/Ctrl+Shift+P) - Search for and select MCP: Add Server
- Choose HTTP as the transport type
- Enter URL:
https://mcp.roic.ai/mcp - Name the server (e.g.,
roicai) and press Enter - Authorize in the browser window that opens
OpenAI Codex
CLI:
codex mcp add roicai --url https://mcp.roic.ai/mcp
Or in ~/.codex/config.toml:
[mcp_servers.roicai]
url = "https://mcp.roic.ai/mcp"
Manual JSON configuration (any compatible MCP client)
{
"mcpServers": {
"roicai": {
"url": "https://mcp.roic.ai/mcp",
"transport": "http"
}
}
}
Self-Hosting the MCP Server
The MCP server is open source, published at github.com/roicai/mcp-server. It runs locally with one command:
ROIC_API_KEY=your_key npx @roicai/mcp-server
This runs over stdio and authenticates with a standard REST API key instead of OAuth — relevant for CI pipelines, automation scripts, or any MCP client that doesn't support hosted OAuth flows.
Configuration for Claude Desktop, Cursor, or any command-based MCP client:
{
"mcpServers": {
"roicai": {
"command": "npx",
"args": ["-y", "@roicai/mcp-server"],
"env": { "ROIC_API_KEY": "your_key" }
}
}
}
Review the repository's license and recent commit history directly on GitHub before adopting it as a dependency, as with any third-party package.
SDKs
Official SDKs/clients: Python, JavaScript/Node.js, Ruby, Go, plus raw cURL examples throughout the docs.
Python install and basic usage:
pip install roicai
from roicai import Roicai
client = Roicai(api_key="YOUR_API_KEY")
prices = client.stock_prices.list("NASDAQ:AAPL")
for day in prices.items:
print(day.date, day.close)
Known Limitations
Based on the publicly available documentation at the time of writing, the API does not currently include:
- Intraday or tick-level price data — historical and latest prices are daily OHLCV only
- Options chain or derivatives data
- Cryptocurrency data
- Full earnings call transcript history on Free or Individual plans — both are capped at 2 quarters; full history requires Professional or Enterprise
- Earnings calendar or bulk downloads on Free or Individual plans — both require Professional or above
- Commercial redistribution rights outside the Enterprise plan
Reference Links
| Resource | Link |
|---|---|
| Homepage | roic.ai |
| Sign up | roic.ai/signup |
| API docs (full) | roic.ai/api/docs |
| Getting started | roic.ai/api/docs/getting-started |
| Authentication docs | roic.ai/api/docs/authentication |
| Response format docs | roic.ai/api/docs/response-format |
| OpenAPI spec | roic.ai/api/docs/openapi |
| MCP docs | roic.ai/api/mcp |
| Self-hosted MCP (GitHub) | github.com/roicai/mcp-server |
| Pricing | roic.ai/pricing |
| Status page | status.roic.ai |
| Base API URL | https://api.roic.ai |
| MCP server URL | https://mcp.roic.ai/mcp |
All pricing, rate limits, and endpoint details in this guide reflect the public documentation at the time of writing. APIs and pricing change over time — verify current details at roic.ai/pricing and roic.ai/api/docs before making integration decisions based on this reference.
Top comments (0)