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
Companies

List companies

GEThttps://api.q4.sa/v1/companies
Lists listed companies, filtered by name, sector or market.
Free

Authorization

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

Query parameters

searchstring
Matches English and Arabic names and common aliases (e.g. "aramco", "الراجحي").
symbolsstring (comma-separated)
Comma-separated Tadawul symbols. Matches any of them.
sectorstring
Sector slug from List sectors, e.g. banks.
marketstring
Main market or Nomu.
One of:mainnomu
statusstring
Listing status.
One of:activesuspendeddelisted
Default: active
limitinteger
Results per page.
Default: 100 · Range: 1–500
cursorstring
The next_cursor from the previous page. Omit it for the first page.

Response

dataobject[]
The result.
symbolstring
Tadawul symbol.
isinstring
International Securities Identification Number.
name_enstring
Name in English.
name_arstring
Name in Arabic.
marketstring
main (TASI) or nomu.
sectorstring
Sector slug.
statusstring
Current status.
is_etfboolean
Whether the security is an exchange-traded fund.
paginationobject
Paging details. See Pagination.
next_cursorstring
Pass as cursor to get the next page. null on the last page.
limitinteger
Page size used.

Errors

400, 401, 403, 404, 429. Every error has the same shape: see Errors.
← Previous
API reference
Next →
Retrieve a company
Request
curl "https://api.q4.sa/v1/companies?search=bank&market=main" \
  -H "x-api-key: $Q4_API_KEY"
Response
{
  "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
  }
}