Q4API Docs
Q4 APISign inGet API key
DocumentationAPI Reference
Overview
API reference
Companies
GETList companiesGETRetrieve a companyGETList sectors
Market data
GETRetrieve a quoteGETList quotesGETRetrieve price historyGETRetrieve index historyGETRetrieve market summaryGETList market moversGETList sector performanceGETList tradesGETRetrieve order book depth
WebSocket
WSQuotes streamWSTrades streamWSDepth stream
Fundamentals
GETRetrieve standardised statementsGETRetrieve as-reported statementsGETList figuresGETRetrieve ratiosGETCompare companiesGETList dividendsGETList corporate actionsGETList stock eventsGETSearch notes
Documents
GETList documentsGETRetrieve a documentGETList document pagesGETRetrieve document textGETRetrieve document summaryGETList notesGETRetrieve a noteGETList sectionsGETRetrieve a sectionGETSearch board report sections
Earnings calls
GETList earnings callsGETRetrieve an earnings callGETRetrieve a transcriptGETRetrieve call audio
Announcements
GETList announcementsGETRetrieve an announcement
Economic data
GETList seriesGETList observations
Webhooks & alerts
POSTCreate a webhookGETList webhooksDELDelete a webhookPOSTCreate an alert ruleGETList alert rulesDELDelete an alert rule
Account
GETRetrieve usage
Fundamentals

Compare companies

GEThttps://api.q4.sa/v1/compare
Returns the same metrics side by side for several companies.
Starter+Up to 3 companies on Starter, 10 on Pro and 20 on Business.

Authorization

x-api-keyheaderrequired
Your API key. See Authentication.

Query parameters

symbolsstring (comma-separated)required
Comma-separated Tadawul symbols. Matches any of them.
metricsstring (comma-separated)required
Comma-separated metric or ratio keys.
periodstring
Period basis.
One of:annualquarterlyttm
Default: ttm

Response

dataobject[]
The result.
symbolstring
Tadawul symbol.
period_enddate
Last day of the period.
net_incomeinteger
roenumber
pb_rationumber
Price to book value.

Errors

400, 401, 403, 404, 429. Every error has the same shape: see Errors.
← Previous
Retrieve ratios
Next →
List dividends
Request
curl "https://api.q4.sa/v1/compare?symbols=1120,1180,1150&metrics=net_income,roe,pb_ratio" \
  -H "x-api-key: $Q4_API_KEY"
Response
{
  "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
    }
  ]
}