{"openapi":"3.1.0","info":{"title":"Q4 API","version":"1.0.0","description":"Saudi market data, fundamentals, filings, earnings calls, announcements and economic data.","contact":{"email":"api@q4.sa"}},"servers":[{"url":"https://api.q4.sa/v1"}],"security":[{"apiKey":[]}],"tags":[{"name":"Companies","description":"Every company listed on the Saudi Exchange main market and Nomu, with profiles and sectors."},{"name":"Market data","description":"Quotes, price history, indices, market breadth, trades and order book depth."},{"name":"Fundamentals","description":"Financial statements, every printed figure with its page, ratios, dividends, corporate actions and stock events."},{"name":"Documents","description":"Financial reports, board reports, presentations and prospectuses, with page text and summaries."},{"name":"Earnings calls","description":"Earnings call recordings with word-timed transcripts."},{"name":"Announcements","description":"Issuer announcements published on Tadawul."},{"name":"Economic data","description":"Saudi government statistics from GASTAT, SAMA and Tadawul."},{"name":"Webhooks & alerts","description":"Register endpoints for push notifications and price alert rules."},{"name":"Account","description":"Your plan and remaining quota."}],"paths":{"/companies":{"get":{"operationId":"listCompanies","summary":"List companies","description":"Lists listed companies, filtered by name, sector or market.\n\nPlan: Free.","tags":["Companies"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/companies/list-companies"},"x-plan":"free","parameters":[{"name":"search","in":"query","required":false,"description":"Matches English and Arabic names and common aliases (e.g. \"aramco\", \"الراجحي\").","schema":{"type":"string"}},{"name":"symbols","in":"query","required":false,"description":"Comma-separated Tadawul symbols. Matches any of them.","schema":{"type":"string","description":"Comma-separated list."}},{"name":"sector","in":"query","required":false,"description":"Sector slug from [List sectors](/docs/api-reference/companies/list-sectors), e.g. `banks`.","schema":{"type":"string"}},{"name":"market","in":"query","required":false,"description":"Main market or Nomu.","schema":{"type":"string","enum":["main","nomu"]}},{"name":"status","in":"query","required":false,"description":"Listing status.","schema":{"type":"string","enum":["active","suspended","delisted"],"default":"active"}},{"name":"limit","in":"query","required":false,"description":"Results per page.","schema":{"type":"integer","default":100,"minimum":1,"maximum":500}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Omit it for the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"isin":{"type":"string"},"name_en":{"type":"string"},"name_ar":{"type":"string"},"market":{"type":"string"},"sector":{"type":"string"},"status":{"type":"string"},"is_etf":{"type":"boolean"}}}},"pagination":{"type":"object","properties":{"next_cursor":{"type":"string"},"limit":{"type":"integer"}}}}},"example":{"data":[{"symbol":"1120","isin":"SA0007879113","name_en":"Al Rajhi Banking and Investment Corp.","name_ar":"مصرف الراجحي","market":"main","sector":"banks","status":"active","is_etf":false},{"symbol":"1180","isin":"SA13L050IE10","name_en":"The Saudi National Bank","name_ar":"البنك الأهلي السعودي","market":"main","sector":"banks","status":"active","is_etf":false}],"pagination":{"next_cursor":"eyJpZCI6MTIwfQ","limit":50}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{symbol}":{"get":{"operationId":"getCompany","summary":"Retrieve a company","description":"Returns one company’s profile, shares and listing details.\n\nPlan: Free. Valuation fields (`market_cap`, `pe_ratio`, `pb_ratio`) need Starter+.","tags":["Companies"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/companies/get-company"},"x-plan":"free","parameters":[{"name":"symbol","in":"path","required":true,"description":"Tadawul symbol, e.g. `2222` for Saudi Aramco. ISINs are accepted too.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"symbol":{"type":"string"},"isin":{"type":"string"},"name_en":{"type":"string"},"name_ar":{"type":"string"},"market":{"type":"string"},"sector":{"type":"string"},"industry":{"type":"string"},"status":{"type":"string"},"listed_on":{"type":"string","format":"date"},"issued_shares":{"type":"integer"},"currency":{"type":"string"},"fiscal_year_end":{"type":"string"},"website":{"type":"string"},"description":{"type":"string"},"market_cap":{"type":"integer"},"pe_ratio":{"type":"number"},"pb_ratio":{"type":"number"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"data":{"symbol":"2222","isin":"SA14TG012N13","name_en":"Saudi Arabian Oil Co.","name_ar":"أرامكو السعودية","market":"main","sector":"energy","industry":"Oil & Gas Integrated","status":"active","listed_on":"2019-12-11","issued_shares":242000000000,"currency":"SAR","fiscal_year_end":"12-31","website":"https://www.aramco.com","description":"Integrated energy and chemicals company…","market_cap":6151640000000,"pe_ratio":16.8,"pb_ratio":4.1,"updated_at":"2026-11-03T13:35:00Z"}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sectors":{"get":{"operationId":"listSectors","summary":"List sectors","description":"Lists the Tadawul sectors with how many companies are in each.\n\nPlan: Free.","tags":["Companies"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/companies/list-sectors"},"x-plan":"free","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name_en":{"type":"string"},"name_ar":{"type":"string"},"companies":{"type":"integer"}}}}}},"example":{"data":[{"slug":"banks","name_en":"Banks","name_ar":"البنوك","companies":10},{"slug":"energy","name_en":"Energy","name_ar":"الطاقة","companies":8},{"slug":"materials","name_en":"Materials","name_ar":"المواد الأساسية","companies":48}]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/quote/{symbol}":{"get":{"operationId":"getQuote","summary":"Retrieve a quote","description":"Returns the latest price, change, volume and best bid and ask for one stock.\n\nPlan: Free. Free and Starter get prices delayed by 15 minutes. Realtime needs Pro+.","tags":["Market data"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/market/get-quote"},"x-plan":"free","parameters":[{"name":"symbol","in":"path","required":true,"description":"Tadawul symbol, e.g. `2222` for Saudi Aramco. ISINs are accepted too.","schema":{"type":"string"}},{"name":"data_mode","in":"query","required":false,"description":"Realtime needs Pro+. Defaults to the freshest data your plan allows: realtime on Pro+, 15-minute delayed below.","schema":{"type":"string","enum":["realtime","delayed"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"symbol":{"type":"string"},"name_en":{"type":"string"},"price":{"type":"number"},"change":{"type":"number"},"change_percent":{"type":"number"},"open":{"type":"number"},"high":{"type":"number"},"low":{"type":"number"},"previous_close":{"type":"number"},"volume":{"type":"integer"},"turnover":{"type":"number"},"trades":{"type":"integer"},"bid":{"type":"number"},"bid_size":{"type":"integer"},"ask":{"type":"number"},"ask_size":{"type":"integer"},"week_52_high":{"type":"number"},"week_52_low":{"type":"number"},"session":{"type":"string"},"is_delayed":{"type":"boolean"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"data":{"symbol":"2222","name_en":"Saudi Arabian Oil Co.","price":25.42,"change":0.18,"change_percent":0.71,"open":25.24,"high":25.5,"low":25.2,"previous_close":25.24,"volume":14382911,"turnover":365104220.6,"trades":21874,"bid":25.4,"bid_size":182400,"ask":25.42,"ask_size":96310,"week_52_high":28.95,"week_52_low":23.1,"session":"open","is_delayed":true,"updated_at":"2026-11-04T10:42:13Z"}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/quotes":{"get":{"operationId":"listQuotes","summary":"List quotes","description":"Returns quotes for up to 50 stocks in one call.\n\nPlan: Starter+. Realtime needs Pro+.","tags":["Market data"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/market/list-quotes"},"x-plan":"starter","parameters":[{"name":"symbols","in":"query","required":true,"description":"Comma-separated Tadawul symbols, up to 50.","schema":{"type":"string","description":"Comma-separated list."}},{"name":"data_mode","in":"query","required":false,"description":"Realtime needs Pro+. Defaults to the freshest data your plan allows: realtime on Pro+, 15-minute delayed below.","schema":{"type":"string","enum":["realtime","delayed"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"price":{"type":"number"},"change":{"type":"number"},"change_percent":{"type":"number"},"volume":{"type":"integer"},"is_delayed":{"type":"boolean"},"updated_at":{"type":"string","format":"date-time"}}}},"missing":{"type":"array","items":{}}}},"example":{"data":[{"symbol":"2222","price":25.42,"change":0.18,"change_percent":0.71,"volume":14382911,"is_delayed":true,"updated_at":"2026-11-04T10:42:13Z"},{"symbol":"1120","price":95.3,"change":-0.6,"change_percent":-0.63,"volume":3104552,"is_delayed":true,"updated_at":"2026-11-04T10:42:11Z"},{"symbol":"2010","price":58.1,"change":0.4,"change_percent":0.69,"volume":1877204,"is_delayed":true,"updated_at":"2026-11-04T10:42:09Z"}],"missing":[]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/prices/{symbol}/history":{"get":{"operationId":"getPriceHistory","summary":"Retrieve price history","description":"Returns OHLCV bars for a stock, adjusted for splits, bonus shares and rights issues.\n\nDaily bars go back to the stock’s listing. Intraday bars (`1min` to `60min`) cover 90 days on Pro and 2 years on Business.\n\nThe latest bar is marked `is_final: false` until the closing auction ends.\n\nPlan: Starter+. Intraday intervals need Pro+.","tags":["Market data"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/market/get-price-history"},"x-plan":"starter","parameters":[{"name":"symbol","in":"path","required":true,"description":"Tadawul symbol, e.g. `2222` for Saudi Aramco. ISINs are accepted too.","schema":{"type":"string"}},{"name":"interval","in":"query","required":false,"description":"Bar size.","schema":{"type":"string","enum":["1min","5min","15min","30min","60min","1d","1w","1mo"],"default":"1d"}},{"name":"from","in":"query","required":false,"description":"Start date, inclusive (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"End date, inclusive (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"adjusted","in":"query","required":false,"description":"Adjust prices and volumes for corporate actions.","schema":{"type":"boolean","default":true}},{"name":"limit","in":"query","required":false,"description":"Results per page.","schema":{"type":"integer","default":500,"minimum":1,"maximum":2000}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Omit it for the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"open":{"type":"number"},"high":{"type":"integer"},"low":{"type":"number"},"close":{"type":"number"},"volume":{"type":"integer"},"turnover":{"type":"number"},"trades":{"type":"integer"},"is_final":{"type":"boolean"}}}},"pagination":{"type":"object","properties":{"next_cursor":{"type":"string"},"limit":{"type":"integer"}}}}},"example":{"data":[{"date":"2026-10-30","open":94.8,"high":96,"low":94.5,"close":95.9,"volume":3412870,"turnover":325884011.2,"trades":9884,"is_final":true},{"date":"2026-10-29","open":95.2,"high":95.4,"low":94.3,"close":94.8,"volume":2975118,"turnover":282401760.9,"trades":8412,"is_final":true}],"pagination":{"next_cursor":"eyJpZCI6MTIwfQ","limit":50}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/indices/{index}/history":{"get":{"operationId":"getIndexHistory","summary":"Retrieve index history","description":"Returns daily or intraday values for TASI, Nomu and the sector indices.\n\nPlan: Starter+. Intraday intervals need Pro+.","tags":["Market data"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/market/get-index-history"},"x-plan":"starter","parameters":[{"name":"index","in":"path","required":true,"description":"`TASI`, `NOMU`, or a sector index such as `TBNI` (banks).","schema":{"type":"string"}},{"name":"interval","in":"query","required":false,"description":"Bar size.","schema":{"type":"string","enum":["1min","5min","15min","60min","1d","1w","1mo"],"default":"1d"}},{"name":"from","in":"query","required":false,"description":"Start date, inclusive (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"End date, inclusive (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","required":false,"description":"Results per page.","schema":{"type":"integer","default":500,"minimum":1,"maximum":2000}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Omit it for the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"open":{"type":"number"},"high":{"type":"number"},"low":{"type":"number"},"close":{"type":"number"},"volume":{"type":"integer"},"turnover":{"type":"integer"}}}},"pagination":{"type":"object","properties":{"next_cursor":{"type":"string"},"limit":{"type":"integer"}}}}},"example":{"data":[{"date":"2026-10-30","open":11842.6,"high":11915.3,"low":11820.1,"close":11903.8,"volume":268430112,"turnover":6702118400}],"pagination":{"next_cursor":"eyJpZCI6MTIwfQ","limit":50}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/summary":{"get":{"operationId":"getMarketSummary","summary":"Retrieve market summary","description":"Returns the index level, breadth and totals for the session.\n\nPlan: Free.","tags":["Market data"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/market/get-market-summary"},"x-plan":"free","parameters":[{"name":"index","in":"query","required":false,"description":"Market: the main market (TASI) or the parallel market (Nomu).","schema":{"type":"string","enum":["TASI","NOMU"],"default":"TASI"}},{"name":"data_mode","in":"query","required":false,"description":"Realtime needs Pro+. Defaults to the freshest data your plan allows: realtime on Pro+, 15-minute delayed below.","schema":{"type":"string","enum":["realtime","delayed"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"index":{"type":"string"},"value":{"type":"number"},"change":{"type":"number"},"change_percent":{"type":"number"},"volume":{"type":"integer"},"turnover":{"type":"integer"},"trades":{"type":"integer"},"advancing":{"type":"integer"},"declining":{"type":"integer"},"unchanged":{"type":"integer"},"session":{"type":"string"},"is_delayed":{"type":"boolean"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"data":{"index":"TASI","value":11903.8,"change":61.2,"change_percent":0.52,"volume":268430112,"turnover":6702118400,"trades":512870,"advancing":142,"declining":81,"unchanged":23,"session":"closed","is_delayed":true,"updated_at":"2026-11-03T12:20:00Z"}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/movers":{"get":{"operationId":"listMarketMovers","summary":"List market movers","description":"Returns the top gainers, losers, or most traded stocks by volume or value.\n\nPlan: Free.","tags":["Market data"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/market/list-market-movers"},"x-plan":"free","parameters":[{"name":"type","in":"query","required":true,"description":"How to rank stocks.","schema":{"type":"string","enum":["gainers","losers","volume","value"]}},{"name":"index","in":"query","required":false,"description":"Market: the main market (TASI) or the parallel market (Nomu).","schema":{"type":"string","enum":["TASI","NOMU"],"default":"TASI"}},{"name":"limit","in":"query","required":false,"description":"Results per page.","schema":{"type":"integer","default":10,"minimum":1,"maximum":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"name_en":{"type":"string"},"price":{"type":"number"},"change_percent":{"type":"number"},"volume":{"type":"integer"},"turnover":{"type":"integer"}}}}}},"example":{"data":[{"symbol":"4030","name_en":"National Shipping Co.","price":31.6,"change_percent":6.4,"volume":8120440,"turnover":252890311},{"symbol":"2380","name_en":"Rabigh Refining and Petrochemical Co.","price":8.92,"change_percent":5.2,"volume":21002118,"turnover":184330102},{"symbol":"1211","name_en":"Saudi Arabian Mining Co. (Ma'aden)","price":52.4,"change_percent":3.9,"volume":4418002,"turnover":228940611}]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/sectors":{"get":{"operationId":"listSectorPerformance","summary":"List sector performance","description":"Returns the day’s change, volume and value for every sector.\n\nPlan: Free.","tags":["Market data"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/market/list-sector-performance"},"x-plan":"free","parameters":[{"name":"index","in":"query","required":false,"description":"Market: the main market (TASI) or the parallel market (Nomu).","schema":{"type":"string","enum":["TASI","NOMU"],"default":"TASI"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"sector":{"type":"string"},"name_en":{"type":"string"},"change_percent":{"type":"number"},"volume":{"type":"integer"},"turnover":{"type":"integer"},"advancing":{"type":"integer"},"declining":{"type":"integer"}}}}}},"example":{"data":[{"sector":"banks","name_en":"Banks","change_percent":0.84,"volume":41220318,"turnover":1402118900,"advancing":7,"declining":3},{"sector":"energy","name_en":"Energy","change_percent":0.41,"volume":22901007,"turnover":611330405,"advancing":5,"declining":3}]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/trades/{symbol}":{"get":{"operationId":"listTrades","summary":"List trades","description":"Returns the latest executed trades for a stock, newest first.\n\nPlan: Business+.","tags":["Market data"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/market/list-trades"},"x-plan":"business","parameters":[{"name":"symbol","in":"path","required":true,"description":"Tadawul symbol, e.g. `2222` for Saudi Aramco. ISINs are accepted too.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Results per page.","schema":{"type":"integer","default":50,"minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"trade_id":{"type":"string"},"time":{"type":"string","format":"date-time"},"price":{"type":"number"},"quantity":{"type":"integer"},"value":{"type":"integer"},"side":{"type":"string"}}}}}},"example":{"data":[{"trade_id":"T-2026110400021874","time":"2026-11-04T10:42:13.412Z","price":25.42,"quantity":1200,"value":30504,"side":"buy"},{"trade_id":"T-2026110400021873","time":"2026-11-04T10:42:12.980Z","price":25.4,"quantity":5000,"value":127000,"side":"sell"}]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/depth/{symbol}":{"get":{"operationId":"getOrderBook","summary":"Retrieve order book depth","description":"Returns the best bids and asks for a stock, up to 20 levels deep.\n\nPlan: Business+.","tags":["Market data"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/market/get-order-book"},"x-plan":"business","parameters":[{"name":"symbol","in":"path","required":true,"description":"Tadawul symbol, e.g. `2222` for Saudi Aramco. ISINs are accepted too.","schema":{"type":"string"}},{"name":"levels","in":"query","required":false,"description":"Price levels per side.","schema":{"type":"integer","default":10,"minimum":1,"maximum":20}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"symbol":{"type":"string"},"best_bid":{"type":"number"},"best_ask":{"type":"number"},"spread":{"type":"number"},"spread_bps":{"type":"number"},"bids":{"type":"array","items":{"type":"object","properties":{"level":{"type":"integer"},"price":{"type":"number"},"quantity":{"type":"integer"},"orders":{"type":"integer"}}}},"asks":{"type":"array","items":{"type":"object","properties":{"level":{"type":"integer"},"price":{"type":"number"},"quantity":{"type":"integer"},"orders":{"type":"integer"}}}},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"data":{"symbol":"2222","best_bid":25.4,"best_ask":25.42,"spread":0.02,"spread_bps":7.9,"bids":[{"level":1,"price":25.4,"quantity":182400,"orders":41},{"level":2,"price":25.38,"quantity":240118,"orders":63}],"asks":[{"level":1,"price":25.42,"quantity":96310,"orders":22},{"level":2,"price":25.44,"quantity":310552,"orders":58}],"updated_at":"2026-11-04T10:42:13.412Z"}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{symbol}/financials":{"get":{"operationId":"getFinancials","summary":"Retrieve standardised statements","description":"Returns income statements, balance sheets and cash flows mapped to standard line items, for comparing companies and periods.\n\nLine items use Q4’s standard metric keys, so the same key means the same thing for every company. Every value links back to the printed figure it came from: follow `fact_id` to [List figures](/docs/api-reference/fundamentals/list-facts).\n\nOnly lines that map to a standard key are returned. For every line exactly as the company printed it, use [Retrieve as-reported statements](/docs/api-reference/fundamentals/get-as-reported).\n\nPlan: Starter+.","tags":["Fundamentals"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/fundamentals/get-financials"},"x-plan":"starter","parameters":[{"name":"symbol","in":"path","required":true,"description":"Tadawul symbol, e.g. `2222` for Saudi Aramco. ISINs are accepted too.","schema":{"type":"string"}},{"name":"statement","in":"query","required":false,"description":"Which statement.","schema":{"type":"string","enum":["income","balance","cash_flow","all"],"default":"all"}},{"name":"period","in":"query","required":false,"description":"Fiscal years, quarters, or trailing twelve months.","schema":{"type":"string","enum":["annual","quarterly","ttm"],"default":"annual"}},{"name":"from_year","in":"query","required":false,"description":"First fiscal year.","schema":{"type":"integer"}},{"name":"to_year","in":"query","required":false,"description":"Last fiscal year.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"symbol":{"type":"string"},"currency":{"type":"string"},"periods":{"type":"array","items":{"type":"object","properties":{"fiscal_year":{"type":"integer"},"fiscal_period":{"type":"string"},"period_end":{"type":"string","format":"date"},"statement":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"metric":{"type":"string"},"label":{"type":"string"},"value":{"type":"integer"},"fact_id":{"type":"string"},"restated":{"type":"boolean"}}}},"source_document_id":{"type":"string"}}}}}}}},"example":{"data":{"symbol":"1120","currency":"SAR","periods":[{"fiscal_year":2025,"fiscal_period":"FY","period_end":"2025-12-31","statement":"income","items":[{"metric":"total_operating_income","label":"Total operating income","value":36412000000,"fact_id":"fct_9Qm2Lr","restated":false},{"metric":"net_income","label":"Net income for the year","value":21802000000,"fact_id":"fct_9Qm2Lx","restated":false},{"metric":"eps_basic","label":"Basic earnings per share","value":5.32,"fact_id":"fct_9Qm2M4","restated":false}],"source_document_id":"doc_7Hk2pQ"}]}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{symbol}/financials/as-reported":{"get":{"operationId":"getAsReported","summary":"Retrieve as-reported statements","description":"Returns a financial statement exactly as the company printed it: every line, in order, with its subtotals and note references.\n\nNothing is renamed, merged or dropped. Rows keep the company’s own labels, order and indentation, and every cell links to its printed figure with `fact_id`.\n\nWhen a row cites a note, `note` holds the note number: pass it to [Retrieve a note](/docs/api-reference/documents/get-document-note) to read the footnote behind the line.\n\nBy default the statement comes from the latest filing for the period, so restated comparatives show their restated values. Pass `document_id` to see a specific filing as published.\n\nPlan: Starter+.","tags":["Fundamentals"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/fundamentals/get-as-reported"},"x-plan":"starter","parameters":[{"name":"symbol","in":"path","required":true,"description":"Tadawul symbol, e.g. `2222` for Saudi Aramco. ISINs are accepted too.","schema":{"type":"string"}},{"name":"statement","in":"query","required":true,"description":"Which statement.","schema":{"type":"string","enum":["income","comprehensive_income","balance","changes_in_equity","cash_flow"]}},{"name":"fiscal_year","in":"query","required":false,"description":"Fiscal year. Defaults to the latest.","schema":{"type":"integer"}},{"name":"fiscal_period","in":"query","required":false,"description":"Annual or interim statement.","schema":{"type":"string","enum":["FY","Q1","Q2","Q3","Q4"],"default":"FY"}},{"name":"document_id","in":"query","required":false,"description":"Use this filing instead of the latest one for the period.","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"The English or Arabic version of the filing.","schema":{"type":"string","enum":["en","ar"],"default":"en"}},{"name":"include_unverified","in":"query","required":false,"description":"Include cells we could not read with confidence. They come back with `verified: false`.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"symbol":{"type":"string"},"statement":{"type":"string"},"title":{"type":"string"},"document_id":{"type":"string"},"page":{"type":"integer"},"currency":{"type":"string"},"scale":{"type":"string"},"columns":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"fiscal_year":{"type":"integer"},"period_end":{"type":"string","format":"date"}}}},"rows":{"type":"array","items":{"type":"object","properties":{"line":{"type":"integer"},"label":{"type":"string"},"depth":{"type":"integer"},"kind":{"type":"string"},"note":{"type":"string"},"cells":{"type":"object","properties":{"c1":{"type":"object","properties":{"value":{"type":"integer"},"printed":{"type":"string"},"fact_id":{"type":"string"},"verified":{"type":"boolean"}}},"c2":{"type":"object","properties":{"value":{"type":"integer"},"printed":{"type":"string"},"fact_id":{"type":"string"},"verified":{"type":"boolean"}}}}}}}}}}}},"example":{"data":{"symbol":"1120","statement":"income","title":"CONSOLIDATED STATEMENT OF INCOME","document_id":"doc_7Hk2pQ","page":14,"currency":"SAR","scale":"thousands","columns":[{"key":"c1","label":"2025","fiscal_year":2025,"period_end":"2025-12-31"},{"key":"c2","label":"2024","fiscal_year":2024,"period_end":"2024-12-31"}],"rows":[{"line":1,"label":"Income from investments and financing","depth":1,"kind":"item","note":"24","cells":{"c1":{"value":52118402000,"printed":"52,118,402","fact_id":"fct_9Qm2La","verified":true},"c2":{"value":47390118000,"printed":"47,390,118","fact_id":"fct_7Tz1Ka","verified":true}}},{"line":2,"label":"Return on deposits and financial liabilities","depth":1,"kind":"item","note":"24","cells":{"c1":{"value":-21664870000,"printed":"(21,664,870)","fact_id":"fct_9Qm2Lb","verified":true},"c2":{"value":-19882305000,"printed":"(19,882,305)","fact_id":"fct_7Tz1Kb","verified":true}}},{"line":3,"label":"Income from investments and financing, net","depth":0,"kind":"subtotal","note":null,"cells":{"c1":{"value":30453532000,"printed":"30,453,532","fact_id":"fct_9Qm2Lc","verified":true},"c2":{"value":27507813000,"printed":"27,507,813","fact_id":"fct_7Tz1Kc","verified":true}}},{"line":18,"label":"Net income for the year","depth":0,"kind":"total","note":null,"cells":{"c1":{"value":21802045000,"printed":"21,802,045","fact_id":"fct_9Qm2Lx","verified":true},"c2":{"value":18480112000,"printed":"18,480,112","fact_id":"fct_7Tz1Kx","verified":true}}}]}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{symbol}/facts":{"get":{"operationId":"listFacts","summary":"List figures","description":"Returns every number printed in a company’s filings, including the notes to the financial statements, with the page and position it came from.\n\nThis is the raw layer under the financial statements: one row per table cell, as printed, with the parsed value in base units. Use `page` and `bbox` to highlight the figure on the PDF.\n\nIt covers the primary statements **and every table in the notes**: segment results, loan books by stage, maturity profiles, related-party balances, and so on. Note figures have `statement: \"note\"` and carry the note they sit under in `note_title`, plus the headings above them in `header_path`. For the note’s written text, use [Retrieve a note](/docs/api-reference/documents/get-document-note).\n\nWhen a later filing restates a figure, the old value stays in `restatements`.\n\nPlan: Starter+.","tags":["Fundamentals"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/fundamentals/list-facts"},"x-plan":"starter","parameters":[{"name":"symbol","in":"path","required":true,"description":"Tadawul symbol, e.g. `2222` for Saudi Aramco. ISINs are accepted too.","schema":{"type":"string"}},{"name":"statement","in":"query","required":false,"description":"Comma-separated: `income`, `balance`, `cash_flow`, `comprehensive_income`, `changes_in_equity`, `note`, `other`. Use `note` for tables in the notes to the financial statements.","schema":{"type":"string","description":"Comma-separated list."}},{"name":"note","in":"query","required":false,"description":"Only figures under notes whose title matches, e.g. `segment` or `27`.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Search row labels and headings, e.g. `stage 3` or `related parties`.","schema":{"type":"string"}},{"name":"metric","in":"query","required":false,"description":"Standard metric key, e.g. `net_income`. Unmapped rows, including most note rows, have none.","schema":{"type":"string"}},{"name":"fiscal_year","in":"query","required":false,"description":"Fiscal year of the period the figure describes.","schema":{"type":"integer"}},{"name":"fiscal_period","in":"query","required":false,"description":"Period the figure describes.","schema":{"type":"string","enum":["FY","Q1","Q2","Q3","Q4","H1","9M"]}},{"name":"document_id","in":"query","required":false,"description":"Only figures from this document. With no other filter, returns every line item in the filing, statements and notes.","schema":{"type":"string"}},{"name":"include_unverified","in":"query","required":false,"description":"Include figures we could not read with confidence. They come back with `verified: false`.","schema":{"type":"boolean","default":false}},{"name":"updated_after","in":"query","required":false,"description":"Only items created or changed after this time. Use it to sync incrementally.","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","required":false,"description":"Results per page.","schema":{"type":"integer","default":100,"minimum":1,"maximum":500}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Omit it for the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"metric":{"type":["string","null"]},"statement":{"type":"string"},"note_title":{"type":"string"},"section_label":{"type":"string"},"header_path":{"type":"array","items":{"type":"string"}},"row_label":{"type":"string"},"column_label":{"type":"string"},"fiscal_year":{"type":"integer"},"fiscal_period":{"type":"string"},"period_start":{"type":"string","format":"date"},"period_end":{"type":"string","format":"date"},"printed_value":{"type":"string"},"value":{"type":"integer"},"unit":{"type":"string"},"scale":{"type":"string"},"document_id":{"type":"string"},"page":{"type":"integer"},"bbox":{"type":"array","items":{"type":"number"}},"verified":{"type":"boolean"},"restatements":{"type":"array","items":{}}}}},"pagination":{"type":"object","properties":{"next_cursor":{"type":"string"},"limit":{"type":"integer"}}}}},"example":{"data":[{"id":"fct_4Rb8Tn","metric":null,"statement":"note","note_title":"27. SEGMENT INFORMATION","section_label":"Retail","header_path":["Segment information","For the year ended 31 December 2025"],"row_label":"Net income for the year","column_label":"Retail","fiscal_year":2025,"fiscal_period":"FY","period_start":"2025-01-01","period_end":"2025-12-31","printed_value":"12,418,302","value":12418302000,"unit":"SAR","scale":"thousands","document_id":"doc_7Hk2pQ","page":71,"bbox":[305.1,402.7,371.6,414.9],"verified":true,"restatements":[]},{"id":"fct_9Qm2Lx","metric":"net_income","statement":"income","note_title":null,"section_label":null,"header_path":["Consolidated statement of income"],"row_label":"Net income for the year","column_label":"2025","fiscal_year":2025,"fiscal_period":"FY","period_start":"2025-01-01","period_end":"2025-12-31","printed_value":"21,802,045","value":21802045000,"unit":"SAR","scale":"thousands","document_id":"doc_7Hk2pQ","page":14,"bbox":[412.5,318.2,488.9,330.6],"verified":true,"restatements":[]}],"pagination":{"next_cursor":"eyJpZCI6MTIwfQ","limit":50}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{symbol}/ratios":{"get":{"operationId":"getRatios","summary":"Retrieve ratios","description":"Returns valuation, profitability, leverage and growth ratios by period.\n\nPlan: Starter+.","tags":["Fundamentals"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/fundamentals/get-ratios"},"x-plan":"starter","parameters":[{"name":"symbol","in":"path","required":true,"description":"Tadawul symbol, e.g. `2222` for Saudi Aramco. ISINs are accepted too.","schema":{"type":"string"}},{"name":"period","in":"query","required":false,"description":"Period basis.","schema":{"type":"string","enum":["annual","quarterly","ttm"],"default":"annual"}},{"name":"history","in":"query","required":false,"description":"How far back.","schema":{"type":"string","enum":["1y","3y","5y","10y","max"],"default":"5y"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"period_end":{"type":"string","format":"date"},"pe_ratio":{"type":"number"},"pb_ratio":{"type":"number"},"ev_to_ebitda":{"type":"number"},"dividend_yield":{"type":"number"},"roe":{"type":"number"},"roa":{"type":"number"},"net_margin":{"type":"number"},"debt_to_equity":{"type":"number"},"current_ratio":{"type":"number"},"revenue_growth":{"type":"number"}}}}}},"example":{"data":[{"period_end":"2026-09-30","pe_ratio":21.4,"pb_ratio":1.6,"ev_to_ebitda":9.8,"dividend_yield":0.051,"roe":0.074,"roa":0.043,"net_margin":0.061,"debt_to_equity":0.29,"current_ratio":1.9,"revenue_growth":0.034}]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/compare":{"get":{"operationId":"compareCompanies","summary":"Compare companies","description":"Returns the same metrics side by side for several companies.\n\nPlan: Starter+. Up to 3 companies on Starter, 10 on Pro and 20 on Business.","tags":["Fundamentals"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/fundamentals/compare-companies"},"x-plan":"starter","parameters":[{"name":"symbols","in":"query","required":true,"description":"Comma-separated Tadawul symbols. Matches any of them.","schema":{"type":"string","description":"Comma-separated list."}},{"name":"metrics","in":"query","required":true,"description":"Comma-separated metric or ratio keys.","schema":{"type":"string","description":"Comma-separated list."}},{"name":"period","in":"query","required":false,"description":"Period basis.","schema":{"type":"string","enum":["annual","quarterly","ttm"],"default":"ttm"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"period_end":{"type":"string","format":"date"},"net_income":{"type":"integer"},"roe":{"type":"number"},"pb_ratio":{"type":"number"}}}}}},"example":{"data":[{"symbol":"1120","period_end":"2026-09-30","net_income":22910000000,"roe":0.214,"pb_ratio":3.9},{"symbol":"1180","period_end":"2026-09-30","net_income":21140000000,"roe":0.128,"pb_ratio":1.3},{"symbol":"1150","period_end":"2026-09-30","net_income":7330000000,"roe":0.162,"pb_ratio":2}]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{symbol}/dividends":{"get":{"operationId":"listDividends","summary":"List dividends","description":"Returns announced and paid cash dividends, with eligibility and payment dates.\n\nPlan: Starter+.","tags":["Fundamentals"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/fundamentals/list-dividends"},"x-plan":"starter","parameters":[{"name":"symbol","in":"path","required":true,"description":"Tadawul symbol, e.g. `2222` for Saudi Aramco. ISINs are accepted too.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Results per page.","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"symbol":{"type":"string"},"trailing_12m_dividends":{"type":"number"},"trailing_12m_yield":{"type":"number"},"upcoming":{"type":"array","items":{}},"history":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string"},"dividend_per_share":{"type":"number"},"total_amount":{"type":"integer"},"announced_on":{"type":"string","format":"date"},"eligibility_date":{"type":"string","format":"date"},"distribution_date":{"type":"string","format":"date"},"announcement_id":{"type":"string"}}}}}}}},"example":{"data":{"symbol":"2222","trailing_12m_dividends":1.26,"trailing_12m_yield":0.0496,"upcoming":[],"history":[{"period":"Q2 2026","dividend_per_share":0.33,"total_amount":79860000000,"announced_on":"2026-08-04","eligibility_date":"2026-08-17","distribution_date":"2026-08-31","announcement_id":"ann_44Rt9w"}]}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{symbol}/corporate-actions":{"get":{"operationId":"listCorporateActions","summary":"List corporate actions","description":"Returns rights issues, bonus shares, capital changes, buybacks and splits.\n\nPlan: Starter+.","tags":["Fundamentals"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/fundamentals/list-corporate-actions"},"x-plan":"starter","parameters":[{"name":"symbol","in":"path","required":true,"description":"Tadawul symbol, e.g. `2222` for Saudi Aramco. ISINs are accepted too.","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"Comma-separated: `rights_issue`, `bonus_shares`, `capital_increase`, `capital_reduction`, `share_buyback`, `stock_split`.","schema":{"type":"string","description":"Comma-separated list."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"stage":{"type":"string"},"ratio":{"type":"string"},"shares_before":{"type":"integer"},"shares_after":{"type":"integer"},"capital_before":{"type":"integer"},"capital_after":{"type":"integer"},"announced_on":{"type":"string","format":"date"},"effective_date":{"type":"string","format":"date"},"announcement_id":{"type":"string"}}}}}},"example":{"data":[{"id":"act_2Lw8Pz","type":"bonus_shares","stage":"completed","ratio":"1 for 10","shares_before":220000000000,"shares_after":242000000000,"capital_before":75000000000,"capital_after":75000000000,"announced_on":"2023-03-12","effective_date":"2023-05-14","announcement_id":"ann_19Kp2c"}]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events":{"get":{"operationId":"listEvents","summary":"List stock events","description":"A single feed of results, dividends, AGMs, capital changes and other material events.\n\nPlan: Pro+.","tags":["Fundamentals"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/fundamentals/list-events"},"x-plan":"pro","parameters":[{"name":"symbols","in":"query","required":false,"description":"Comma-separated Tadawul symbols. Matches any of them.","schema":{"type":"string","description":"Comma-separated list."}},{"name":"types","in":"query","required":false,"description":"Comma-separated, e.g. `financial_results,dividend,general_assembly`.","schema":{"type":"string","description":"Comma-separated list."}},{"name":"from","in":"query","required":false,"description":"Start date, inclusive (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"End date, inclusive (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"updated_after","in":"query","required":false,"description":"Only items created or changed after this time. Use it to sync incrementally.","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","required":false,"description":"Results per page.","schema":{"type":"integer","default":50,"minimum":1,"maximum":500}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Omit it for the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"symbol":{"type":"string"},"type":{"type":"string"},"date":{"type":"string","format":"date"},"title":{"type":"string"},"announcement_id":{"type":"string"},"document_id":{"type":"string"}}}},"pagination":{"type":"object","properties":{"next_cursor":{"type":"string"},"limit":{"type":"integer"}}}}},"example":{"data":[{"id":"evt_7Gq1Ns","symbol":"2222","type":"financial_results","date":"2026-11-03","title":"Q3 2026 interim results","announcement_id":"ann_51Vb3k","document_id":"doc_8Pd2xM"},{"id":"evt_7Gq1Nt","symbol":"2222","type":"dividend","date":"2026-11-03","title":"Q3 2026 cash dividend of SAR 0.33 per share","announcement_id":"ann_51Vb3m","document_id":null}],"pagination":{"next_cursor":"eyJpZCI6MTIwfQ","limit":50}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents":{"get":{"operationId":"listDocuments","summary":"List documents","description":"Lists filings and decks, newest first, filtered by company, type and period.\n\nPlan: Free.","tags":["Documents"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/documents/list-documents"},"x-plan":"free","parameters":[{"name":"symbols","in":"query","required":false,"description":"Comma-separated Tadawul symbols. Matches any of them.","schema":{"type":"string","description":"Comma-separated list."}},{"name":"types","in":"query","required":false,"description":"Comma-separated: `financial_report`, `board_report`, `presentation`, `prospectus`.","schema":{"type":"string","description":"Comma-separated list."}},{"name":"fiscal_year","in":"query","required":false,"description":"Fiscal year covered.","schema":{"type":"integer"}},{"name":"fiscal_period","in":"query","required":false,"description":"Period covered.","schema":{"type":"string","enum":["FY","Q1","Q2","Q3","Q4"]}},{"name":"from","in":"query","required":false,"description":"Start date, inclusive (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"End date, inclusive (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"updated_after","in":"query","required":false,"description":"Only items created or changed after this time. Use it to sync incrementally.","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","required":false,"description":"Results per page.","schema":{"type":"integer","default":50,"minimum":1,"maximum":500}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Omit it for the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"symbol":{"type":"string"},"type":{"type":"string"},"title":{"type":"string"},"language":{"type":"string"},"fiscal_year":{"type":"integer"},"fiscal_period":{"type":"string"},"published_at":{"type":"string","format":"date-time"},"pages":{"type":"integer"},"file_url":{"type":"string"},"source_url":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","properties":{"next_cursor":{"type":"string"},"limit":{"type":"integer"}}}}},"example":{"data":[{"id":"doc_7Hk2pQ","symbol":"1120","type":"financial_report","title":"Annual financial statements 2025","language":"en","fiscal_year":2025,"fiscal_period":"FY","published_at":"2026-02-18T05:31:00Z","pages":96,"file_url":"https://api.q4.sa/v1/documents/doc_7Hk2pQ/file","source_url":"https://www.saudiexchange.sa/…","updated_at":"2026-02-18T06:02:44Z"}],"pagination":{"next_cursor":"eyJpZCI6MTIwfQ","limit":50}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}":{"get":{"operationId":"getDocument","summary":"Retrieve a document","description":"Returns one document’s metadata and a signed link to the PDF.\n\nPlan: Free.","tags":["Documents"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/documents/get-document"},"x-plan":"free","parameters":[{"name":"id","in":"path","required":true,"description":"Document ID, e.g. `doc_7Hk2pQ`.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"symbol":{"type":"string"},"type":{"type":"string"},"title":{"type":"string"},"language":{"type":"string"},"fiscal_year":{"type":"integer"},"fiscal_period":{"type":"string"},"published_at":{"type":"string","format":"date-time"},"pages":{"type":"integer"},"file_url":{"type":"string"},"source_url":{"type":"string"}}}}},"example":{"data":{"id":"doc_7Hk2pQ","symbol":"1120","type":"financial_report","title":"Annual financial statements 2025","language":"en","fiscal_year":2025,"fiscal_period":"FY","published_at":"2026-02-18T05:31:00Z","pages":96,"file_url":"https://files.q4.sa/d/doc_7Hk2pQ.pdf?sig=…&exp=1762268400","source_url":"https://www.saudiexchange.sa/…"}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/pages":{"get":{"operationId":"listDocumentPages","summary":"List document pages","description":"Returns the extracted text of each page, with detected tables.\n\nPlan: Starter+.","tags":["Documents"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/documents/list-document-pages"},"x-plan":"starter","parameters":[{"name":"id","in":"path","required":true,"description":"Document ID, e.g. `doc_7Hk2pQ`.","schema":{"type":"string"}},{"name":"pages","in":"query","required":false,"description":"Page numbers or ranges, e.g. `1-5,14`.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Results per page.","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Omit it for the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"page":{"type":"integer"},"text":{"type":"string"},"tables":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"rows":{"type":"integer"},"columns":{"type":"integer"}}}}}}},"pagination":{"type":"object","properties":{"next_cursor":{"type":["string","null"]},"limit":{"type":"integer"}}}}},"example":{"data":[{"page":14,"text":"CONSOLIDATED STATEMENT OF INCOME\nFor the year ended 31 December 2025\n(SAR’000)…","tables":[{"title":"Consolidated statement of income","rows":28,"columns":3}]}],"pagination":{"next_cursor":null,"limit":50}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/text":{"get":{"operationId":"getDocumentText","summary":"Retrieve document text","description":"Returns the whole document as plain text or Markdown, with page markers.\n\nPlan: Starter+.","tags":["Documents"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/documents/get-document-text"},"x-plan":"starter","parameters":[{"name":"id","in":"path","required":true,"description":"Document ID, e.g. `doc_7Hk2pQ`.","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"Output format.","schema":{"type":"string","enum":["markdown","plain"],"default":"markdown"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"format":{"type":"string"},"text":{"type":"string"},"characters":{"type":"integer"}}}}},"example":{"data":{"id":"doc_7Hk2pQ","format":"markdown","text":"<!-- page 1 -->\n# Al Rajhi Bank\n## Annual financial statements 2025\n…","characters":412880}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/summary":{"get":{"operationId":"getDocumentSummary","summary":"Retrieve document summary","description":"Returns an AI summary of the document, each point cited to its page.\n\nPlan: Starter+.","tags":["Documents"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/documents/get-document-summary"},"x-plan":"starter","parameters":[{"name":"id","in":"path","required":true,"description":"Document ID, e.g. `doc_7Hk2pQ`.","schema":{"type":"string"}},{"name":"length","in":"query","required":false,"description":"One line, a paragraph, or a full brief.","schema":{"type":"string","enum":["line","short","long"],"default":"short"}},{"name":"language","in":"query","required":false,"description":"Summary language.","schema":{"type":"string","enum":["en","ar"],"default":"en"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"length":{"type":"string"},"language":{"type":"string"},"summary":{"type":"string"},"citations":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"page":{"type":"integer"}}}},"generated_at":{"type":"string","format":"date-time"}}}}},"example":{"data":{"id":"doc_7Hk2pQ","length":"short","language":"en","summary":"Net income rose 18% to SAR 21.8bn on higher financing income…","citations":[{"text":"Net income rose 18% to SAR 21.8bn","page":14}],"generated_at":"2026-02-18T06:10:02Z"}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/notes":{"get":{"operationId":"listDocumentNotes","summary":"List notes","description":"Lists the notes to the financial statements in a financial report, in order, with their pages.\n\nUse it as the table of contents of a report’s notes. Each note links to its full text with [Retrieve a note](/docs/api-reference/documents/get-document-note), and to its figures with [List figures](/docs/api-reference/fundamentals/list-facts) (`statement=note&document_id=…`).\n\nPlan: Starter+.","tags":["Documents"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/documents/list-document-notes"},"x-plan":"starter","parameters":[{"name":"id","in":"path","required":true,"description":"Document ID, e.g. `doc_7Hk2pQ`.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string"},"title":{"type":"string"},"pages":{"type":"array","items":{"type":"integer"}},"tables":{"type":"integer"},"figures":{"type":"integer"}}}}}},"example":{"data":[{"number":"2","title":"BASIS OF PREPARATION","pages":[18,19],"tables":0,"figures":0},{"number":"3","title":"MATERIAL ACCOUNTING POLICIES","pages":[19,31],"tables":1,"figures":12},{"number":"27","title":"SEGMENT INFORMATION","pages":[70,72],"tables":2,"figures":96}]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/notes/{number}":{"get":{"operationId":"getDocumentNote","summary":"Retrieve a note","description":"Returns one note’s full text, its tables, and the figures in them.\n\nThe text is the note as printed, split into paragraphs with the page each comes from, so you can quote an accounting policy or a contingency and cite it. Tables come back as rows of labels and the figure IDs in each cell.\n\nPlan: Starter+.","tags":["Documents"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/documents/get-document-note"},"x-plan":"starter","parameters":[{"name":"id","in":"path","required":true,"description":"Document ID, e.g. `doc_7Hk2pQ`.","schema":{"type":"string"}},{"name":"number","in":"path","required":true,"description":"Note number as printed, e.g. `27`.","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"Paragraphs with pages, one Markdown block, or plain text.","schema":{"type":"string","enum":["paragraphs","markdown","plain"],"default":"paragraphs"}},{"name":"include_tables","in":"query","required":false,"description":"Include the note’s tables.","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"document_id":{"type":"string"},"number":{"type":"string"},"title":{"type":"string"},"pages":{"type":"array","items":{"type":"integer"}},"paragraphs":{"type":"array","items":{"type":"object","properties":{"page":{"type":"integer"},"text":{"type":"string"}}}},"tables":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"page":{"type":"integer"},"columns":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"fact_ids":{"type":"array","items":{"type":"string"}}}}}}}}}}}},"example":{"data":{"document_id":"doc_7Hk2pQ","number":"27","title":"SEGMENT INFORMATION","pages":[70,72],"paragraphs":[{"page":70,"text":"Operating segments are identified on the basis of internal reports about components of the Group that are regularly reviewed by the Board of Directors…"},{"page":70,"text":"The Group’s primary business is conducted in the Kingdom of Saudi Arabia. The Group has four reportable segments: Retail, Corporate, Treasury and Investment services and brokerage…"}],"tables":[{"title":"Segment information for the year ended 31 December 2025","page":71,"columns":["Retail","Corporate","Treasury","Investment services","Total"],"rows":[{"label":"Net income for the year","fact_ids":["fct_4Rb8Tn","fct_4Rb8Tp","fct_4Rb8Tq","fct_4Rb8Tr","fct_4Rb8Ts"]}]}]}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{symbol}/notes":{"get":{"operationId":"searchNotes","summary":"Search notes","description":"Finds notes across all of a company’s financial reports by title or text, e.g. every segment note since 2020.\n\nPlan: Starter+.","tags":["Fundamentals"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/fundamentals/search-notes"},"x-plan":"starter","parameters":[{"name":"symbol","in":"path","required":true,"description":"Tadawul symbol, e.g. `2222` for Saudi Aramco. ISINs are accepted too.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Words in the note title or text, e.g. `zakat`, `related parties`, `expected credit loss`.","schema":{"type":"string"}},{"name":"fiscal_year","in":"query","required":false,"description":"Only notes in reports for this fiscal year.","schema":{"type":"integer"}},{"name":"fiscal_period","in":"query","required":false,"description":"Only notes in reports for this period.","schema":{"type":"string","enum":["FY","Q1","Q2","Q3","Q4"]}},{"name":"limit","in":"query","required":false,"description":"Results per page.","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Omit it for the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"document_id":{"type":"string"},"fiscal_year":{"type":"integer"},"fiscal_period":{"type":"string"},"number":{"type":"string"},"title":{"type":"string"},"pages":{"type":"array","items":{"type":"integer"}},"snippet":{"type":"string"}}}},"pagination":{"type":"object","properties":{"next_cursor":{"type":"string"},"limit":{"type":"integer"}}}}},"example":{"data":[{"document_id":"doc_7Hk2pQ","fiscal_year":2025,"fiscal_period":"FY","number":"30","title":"ZAKAT","pages":[76,77],"snippet":"…the Bank has filed its Zakat returns with the Zakat, Tax and Customs Authority up to the year ended 31 December 2024…"}],"pagination":{"next_cursor":"eyJpZCI6MTIwfQ","limit":50}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/sections":{"get":{"operationId":"listDocumentSections","summary":"List sections","description":"Lists the chapters of a board report, in order, each tagged with a standard category.\n\nBoard reports follow the Capital Market Authority’s disclosure rules, so they cover the same ground every year, in each company’s own words and order. Every chapter is tagged with a [standard category](/docs/datasets/board-reports#categories), so `remuneration` is the directors’ pay chapter whatever the company called it.\n\nRead a chapter in full with [Retrieve a section](/docs/api-reference/documents/get-document-section).\n\nPlan: Starter+.","tags":["Documents"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/documents/list-document-sections"},"x-plan":"starter","parameters":[{"name":"id","in":"path","required":true,"description":"ID of a board report (`type=board_report`).","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"Only these categories, comma-separated, e.g. `remuneration,related_parties`.","schema":{"type":"string","description":"Comma-separated list."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"pages":{"type":"array","items":{"type":"integer"}},"tables":{"type":"integer"},"figures":{"type":"integer"}}}}}},"example":{"data":[{"id":"sec_01","title":"Overview of the Bank’s activities","category":"business_overview","pages":[4,9],"tables":1,"figures":14},{"id":"sec_06","title":"Board of Directors and its committees","category":"board_composition","pages":[22,31],"tables":4,"figures":38},{"id":"sec_09","title":"Remuneration of Board members and Senior Executives","category":"remuneration","pages":[36,39],"tables":3,"figures":62},{"id":"sec_12","title":"Transactions with related parties","category":"related_parties","pages":[44,46],"tables":1,"figures":21}]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/sections/{section_id}":{"get":{"operationId":"getDocumentSection","summary":"Retrieve a section","description":"Returns one board report chapter in full: its text paragraph by paragraph with pages, and its tables with the figures in them.\n\nPlan: Starter+.","tags":["Documents"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/documents/get-document-section"},"x-plan":"starter","parameters":[{"name":"id","in":"path","required":true,"description":"Document ID, e.g. `doc_7Hk2pQ`.","schema":{"type":"string"}},{"name":"section_id","in":"path","required":true,"description":"Section ID from List sections, e.g. `sec_09`.","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"Paragraphs with pages, one Markdown block, or plain text.","schema":{"type":"string","enum":["paragraphs","markdown","plain"],"default":"paragraphs"}},{"name":"include_tables","in":"query","required":false,"description":"Include the chapter’s tables.","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"document_id":{"type":"string"},"id":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"pages":{"type":"array","items":{"type":"integer"}},"paragraphs":{"type":"array","items":{"type":"object","properties":{"page":{"type":"integer"},"text":{"type":"string"}}}},"tables":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"page":{"type":"integer"},"columns":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"fact_ids":{"type":"array","items":{"type":"string"}}}}}}}}}}}},"example":{"data":{"document_id":"doc_5Bn3Wd","id":"sec_09","title":"Remuneration of Board members and Senior Executives","category":"remuneration","pages":[36,39],"paragraphs":[{"page":36,"text":"The Remuneration Policy for Board members, Committee members and Senior Executives was approved by the General Assembly…"},{"page":37,"text":"The table below shows the remuneration paid to Board members for the year ended 31 December 2025…"}],"tables":[{"title":"Remuneration of Board members (SAR)","page":37,"columns":["Fixed remuneration","Attendance allowance","Variable remuneration","Total"],"rows":[{"label":"Independent members","fact_ids":["fct_6Hp2Ra","fct_6Hp2Rb","fct_6Hp2Rc","fct_6Hp2Rd"]}]}]}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{symbol}/sections":{"get":{"operationId":"searchSections","summary":"Search board report sections","description":"Returns the same board report chapter across years, e.g. directors’ remuneration since 2020.\n\nPlan: Starter+.","tags":["Documents"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/documents/search-sections"},"x-plan":"starter","parameters":[{"name":"symbol","in":"path","required":true,"description":"Tadawul symbol, e.g. `2222` for Saudi Aramco. ISINs are accepted too.","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"Comma-separated standard categories, e.g. `remuneration`.","schema":{"type":"string","description":"Comma-separated list."}},{"name":"q","in":"query","required":false,"description":"Words in the chapter title or text, e.g. `penalties` or `audit committee`.","schema":{"type":"string"}},{"name":"from_year","in":"query","required":false,"description":"First fiscal year.","schema":{"type":"integer"}},{"name":"to_year","in":"query","required":false,"description":"Last fiscal year.","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Results per page.","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Omit it for the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"document_id":{"type":"string"},"fiscal_year":{"type":"integer"},"id":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"pages":{"type":"array","items":{"type":"integer"}},"snippet":{"type":"string"}}}},"pagination":{"type":"object","properties":{"next_cursor":{"type":"string"},"limit":{"type":"integer"}}}}},"example":{"data":[{"document_id":"doc_5Bn3Wd","fiscal_year":2025,"id":"sec_09","title":"Remuneration of Board members and Senior Executives","category":"remuneration","pages":[36,39],"snippet":"The table below shows the remuneration paid to Board members…"},{"document_id":"doc_2Kc7Vy","fiscal_year":2024,"id":"sec_08","title":"Remuneration of Board members and Senior Executives","category":"remuneration","pages":[34,37],"snippet":"The table below shows the remuneration paid to Board members…"}],"pagination":{"next_cursor":"eyJpZCI6MTIwfQ","limit":50}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/earnings-calls":{"get":{"operationId":"listEarningsCalls","summary":"List earnings calls","description":"Lists recorded earnings calls, newest first.\n\nPlan: Pro+.","tags":["Earnings calls"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/earnings-calls/list-earnings-calls"},"x-plan":"pro","parameters":[{"name":"symbols","in":"query","required":false,"description":"Comma-separated Tadawul symbols. Matches any of them.","schema":{"type":"string","description":"Comma-separated list."}},{"name":"fiscal_year","in":"query","required":false,"description":"Fiscal year discussed.","schema":{"type":"integer"}},{"name":"from","in":"query","required":false,"description":"Start date, inclusive (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"End date, inclusive (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"updated_after","in":"query","required":false,"description":"Only items created or changed after this time. Use it to sync incrementally.","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","required":false,"description":"Results per page.","schema":{"type":"integer","default":50,"minimum":1,"maximum":500}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Omit it for the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"symbol":{"type":"string"},"title":{"type":"string"},"fiscal_year":{"type":"integer"},"fiscal_period":{"type":"string"},"held_at":{"type":"string","format":"date-time"},"language":{"type":"string"},"duration_seconds":{"type":"integer"},"has_transcript":{"type":"boolean"},"presentation_id":{"type":"string"}}}},"pagination":{"type":"object","properties":{"next_cursor":{"type":"string"},"limit":{"type":"integer"}}}}},"example":{"data":[{"id":"call_3Fn8xR","symbol":"2222","title":"Q3 2026 earnings call","fiscal_year":2026,"fiscal_period":"Q3","held_at":"2026-11-04T12:30:00Z","language":"en","duration_seconds":3412,"has_transcript":true,"presentation_id":"doc_8Pd2xN"}],"pagination":{"next_cursor":"eyJpZCI6MTIwfQ","limit":50}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/earnings-calls/{id}":{"get":{"operationId":"getEarningsCall","summary":"Retrieve an earnings call","description":"Returns one call’s details, speakers and linked presentation.\n\nPlan: Pro+.","tags":["Earnings calls"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/earnings-calls/get-earnings-call"},"x-plan":"pro","parameters":[{"name":"id","in":"path","required":true,"description":"Earnings call ID, e.g. `call_3Fn8xR`.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"symbol":{"type":"string"},"title":{"type":"string"},"fiscal_year":{"type":"integer"},"fiscal_period":{"type":"string"},"held_at":{"type":"string","format":"date-time"},"language":{"type":"string"},"duration_seconds":{"type":"integer"},"speakers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"}}}},"presentation_id":{"type":"string"}}}}},"example":{"data":{"id":"call_3Fn8xR","symbol":"2222","title":"Q3 2026 earnings call","fiscal_year":2026,"fiscal_period":"Q3","held_at":"2026-11-04T12:30:00Z","language":"en","duration_seconds":3412,"speakers":[{"id":"spk_1","name":"Chief Financial Officer","role":"management"},{"id":"spk_2","name":"Analyst","role":"analyst"}],"presentation_id":"doc_8Pd2xN"}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/earnings-calls/{id}/transcript":{"get":{"operationId":"getTranscript","summary":"Retrieve a transcript","description":"Returns the transcript by speaker turn, with start and end times, or word by word.\n\nPlan: Pro+.","tags":["Earnings calls"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/earnings-calls/get-transcript"},"x-plan":"pro","parameters":[{"name":"id","in":"path","required":true,"description":"Earnings call ID, e.g. `call_3Fn8xR`.","schema":{"type":"string"}},{"name":"granularity","in":"query","required":false,"description":"Speaker turns, word-level timings, or one block of text.","schema":{"type":"string","enum":["segments","words","text"],"default":"segments"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"language":{"type":"string"},"segments":{"type":"array","items":{"type":"object","properties":{"speaker_id":{"type":"string"},"start":{"type":"number"},"end":{"type":"number"},"section":{"type":"string"},"text":{"type":"string"}}}}}}}},"example":{"data":{"id":"call_3Fn8xR","language":"en","segments":[{"speaker_id":"spk_1","start":62.4,"end":91.8,"section":"prepared_remarks","text":"Net income for the quarter was…"},{"speaker_id":"spk_2","start":1904.2,"end":1921,"section":"qa","text":"Could you give more colour on…"}]}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/earnings-calls/{id}/audio":{"get":{"operationId":"getAudio","summary":"Retrieve call audio","description":"Returns a signed link to the call recording.\n\nPlan: Pro+.","tags":["Earnings calls"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/earnings-calls/get-audio"},"x-plan":"pro","parameters":[{"name":"id","in":"path","required":true,"description":"Earnings call ID, e.g. `call_3Fn8xR`.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"audio_url":{"type":"string"},"mime_type":{"type":"string"},"duration_seconds":{"type":"integer"},"expires_at":{"type":"string","format":"date-time"}}}}},"example":{"data":{"id":"call_3Fn8xR","audio_url":"https://files.q4.sa/a/call_3Fn8xR.m4a?sig=…&exp=1762268400","mime_type":"audio/mp4","duration_seconds":3412,"expires_at":"2026-11-04T15:00:00Z"}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/announcements":{"get":{"operationId":"listAnnouncements","summary":"List announcements","description":"Lists issuer announcements published on Tadawul, newest first.\n\nPlan: Starter+.","tags":["Announcements"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/announcements/list-announcements"},"x-plan":"starter","parameters":[{"name":"symbols","in":"query","required":false,"description":"Comma-separated Tadawul symbols. Matches any of them.","schema":{"type":"string","description":"Comma-separated list."}},{"name":"q","in":"query","required":false,"description":"Full-text search in the title and body.","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"Announcement language.","schema":{"type":"string","enum":["en","ar"],"default":"en"}},{"name":"from","in":"query","required":false,"description":"Start date, inclusive (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"End date, inclusive (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"updated_after","in":"query","required":false,"description":"Only items created or changed after this time. Use it to sync incrementally.","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","required":false,"description":"Results per page.","schema":{"type":"integer","default":50,"minimum":1,"maximum":500}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Omit it for the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"symbol":{"type":"string"},"title":{"type":"string"},"published_at":{"type":"string","format":"date-time"},"language":{"type":"string"},"summary":{"type":"string"},"source_url":{"type":"string"}}}},"pagination":{"type":"object","properties":{"next_cursor":{"type":"string"},"limit":{"type":"integer"}}}}},"example":{"data":[{"id":"ann_51Vb3k","symbol":"2222","title":"Saudi Aramco announces its interim financial results for the period ending 30 September 2026","published_at":"2026-11-03T04:02:00Z","language":"en","summary":"Net income of SAR 101.6bn for the quarter…","source_url":"https://www.saudiexchange.sa/…"}],"pagination":{"next_cursor":"eyJpZCI6MTIwfQ","limit":50}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/announcements/{id}":{"get":{"operationId":"getAnnouncement","summary":"Retrieve an announcement","description":"Returns one announcement with its full text and HTML.\n\nPlan: Starter+.","tags":["Announcements"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/announcements/get-announcement"},"x-plan":"starter","parameters":[{"name":"id","in":"path","required":true,"description":"Announcement ID, e.g. `ann_51Vb3k`.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"symbol":{"type":"string"},"title":{"type":"string"},"published_at":{"type":"string","format":"date-time"},"language":{"type":"string"},"content_text":{"type":"string"},"content_html":{"type":"string"},"source_url":{"type":"string"}}}}},"example":{"data":{"id":"ann_51Vb3k","symbol":"2222","title":"Saudi Aramco announces its interim financial results for the period ending 30 September 2026","published_at":"2026-11-03T04:02:00Z","language":"en","content_text":"Element List | Current Quarter | Similar Quarter for previous year…","content_html":"<table>…</table>","source_url":"https://www.saudiexchange.sa/…"}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/economic/series":{"get":{"operationId":"listSeries","summary":"List series","description":"Lists the government statistics series we publish, by source and topic.\n\nPlan: Business+.","tags":["Economic data"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/economic/list-series"},"x-plan":"business","parameters":[{"name":"source","in":"query","required":false,"description":"Publishing body.","schema":{"type":"string","enum":["gastat","sama","tadawul"]}},{"name":"q","in":"query","required":false,"description":"Search series titles in English or Arabic.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Results per page.","schema":{"type":"integer","default":100,"minimum":1,"maximum":500}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Omit it for the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"title_en":{"type":"string"},"title_ar":{"type":"string"},"source":{"type":"string"},"frequency":{"type":"string"},"unit":{"type":"string"},"first_period":{"type":"string"},"last_period":{"type":"string"},"dimensions":{"type":"array","items":{"type":"string"}}}}},"pagination":{"type":"object","properties":{"next_cursor":{"type":"string"},"limit":{"type":"integer"}}}}},"example":{"data":[{"key":"gastat.cpi.headline","title_en":"Consumer price index, headline","title_ar":"الرقم القياسي لأسعار المستهلك","source":"gastat","frequency":"monthly","unit":"index (2023=100)","first_period":"2013-01","last_period":"2026-09","dimensions":["region"]}],"pagination":{"next_cursor":"eyJpZCI6MTIwfQ","limit":50}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/economic/series/{key}/observations":{"get":{"operationId":"listObservations","summary":"List observations","description":"Returns a series’ values over time, optionally split by its dimensions.\n\nPlan: Business+.","tags":["Economic data"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/economic/list-observations"},"x-plan":"business","parameters":[{"name":"key","in":"path","required":true,"description":"Series key from [List series](/docs/api-reference/economic/list-series).","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Start date, inclusive (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"End date, inclusive (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"dimensions","in":"query","required":false,"description":"Filter by dimension, e.g. `region:riyadh`.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Results per page.","schema":{"type":"integer","default":500,"minimum":1,"maximum":5000}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Omit it for the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string"},"period_end":{"type":"string","format":"date"},"value":{"type":"number"},"dimensions":{"type":"object","properties":{"region":{"type":"string"}}}}}},"pagination":{"type":"object","properties":{"next_cursor":{"type":"string"},"limit":{"type":"integer"}}}}},"example":{"data":[{"period":"2026-09","period_end":"2026-09-30","value":106.42,"dimensions":{"region":"national"}},{"period":"2026-08","period_end":"2026-08-31","value":106.18,"dimensions":{"region":"national"}}],"pagination":{"next_cursor":"eyJpZCI6MTIwfQ","limit":50}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"post":{"operationId":"createWebhook","summary":"Create a webhook","description":"Registers an HTTPS endpoint to receive events.\n\nThe response includes the `signing_secret` once. Store it: you need it to [verify signatures](/docs/webhooks/signatures).\n\nPlan: Pro+.","tags":["Webhooks & alerts"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/webhooks/create-webhook"},"x-plan":"pro","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"symbols":{"type":"array","items":{"type":"string"}},"status":{"type":"string"},"signing_secret":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}}},"example":{"data":{"id":"whk_5Ty7Ua","url":"https://example.com/q4/webhooks","events":["announcement.created","document.created"],"symbols":["2222","1120"],"status":"active","signing_secret":"whsec_Zp4c…","created_at":"2026-11-04T09:00:00Z"}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","description":"HTTPS URL that accepts POST requests."},"events":{"type":"array","items":{"type":"string"},"description":"Event types to send. See [Events](/docs/webhooks/events)."},"symbols":{"type":"array","items":{"type":"string"},"description":"Only events for these symbols. Omit for all."},"description":{"type":"string","description":"A note for yourself."}}},"example":{"url":"https://example.com/q4/webhooks","events":["announcement.created","document.created"],"symbols":["2222","1120"]}}}}},"get":{"operationId":"listWebhooks","summary":"List webhooks","description":"Lists your webhook endpoints and their delivery health.\n\nPlan: Pro+.","tags":["Webhooks & alerts"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/webhooks/list-webhooks"},"x-plan":"pro","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"status":{"type":"string"},"last_delivery_at":{"type":"string","format":"date-time"},"failures_24h":{"type":"integer"}}}}}},"example":{"data":[{"id":"whk_5Ty7Ua","url":"https://example.com/q4/webhooks","events":["announcement.created","document.created"],"status":"active","last_delivery_at":"2026-11-04T08:59:12Z","failures_24h":0}]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}":{"delete":{"operationId":"deleteWebhook","summary":"Delete a webhook","description":"Stops deliveries to an endpoint and deletes it.\n\nPlan: Pro+.","tags":["Webhooks & alerts"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/webhooks/delete-webhook"},"x-plan":"pro","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}}}},"example":{"data":{"id":"whk_5Ty7Ua","deleted":true}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/alerts":{"post":{"operationId":"createAlert","summary":"Create an alert rule","description":"Sends an `alert.triggered` webhook when a price or volume condition is met.\n\nPlan: Pro+.","tags":["Webhooks & alerts"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/webhooks/create-alert"},"x-plan":"pro","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"symbol":{"type":"string"},"type":{"type":"string"},"value":{"type":"integer"},"once":{"type":"boolean"},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}}},"example":{"data":{"id":"alr_8Wd3Qe","symbol":"2222","type":"price_above","value":27,"once":true,"status":"active","created_at":"2026-11-04T09:01:00Z"}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["symbol","type","value"],"properties":{"symbol":{"type":"string","description":"Tadawul symbol."},"type":{"type":"string","enum":["price_above","price_below","change_percent","abnormal_volume","unusual_value"],"description":"Condition to watch."},"value":{"type":"number","description":"Threshold: a price in SAR, a percent, or a multiple of the 20-day average."},"once":{"type":"boolean","default":true,"description":"Disable the rule after it fires once."}}},"example":{"symbol":"2222","type":"price_above","value":27,"once":true}}}}},"get":{"operationId":"listAlerts","summary":"List alert rules","description":"Lists your alert rules and when they last fired.\n\nPlan: Pro+.","tags":["Webhooks & alerts"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/webhooks/list-alerts"},"x-plan":"pro","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"symbol":{"type":"string"},"type":{"type":"string"},"value":{"type":"integer"},"once":{"type":"boolean"},"status":{"type":"string"},"last_triggered_at":{"type":["string","null"]}}}}}},"example":{"data":[{"id":"alr_8Wd3Qe","symbol":"2222","type":"price_above","value":27,"once":true,"status":"active","last_triggered_at":null}]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/alerts/{id}":{"delete":{"operationId":"deleteAlert","summary":"Delete an alert rule","description":"Deletes an alert rule.\n\nPlan: Pro+.","tags":["Webhooks & alerts"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/webhooks/delete-alert"},"x-plan":"pro","parameters":[{"name":"id","in":"path","required":true,"description":"Alert rule ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}}}},"example":{"data":{"id":"alr_8Wd3Qe","deleted":true}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/usage":{"get":{"operationId":"getUsage","summary":"Retrieve usage","description":"Returns your plan, today’s request count and when the quota resets. Does not count towards it.\n\nPlan: Free.","tags":["Account"],"externalDocs":{"url":"https://q4.sa/docs/api-reference/account/get-usage"},"x-plan":"free","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"plan":{"type":"string"},"requests_today":{"type":"integer"},"requests_per_day":{"type":"integer"},"requests_per_minute":{"type":"integer"},"resets_at":{"type":"string","format":"date-time"},"keys":{"type":"integer"}}}}},"example":{"data":{"plan":"starter","requests_today":1284,"requests_per_day":5000,"requests_per_minute":100,"resets_at":"2026-11-04T21:00:00Z","keys":2}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_PARAM","AUTH_REQUIRED","INVALID_API_KEY","PLAN_LIMIT","NOT_FOUND","INVALID_SYMBOL","AMBIGUOUS_IDENTIFIER","RATE_LIMITED","SERVER_ERROR","UNAVAILABLE"]},"message":{"type":"string"},"param":{"type":"string"}}}}}}}}