---
canonical_url: "https://docs.composio.dev/toolkits/finnhub"
markdown_url: "https://docs.composio.dev/toolkits/finnhub.md"
product: "platform"
version: null
last_updated: null
---

# Finnhub

Finnhub provides real-time market data, company fundamentals, financial news, economic data, and securities reference information.

- **Category:** market data
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 11
- **Triggers:** 0
- **Slug:** `FINNHUB`
- **Version:** 20261014_01
- **Instant:** Supported on the latest version. Support varies by tool.

## Tools

### Get Company Financial Metrics

**Slug:** `FINNHUB_GET_COMPANY_FINANCIAL_METRICS`

Get Finnhub's current key ratios and annual or quarterly metric series for one company.

**Instant:** Supported on the latest version.

**Instant pricing:** $0.02 per Finnhub API request

**Discount:** 100

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `symbol` | string | Yes | Company ticker whose financial metrics should be returned. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Company Profile

**Slug:** `FINNHUB_GET_COMPANY_PROFILE`

Look up a company profile by exactly one ticker, ISIN, or CUSIP.

**Instant:** Supported on the latest version.

**Instant pricing:** $0.02 per Finnhub API request

**Discount:** 100

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `isin` | string | No | Company ISIN. Provide exactly one identifier. |
| `cusip` | string | No | Company CUSIP. Provide exactly one identifier. |
| `symbol` | string | No | Company ticker, such as AAPL. Provide exactly one identifier. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Market Status

**Slug:** `FINNHUB_GET_MARKET_STATUS`

Check whether an exchange is open now and identify its current session, timezone, or holiday.

**Instant:** Supported on the latest version.

**Instant pricing:** $0.02 per Finnhub API request

**Discount:** 100

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `exchange` | string | Yes | Finnhub exchange code, such as US. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Quote

**Slug:** `FINNHUB_GET_QUOTE`

Get the latest price snapshot for one Finnhub symbol. Unknown symbols fail explicitly instead of returning a misleading zero quote.

**Instant:** Supported on the latest version.

**Instant pricing:** $0.02 per Finnhub API request

**Discount:** 100

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `symbol` | string | Yes | Exact Finnhub symbol to quote. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Quotes

**Slug:** `FINNHUB_GET_QUOTES`

Get price snapshots for 1-10 Finnhub symbols in one tool call. This uses one Finnhub API request per symbol and reports unrecognized symbols per result.

**Instant:** Supported on the latest version.

**Instant pricing:** $0.02 per Finnhub API request; 1-10 requests ($0.02-$0.2) per tool call

**Discount:** 100

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `symbols` | array | Yes | One to 10 unique Finnhub symbols to quote. The tool makes one upstream request per symbol and preserves this order in the results. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Reported Financials

**Slug:** `FINNHUB_GET_REPORTED_FINANCIALS`

Retrieve as-reported balance-sheet, cash-flow, and income-statement data for a company or filing. A ticker, CIK, or accession number is required; large statement details are available only when requested.

**Instant:** Supported on the latest version.

**Instant pricing:** $0.02 per Finnhub API request

