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

List figures

GEThttps://api.q4.sa/v1/companies/{symbol}/facts
Returns every number printed in a company’s filings, including the notes to the financial statements, with the page and position it came from.
Starter+

This 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.

It 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.

When a later filing restates a figure, the old value stays in restatements.

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

statementstring (comma-separated)
Comma-separated: income, balance, cash_flow, comprehensive_income, changes_in_equity, note, other. Use note for tables in the notes to the financial statements.
notestring
Only figures under notes whose title matches, e.g. segment or 27.
qstring
Search row labels and headings, e.g. stage 3 or related parties.
metricstring
Standard metric key, e.g. net_income. Unmapped rows, including most note rows, have none.
fiscal_yearinteger
Fiscal year of the period the figure describes.
fiscal_periodstring
Period the figure describes.
One of:FYQ1Q2Q3Q4H19M
document_idstring
Only figures from this document. With no other filter, returns every line item in the filing, statements and notes.
include_unverifiedboolean
Include figures we could not read with confidence. They come back with verified: false.
Default: false
updated_afterdatetime
Only items created or changed after this time. Use it to sync incrementally.
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.
idstring
Unique ID.
metricnull
Standard metric key, the same across companies.
statementstring
Where the table sits: a primary statement, or note for the notes to the financial statements.
note_titlestring
The numbered note the table sits under, as printed. null for the primary statements.
section_labelstring
The sub-section of the table the row belongs to, e.g. a segment or a stage.
header_pathstring[]
The headings printed above the table, outermost first.
row_labelstring
The row label as printed.
column_labelstring
The column header as printed.
fiscal_yearinteger
Fiscal year.
fiscal_periodstring
Fiscal period: FY, Q1–Q4, H1 or 9M.
period_startdate
First day of the period.
period_enddate
Last day of the period.
printed_valuestring
The figure exactly as printed in the filing.
valueinteger
The parsed value in base units (scale applied).
unitstring
scalestring
The scale printed on the table, e.g. thousands or millions.
document_idstring
Document the item came from.
pageinteger
PDF page number (1-based).
bboxnumber[]
Position on the page as [x0, y0, x1, y1] in PDF points.
verifiedboolean
False if we could not read the value with confidence. Only returned with include_unverified=true.
restatementsarray
Earlier values for the same figure, if a later filing changed it.
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
Retrieve as-reported statements
Next →
Retrieve ratios
Request
curl "https://api.q4.sa/v1/companies/1120/facts?statement=note&note=segment&fiscal_year=2025" \
  -H "x-api-key: $Q4_API_KEY"
Response
{
  "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
  }
}