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

Retrieve order book depth

GEThttps://api.q4.sa/v1/market/depth/{symbol}
Returns the best bids and asks for a stock, up to 20 levels deep.
Business+

Authorization

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

Path parameters

symbolstringrequired
Tadawul symbol, e.g. 2222 for Saudi Aramco. ISINs are accepted too.

Query parameters

levelsinteger
Price levels per side.
Default: 10 · Range: 1–20

Response

dataobject
The result.
symbolstring
Tadawul symbol.
best_bidnumber
best_asknumber
spreadnumber
spread_bpsnumber
bidsobject[]
levelinteger
pricenumber
Last traded price, SAR.
quantityinteger
ordersinteger
asksobject[]
levelinteger
pricenumber
Last traded price, SAR.
quantityinteger
ordersinteger
updated_atdatetime
When this record last changed.

Errors

400, 401, 403, 404, 429. Every error has the same shape: see Errors.
← Previous
List trades
Next →
Quotes stream
Request
curl "https://api.q4.sa/v1/market/depth/2222?levels=2" \
  -H "x-api-key: $Q4_API_KEY"
Response
{
  "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"
  }
}