**Discount:** 100

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cik` | string | No | SEC Central Index Key used to find reports. Required when neither a ticker nor an accession number is provided. |
| `symbol` | string | No | Company ticker used to find reports. Required when neither CIK nor an accession number is provided. |
| `to_date` | string | No | Optional report end-date upper bound in YYYY-MM-DD format; provide with from_date. |
| `frequency` | string ("annual" | "quarterly") | No | Report frequency: annual or quarterly. |
| `from_date` | string | No | Optional report end-date lower bound in YYYY-MM-DD format; provide with to_date. |
| `max_reports` | integer | No | Maximum reports returned by the tool; Finnhub does not paginate this endpoint. |
| `access_number` | string | No | SEC accession number for one specific report. Required when neither a ticker nor CIK is provided. |
| `include_statement_details` | boolean | No | Include full balance-sheet, cash-flow, and income-statement arrays. Leave false for compact report metadata because statement bodies can be large. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Calendar Events

**Slug:** `FINNHUB_LIST_CALENDAR_EVENTS`

List earnings releases or IPO events in an ordered date range. Use an earnings ticker or a narrow date window because Finnhub does not paginate or server-limit these calendars.

**Instant:** Supported on the latest version.

**Instant pricing:** $0.02 per Finnhub API request

**Discount:** 100

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `symbol` | string | No | Optional earnings ticker filter; unavailable for IPO events. |
| `to_date` | string | Yes | End date in YYYY-MM-DD format. |
| `from_date` | string | Yes | Start date in YYYY-MM-DD format. |
| `event_type` | string ("earnings" | "ipo") | Yes | Calendar dataset to query: earnings releases or IPO events. |
| `max_results` | integer | No | Maximum events returned by the tool. This local cap does not reduce Finnhub's upstream payload, so use a ticker or narrow date range. |
| `include_international` | boolean | No | For earnings only, include international markets. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Earnings Results

**Slug:** `FINNHUB_LIST_EARNINGS_RESULTS`

List a company's recent actual versus estimated earnings and surprise values.

**Instant:** Supported on the latest version.

**Instant pricing:** $0.02 per Finnhub API request

**Discount:** 100

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `symbol` | string | Yes | Company ticker, such as AAPL; must not be blank. |
| `max_results` | integer | No | Requested and locally enforced result cap. Finnhub may ignore the upstream limit; the free tier currently returns the last four quarters. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List SEC Filings

**Slug:** `FINNHUB_LIST_SEC_FILINGS`

List SEC filing metadata; a ticker, CIK, or accession number is required, optionally filtered by form and an ordered date range.

**Instant:** Supported on the latest version.

**Instant pricing:** $0.02 per Finnhub API request

**Discount:** 100

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cik` | string | No | SEC Central Index Key used to find filings. Required when neither a ticker nor an accession number is provided. |
| `form` | string | No | Optional SEC form filter, such as 10-K or NT 10-K. |
| `symbol` | string | No | Company ticker used to find filings. Required when neither CIK nor an accession number is provided. |
| `to_date` | string | No | Optional filing-date upper bound in YYYY-MM-DD format; provide with from_date. |
| `from_date` | string | No | Optional filing-date lower bound in YYYY-MM-DD format; provide with to_date. |
| `max_results` | integer | No | Maximum filings returned by the tool; Finnhub does not paginate this endpoint. |
| `access_number` | string | No | SEC accession number for one specific filing. Required when neither a ticker nor CIK is provided. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Search News

**Slug:** `FINNHUB_SEARCH_NEWS`

Get broad market news by category or company-specific news for an ordered date range. Use narrow company date ranges because Finnhub does not paginate or server-limit company news.

**Instant:** Supported on the latest version.

**Instant pricing:** $0.02 per Finnhub news API request

**Discount:** 100

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `min_id` | integer | No | For market news, return updates after this article ID. Use next_min_id from a prior untruncated response for incremental polling. |
| `symbol` | string | No | Exact company ticker. Required only when news_type is company. |
| `to_date` | string | No | Company-news end date in YYYY-MM-DD format. Required with from_date when news_type is company; unavailable for market news. |
| `category` | string ("general" | "forex" | "crypto" | "merger") | No | Market-news category. Required only when news_type is market. |
| `from_date` | string | No | Company-news start date in YYYY-MM-DD format. Required with to_date when news_type is company; unavailable for market news. |
| `news_type` | string ("market" | "company") | Yes | Use market for category news or company for ticker-specific news. |
| `max_results` | integer | No | Maximum articles returned by the tool. This local cap does not reduce Finnhub's company-news payload, so prefer narrow company date ranges. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Search Symbols

**Slug:** `FINNHUB_SEARCH_SYMBOLS`

Find tradable symbols by ticker, company name, ISIN, or CUSIP, optionally restricted to an exchange.

**Instant:** Supported on the latest version.

**Instant pricing:** $0.02 per Finnhub API request

**Discount:** 100

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Ticker, company name, ISIN, or CUSIP to search; must not be blank. |
| `exchange` | string | No | Optional Finnhub exchange code to restrict matches. |
| `max_results` | integer | No | Maximum matches returned by the tool; Finnhub provides no server-side limit. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |