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
Market data

List market movers

GEThttps://api.q4.sa/v1/market/movers
Returns the top gainers, losers, or most traded stocks by volume or value.
Free

Authorization

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

Query parameters

typestringrequired
How to rank stocks.
One of:gainerslosersvolumevalue
indexstring
Market: the main market (TASI) or the parallel market (Nomu).
One of:TASINOMU
Default: TASI
limitinteger
Results per page.
Default: 10 · Range: 1–50

Response

dataobject[]
The result.
symbolstring
Tadawul symbol.
name_enstring
Name in English.
pricenumber
Last traded price, SAR.
change_percentnumber
Change from the previous close, percent.
volumeinteger
Shares traded.
turnoverinteger
Value traded, SAR.

Errors

400, 401, 403, 404, 429. Every error has the same shape: see Errors.
← Previous
Retrieve market summary
Next →
List sector performance
Request
curl "https://api.q4.sa/v1/market/movers?type=gainers&limit=3" \
  -H "x-api-key: $Q4_API_KEY"
Response
{
  "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
    }
  ]
}