# Q4 API

> Saudi market data, financial statements with page-level sources, filings, earnings call transcripts, announcements and government statistics for every company listed on the Saudi Exchange.

Base URL: https://api.q4.sa/v1. Auth header: x-api-key. OpenAPI: https://q4.sa/docs/openapi.json. Full text: https://q4.sa/docs/llms-full.txt.

## Overview

- [Introducing the Q4 API: the complete guide](https://q4.sa/blog/q4-api-saudi-stock-exchange-api): what the Q4 API covers, every endpoint, sourcing, realtime data, pricing and how to start.
- [Q4 API product page and pricing](https://q4.sa/q4-api)

## Overview

- [Introduction](https://q4.sa/docs)
- [Quickstart](https://q4.sa/docs/quickstart)
- [Data overview](https://q4.sa/docs/data-overview)
- [Plans and limits](https://q4.sa/docs/plans)

## Datasets

- [Companies](https://q4.sa/docs/datasets/companies)
- [Market data](https://q4.sa/docs/datasets/market-data)
- [Realtime & streaming](https://q4.sa/docs/datasets/realtime)
- [Fundamentals](https://q4.sa/docs/datasets/fundamentals)
- [Dividends & corporate actions](https://q4.sa/docs/datasets/dividends-and-actions)
- [Filings & reports](https://q4.sa/docs/datasets/filings)
- [Board reports](https://q4.sa/docs/datasets/board-reports)
- [Presentations](https://q4.sa/docs/datasets/presentations)
- [Earnings calls](https://q4.sa/docs/datasets/earnings-calls)
- [Announcements](https://q4.sa/docs/datasets/announcements)
- [Economic data](https://q4.sa/docs/datasets/economic-data)

## REST API

- [Authentication](https://q4.sa/docs/authentication)
- [Pagination and filtering](https://q4.sa/docs/pagination)
- [Rate limits](https://q4.sa/docs/rate-limits)
- [Errors](https://q4.sa/docs/errors)

## WebSocket

- [Connecting](https://q4.sa/docs/websocket/connecting)
- [Streams](https://q4.sa/docs/websocket/streams)
- [WebSocket errors](https://q4.sa/docs/websocket/errors)

## Webhooks

- [Webhooks](https://q4.sa/docs/webhooks/getting-started)
- [Webhook events](https://q4.sa/docs/webhooks/events)
- [Signatures](https://q4.sa/docs/webhooks/signatures)

## MCP

- [Q4 MCP connector](https://q4.sa/docs/mcp)

## More

- [Changelog](https://q4.sa/docs/changelog)
- [Support](https://q4.sa/docs/support)

## API reference: Companies

- [List companies](https://q4.sa/docs/api-reference/companies/list-companies): GET /companies. Lists listed companies, filtered by name, sector or market.
- [Retrieve a company](https://q4.sa/docs/api-reference/companies/get-company): GET /companies/{symbol}. Returns one company’s profile, shares and listing details.
- [List sectors](https://q4.sa/docs/api-reference/companies/list-sectors): GET /sectors. Lists the Tadawul sectors with how many companies are in each.

## API reference: Market data

- [Retrieve a quote](https://q4.sa/docs/api-reference/market/get-quote): GET /quote/{symbol}. Returns the latest price, change, volume and best bid and ask for one stock.
- [List quotes](https://q4.sa/docs/api-reference/market/list-quotes): GET /quotes. Returns quotes for up to 50 stocks in one call.
- [Retrieve price history](https://q4.sa/docs/api-reference/market/get-price-history): GET /prices/{symbol}/history. Returns OHLCV bars for a stock, adjusted for splits, bonus shares and rights issues.
- [Retrieve index history](https://q4.sa/docs/api-reference/market/get-index-history): GET /indices/{index}/history. Returns daily or intraday values for TASI, Nomu and the sector indices.
- [Retrieve market summary](https://q4.sa/docs/api-reference/market/get-market-summary): GET /market/summary. Returns the index level, breadth and totals for the session.
- [List market movers](https://q4.sa/docs/api-reference/market/list-market-movers): GET /market/movers. Returns the top gainers, losers, or most traded stocks by volume or value.
- [List sector performance](https://q4.sa/docs/api-reference/market/list-sector-performance): GET /market/sectors. Returns the day’s change, volume and value for every sector.
- [List trades](https://q4.sa/docs/api-reference/market/list-trades): GET /market/trades/{symbol}. Returns the latest executed trades for a stock, newest first.
- [Retrieve order book depth](https://q4.sa/docs/api-reference/market/get-order-book): GET /market/depth/{symbol}. Returns the best bids and asks for a stock, up to 20 levels deep.

## API reference: WebSocket

- [Quotes stream](https://q4.sa/docs/api-reference/streaming/stream-quotes): WS /ws/stocks. Pushes a quote every time a subscribed stock’s price, volume or best bid and ask changes.
- [Trades stream](https://q4.sa/docs/api-reference/streaming/stream-trades): WS /ws/trades. Pushes every executed trade for the stocks you subscribe to.
- [Depth stream](https://q4.sa/docs/api-reference/streaming/stream-depth): WS /ws/depth. Pushes the top 10 levels of the order book whenever they change.

## API reference: Fundamentals

- [Retrieve standardised statements](https://q4.sa/docs/api-reference/fundamentals/get-financials): GET /companies/{symbol}/financials. Returns income statements, balance sheets and cash flows mapped to standard line items, for comparing companies and periods.
- [Retrieve as-reported statements](https://q4.sa/docs/api-reference/fundamentals/get-as-reported): GET /companies/{symbol}/financials/as-reported. Returns a financial statement exactly as the company printed it: every line, in order, with its subtotals and note references.
- [List figures](https://q4.sa/docs/api-reference/fundamentals/list-facts): GET /companies/{symbol}/facts. Returns every number printed in a company’s filings, including the notes to the financial statements, with the page and position it came from.
- [Retrieve ratios](https://q4.sa/docs/api-reference/fundamentals/get-ratios): GET /companies/{symbol}/ratios. Returns valuation, profitability, leverage and growth ratios by period.
- [Compare companies](https://q4.sa/docs/api-reference/fundamentals/compare-companies): GET /compare. Returns the same metrics side by side for several companies.
- [List dividends](https://q4.sa/docs/api-reference/fundamentals/list-dividends): GET /companies/{symbol}/dividends. Returns announced and paid cash dividends, with eligibility and payment dates.
- [List corporate actions](https://q4.sa/docs/api-reference/fundamentals/list-corporate-actions): GET /companies/{symbol}/corporate-actions. Returns rights issues, bonus shares, capital changes, buybacks and splits.
- [List stock events](https://q4.sa/docs/api-reference/fundamentals/list-events): GET /events. A single feed of results, dividends, AGMs, capital changes and other material events.
- [Search notes](https://q4.sa/docs/api-reference/fundamentals/search-notes): GET /companies/{symbol}/notes. Finds notes across all of a company’s financial reports by title or text, e.g. every segment note since 2020.

## API reference: Documents

- [List documents](https://q4.sa/docs/api-reference/documents/list-documents): GET /documents. Lists filings and decks, newest first, filtered by company, type and period.
- [Retrieve a document](https://q4.sa/docs/api-reference/documents/get-document): GET /documents/{id}. Returns one document’s metadata and a signed link to the PDF.
- [List document pages](https://q4.sa/docs/api-reference/documents/list-document-pages): GET /documents/{id}/pages. Returns the extracted text of each page, with detected tables.
- [Retrieve document text](https://q4.sa/docs/api-reference/documents/get-document-text): GET /documents/{id}/text. Returns the whole document as plain text or Markdown, with page markers.
- [Retrieve document summary](https://q4.sa/docs/api-reference/documents/get-document-summary): GET /documents/{id}/summary. Returns an AI summary of the document, each point cited to its page.
- [List notes](https://q4.sa/docs/api-reference/documents/list-document-notes): GET /documents/{id}/notes. Lists the notes to the financial statements in a financial report, in order, with their pages.
- [Retrieve a note](https://q4.sa/docs/api-reference/documents/get-document-note): GET /documents/{id}/notes/{number}. Returns one note’s full text, its tables, and the figures in them.
- [List sections](https://q4.sa/docs/api-reference/documents/list-document-sections): GET /documents/{id}/sections. Lists the chapters of a board report, in order, each tagged with a standard category.
- [Retrieve a section](https://q4.sa/docs/api-reference/documents/get-document-section): GET /documents/{id}/sections/{section_id}. Returns one board report chapter in full: its text paragraph by paragraph with pages, and its tables with the figures in them.
- [Search board report sections](https://q4.sa/docs/api-reference/documents/search-sections): GET /companies/{symbol}/sections. Returns the same board report chapter across years, e.g. directors’ remuneration since 2020.

## API reference: Earnings calls

- [List earnings calls](https://q4.sa/docs/api-reference/earnings-calls/list-earnings-calls): GET /earnings-calls. Lists recorded earnings calls, newest first.
- [Retrieve an earnings call](https://q4.sa/docs/api-reference/earnings-calls/get-earnings-call): GET /earnings-calls/{id}. Returns one call’s details, speakers and linked presentation.
- [Retrieve a transcript](https://q4.sa/docs/api-reference/earnings-calls/get-transcript): GET /earnings-calls/{id}/transcript. Returns the transcript by speaker turn, with start and end times, or word by word.
- [Retrieve call audio](https://q4.sa/docs/api-reference/earnings-calls/get-audio): GET /earnings-calls/{id}/audio. Returns a signed link to the call recording.

## API reference: Announcements

- [List announcements](https://q4.sa/docs/api-reference/announcements/list-announcements): GET /announcements. Lists issuer announcements published on Tadawul, newest first.
- [Retrieve an announcement](https://q4.sa/docs/api-reference/announcements/get-announcement): GET /announcements/{id}. Returns one announcement with its full text and HTML.

## API reference: Economic data

- [List series](https://q4.sa/docs/api-reference/economic/list-series): GET /economic/series. Lists the government statistics series we publish, by source and topic.
- [List observations](https://q4.sa/docs/api-reference/economic/list-observations): GET /economic/series/{key}/observations. Returns a series’ values over time, optionally split by its dimensions.

## API reference: Webhooks & alerts

- [Create a webhook](https://q4.sa/docs/api-reference/webhooks/create-webhook): POST /webhooks. Registers an HTTPS endpoint to receive events.
- [List webhooks](https://q4.sa/docs/api-reference/webhooks/list-webhooks): GET /webhooks. Lists your webhook endpoints and their delivery health.
- [Delete a webhook](https://q4.sa/docs/api-reference/webhooks/delete-webhook): DELETE /webhooks/{id}. Stops deliveries to an endpoint and deletes it.
- [Create an alert rule](https://q4.sa/docs/api-reference/webhooks/create-alert): POST /alerts. Sends an `alert.triggered` webhook when a price or volume condition is met.
- [List alert rules](https://q4.sa/docs/api-reference/webhooks/list-alerts): GET /alerts. Lists your alert rules and when they last fired.
- [Delete an alert rule](https://q4.sa/docs/api-reference/webhooks/delete-alert): DELETE /alerts/{id}. Deletes an alert rule.

## API reference: Account

- [Retrieve usage](https://q4.sa/docs/api-reference/account/get-usage): GET /usage. Returns your plan, today’s request count and when the quota resets. Does not count towards it.