ASHUMGulf news and Dubai stocks, live

Ashum API

The headlines from 42 Gulf news outlets as JSON: newest first, sorted into sections, searchable, and grouped when several outlets carry the same story. Ashum checks every outlet every 10 minutes. The API also carries the companies of Dubai Financial Market (DFM): their prices, their disclosures with the text of the documents filed since November 2024, and the exchange’s calendar.

Endpoints

$0.005 a request, which is $5 for 1,000, paid as you go with no subscription. A new account starts with 200 free requests. API pricing

EndpointWhat it returnsA call costs
GET /api/v1/storiesStories, newest first.1 request for every 25 stories
GET /api/v1/stories/{id}A single story, with the same story in other outlets and related coverage from the days around it.1 request
GET /api/v1/searchStories about a subject, best match first.1 request for every 25 stories
GET /api/v1/topThe stories that two or more outlets carried in the last 24 hours, the most widely carried first.1 request for every 25 stories
GET /api/v1/sourcesEvery outlet Ashum reads, when it was last checked, and whether that check worked.1 request
GET /api/v1/topicsThe seven sections stories are sorted into, and what each one covers.1 request
GET /api/v1/companiesEverything listed on Dubai Financial Market (DFM) today, in order of symbol: shares, funds, ETFs and REITs, each with its latest price.1 request
GET /api/v1/companies/{symbol}One DFM company as its page on ashum.ai shows it: the whole price line, its profile, the symbols it traded under before, the coming dates on DFM's calendar, and when it has filed its results in past years.1 request
GET /api/v1/disclosuresWhat DFM companies have filed with the exchange, newest first: results, board decisions, dividends, notices.1 request for every 25 disclosures
GET /api/v1/disclosures/{id}A single disclosure with the text of each attached document, a page at a time, and the address of the original file at DFM.1 request
GET /api/v1/prices/{symbol}A share's daily prices as DFM gives them, oldest first, in UAE dirhams.1 request
GET /api/v1/financials/{symbol}A DFM company's headline figures by period: revenue (or, for a bank, total income), profit, cash from operations, total assets and total equity.1 request
GET /api/v1/calendarThe dates on DFM's calendar: board meetings, general assemblies, earnings calls and the dates of a dividend.1 request
GET /api/v1/ownership/{symbol}How a DFM company's shares are held by the holder's nationality, by session, newest first, with the limit on foreign holders; and its largest shareholders as DFM lists them.1 request
GET /api/v1/flowsWhat each kind of investor, and investors of each nationality, bought and sold on DFM in a session, newest session first, in UAE dirhams.1 request
GET /api/v1/block-tradesThe block trades DFM lists (it calls them direct deals), newest first, in UAE dirhams.1 request
GET /api/v1/margin/{symbol}A DFM share's margin trading by week, newest first, in UAE dirhams, as DFM's weekly report gives it: the shares available for margin trading, and what was bought and sold on margin in the week.1 request
GET /api/v1/shariaThe DFM companies on DFM's own list of Shari'a-compliant companies for a quarter: the newest list held, or the quarter asked for.1 request
GET /api/v1/brokersDFM's ranking of its brokers for a month, first by the value they traded, in UAE dirhams, with each broker's share of the market's value, volume and trades.1 request
GET /api/v1/seriesThe dated figures Ashum keeps, each with its latest value.1 request
GET /api/v1/series/{code}One dated figure day by day, newest first.1 request
GET /api/v1/usageWhere the account stands: the requests it holds, what they are worth, and how many calls it made today.Free

Each address opens its section below. A call that returns an error costs nothing. How a call is counted

Start here

  1. Sign in and create a key. A new account comes with 200 requests to try the API; no card needed.
  2. Send the key with every request, in the Authorization header.
  3. Read the JSON that comes back. Every answer puts its content under data.
Request
curl "https://ashum.ai/api/v1/stories?limit=5" \
  -H "Authorization: Bearer YOUR_KEY"

Every address starts with https://ashum.ai/api/v1. All requests are GET. Times are UTC. The example answers on this page show the real shape; the stories in them are placeholders. The DFM examples are real answers from 13 November 2026, cut short.

Keys

A key looks like ashum_ followed by 32 characters. It is shown once, when you create it; Ashum keeps only a fingerprint of it, so a lost key cannot be shown again. Revoke it and make another.

Call the API from your server. A key placed in a web page or in an app people download can be read by anyone, and whoever reads it spends your requests.

Price and limits

The API is pay as you go, with no subscription. A new account starts with 200 trial requests. After that, add funds ($20 to $1,000 at a time): every dollar is 200 requests, which is $0.005 a request.

RequestsHow far backA minute, per keyKeys
Trial: 200, once30 days30010
From added fundsEverything, from 200830010

What a call costs. One request, for most calls. A call that returns a list of stories costs one request for every 25 stories, or part of 25, in the answer: up to 25 stories is one request, 100 stories is four. A list of disclosures is counted the same way. A call that returns an error costs nothing, and /usage is always free. With no requests left, calls answer 402 until funds are added.

Once an account has added funds, its requests reach the whole archive. “Everything” is the archive from January 2008. Outlets joined at different times, so how far back one outlet goes depends on the outlet. Search by meaning covers every outlet from January 2024 and part of the archive before it; the words of every story are searchable. DFM disclosures go back to 2000, and DFM’s daily prices to 31 December 2024.

Every answer to a valid key says where you stand: X-Credits-Remaining is the number of requests left and X-Request-Cost is what this call took. X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the minute starts again) count the minute; past the limit the answer is 429 with a Retry-After header in seconds. Every call made with a valid key counts toward the minute, whatever it answers.

New stories arrive every 10 minutes, so asking more often than every few minutes returns the same answer.

The feed

GET /api/v1/stories

Stories, newest first. The same feed as the front page of ashum.ai.

You can sendWhat it is
topicOne section: business, economy, government, world, tech, sport or life.
sourceOne outlet, by its id from /sources (for example wam).
qOnly stories whose headline or summary contains these words. Quotes match an exact phrase. Up to 120 characters.
sinceOnly stories published at or after this time, such as 2026-11-01T00:00:00Z.
untilOnly stories published before this time. On trial requests, a time more than 30 days back answers 402 funds_required.
limitHow many stories, 1 to 100. Default 25. Every 25 stories in the answer, or part of 25, counts as one request.
cursorThe next_cursor from the page before, to get the page after it.
Request
curl "https://ashum.ai/api/v1/stories?topic=economy&limit=1" \
  -H "Authorization: Bearer YOUR_KEY"
Answer
{
  "data": [
    {
      "id": "412345",
      "headline": "Example headline, exactly as the publisher wrote it",
      "summary": "The publisher's own first lines of the story.",
      "url": "https://publisher.example/the-story",
      "source": { "id": "wam", "name": "WAM" },
      "topic": "economy",
      "published_at": "2026-11-10T08:15:00.000Z"
    }
  ],
  "next_cursor": "MjAyNi0xMS0xMFQwODoxNTowMC4wMDBafDQxMjM0NQ"
}
In the answerWhat it is
dataThe stories, newest first. Each has the fields listed under A story.
next_cursorWhere the next page starts, or null when there are no more stories. See Paging.

One story and who else covered it

GET /api/v1/stories/{id}

A single story, with the same story in other outlets and related coverage from the days around it.

Request
curl "https://ashum.ai/api/v1/stories/412345" \
  -H "Authorization: Bearer YOUR_KEY"
Answer
{
  "data": {
    "id": "412345",
    "headline": "Example headline, exactly as the publisher wrote it",
    "summary": "The publisher's own first lines of the story.",
    "url": "https://publisher.example/the-story",
    "source": { "id": "wam", "name": "WAM" },
    "topic": "economy",
    "published_at": "2026-11-10T08:15:00.000Z",
    "same_story": [
      {
        "id": "412391",
        "headline": "The same event, as another outlet headlined it",
        "url": "https://another-publisher.example/the-story",
        "source": { "id": "gulf_news", "name": "Gulf News" },
        "topic": "economy",
        "published_at": "2026-11-10T08:40:00.000Z"
      }
    ],
    "related": []
  }
}
In the answerWhat it is
same_storyThe same story as other outlets ran it, earliest first. Empty when no other outlet carried it.
relatedOther stories on the same subject from the days around it. Empty when there are none.

Stories inside same_story and related carry no summary. Ask for each by its id if you need one.

Top stories

GET /api/v1/top

The stories that two or more outlets carried in the last 24 hours, the most widely carried first. Worked out again every 10 minutes.

You can sendWhat it is
limitHow many stories, 1 to 60. Default 25. Every 25 stories in the answer, or part of 25, counts as one request.
Request
curl "https://ashum.ai/api/v1/top?limit=10" \
  -H "Authorization: Bearer YOUR_KEY"
Answer
{
  "data": [
    {
      "id": "412345",
      "headline": "Example headline, exactly as the publisher wrote it",
      "summary": "The publisher's own first lines of the story.",
      "url": "https://publisher.example/the-story",
      "source": { "id": "wam", "name": "WAM" },
      "topic": "economy",
      "published_at": "2026-11-10T08:15:00.000Z",
      "outlets": 6
    }
  ]
}
In the answerWhat it is
outletsHow many outlets carried the story. Always 2 or more here.

Outlets

GET /api/v1/sources

Every outlet Ashum reads, when it was last checked, and whether that check worked.

Request
curl "https://ashum.ai/api/v1/sources" \
  -H "Authorization: Bearer YOUR_KEY"
Answer
{
  "data": [
    {
      "id": "wam",
      "name": "WAM",
      "last_checked_at": "2026-11-10T08:20:41.000Z",
      "last_ok_at": "2026-11-10T08:20:41.000Z",
      "ok": true
    }
  ]
}
In the answerWhat it is
idThe outlet's id: what a story carries in source.id, and what the source filter takes.
nameThe outlet's name, to show to people.
last_checked_atWhen Ashum last asked the outlet for stories, or null if it has not yet.
last_ok_atWhen a check last worked, or null.
oktrue if the latest check worked. false means the outlet could not be read just now; its earlier stories are still here.

The archive also holds a few stories from an outlet Ashum no longer reads: Zawya (zawya). It is not in this list, and the source filter takes it.

Sections

GET /api/v1/topics

The seven sections stories are sorted into, and what each one covers.

Request
curl "https://ashum.ai/api/v1/topics" \
  -H "Authorization: Bearer YOUR_KEY"
Answer
{
  "data": [
    {
      "id": "business",
      "name": "Business",
      "covers": "Companies and industries: deals, results, launches ..."
    }
  ]
}
In the answerWhat it is
idThe section's id: what a story carries in topic, and what the topic filter takes.
nameThe section's name, to show to people.
coversOne sentence on what is sorted into the section.

DFM companies

GET /api/v1/companies

Everything listed on Dubai Financial Market (DFM) today, in order of symbol: shares, funds, ETFs and REITs, each with its latest price. Prices are DFM's own, in UAE dirhams, read by Ashum every 10 minutes while the market is open.

Request
curl "https://ashum.ai/api/v1/companies" \
  -H "Authorization: Bearer YOUR_KEY"
Answer
{
  "data": [
    {
      "symbol": "EMAAR",
      "name": "Emaar Properties PJSC",
      "name_ar": "إعمار العقارية ش.م.ع",
      "sector": "Real Estate",
      "isin": "AEE000301011",
      "listed_on": "2000-03-25",
      "quote": {
        "price": 12.3, "change": -0.58, "change_pct": -4.503,
        "as_of": "2026-11-13T11:52:00.804Z"
      }
    }
  ]
}
In the answerWhat it is
symbolThe company's symbol on DFM today: what /companies/{symbol}, /prices/{symbol} and every symbol filter take.
nameThe company's registered name. name_ar is the same in Arabic, or null.
sectorThe sector DFM puts it in, or null.
isinIts ISIN, or null where DFM gives none.
listed_onThe day it was listed on DFM, or null.
quoteThe latest price: price, then change and change_pct (a percentage) against the previous close, and as_of, when Ashum read them from DFM. null for a share DFM gives no price for.

The list comes whole: one request returns every company. The example shows one of them. Shares listed on Nasdaq Dubai are not included.

One company

GET /api/v1/companies/{symbol}

One DFM company as its page on ashum.ai shows it: the whole price line, its profile, the symbols it traded under before, the coming dates on DFM's calendar, and when it has filed its results in past years. The symbol can be in any case, and a symbol the company used to trade under answers for the company as it is today.

Request
curl "https://ashum.ai/api/v1/companies/EMAAR" \
  -H "Authorization: Bearer YOUR_KEY"
Answer
{
  "data": {
    "symbol": "EMAAR",
    "name": "Emaar Properties PJSC",
    "name_ar": "إعمار العقارية ش.م.ع",
    "sector": "Real Estate",
    "isin": "AEE000301011",
    "listed_on": "2000-03-25",
    "active": true,
    "quote": {
      "price": 12.3, "change": -0.58, "change_pct": -4.503, "open": 12.32,
      "high": 12.42, "low": 12.24, "previous_close": 12.88, "high_52w": 17.26,
      "low_52w": 10.16, "volume": 29944909, "value": 368725164.64,
      "market_cap": 108717115143, "traded_on": "2026-11-13",
      "as_of": "2026-11-13T11:52:00.804Z"
    },
    "profile": {
      "description": "Emaar Properties Public Joint Stock Company (the ...",
      "established": "1997-06-23",
      "fiscal_year_end": "DECEMBER",
      "auditor": "Ernst & Young Middle East",
      "issued_shares": 8838789849,
      "website": "https://www.emaar.com/en",
      "board": [
        {
          "name": "Mr. Jamal Majed Khalfan BinTheniyah", "title": "Chairman"
        }
      ],
      "management": [
        {
          "name": "H.E. Mohamed Ali Rashed Alabbar",
          "title": "Managing Director"
        }
      ]
    },
    "former_symbols": [],
    "calendar": [
      {
        "kind": "ex_dividend", "date": "2026-11-13",
        "title": "EMAAR - Ex-Dividend Date",
        "disclosure_id": "bd7523db-e2b6-48b4-82fa-f191cfb6cb9a"
      }
    ],
    "results_timing": [
      {
        "period": "Q1",
        "name": "First quarter",
        "filed_at": [
          "2019-03-31T06:01:00.000Z", "2021-05-10T18:58:09.000Z",
          "2022-05-13T12:14:00.000Z", "2023-05-15T04:38:00.000Z",
          "2024-05-15T11:57:04.000Z", "2025-05-14T12:49:33.000Z",
          "2026-05-11T04:07:27.000Z"
        ]
      }
    ]
  }
}
In the answerWhat it is
symbolThe symbol the company trades under today, whichever one you asked with. name, name_ar, sector, isin and listed_on are as in /companies.
activefalse for a company DFM no longer lists. Such a company is not in /companies, and still answers here.
quoteThe whole price line. Beside the four fields of /companies: open, high, low and previous_close; high_52w and low_52w, the range of the last 52 weeks; volume (shares) and value (dirhams) traded in the session; market_cap; and traded_on, the day of that session. A figure DFM does not give is null: a share that has not traded today has no open, high or low.
profileWhat the company has told DFM about itself: description, established (a day), fiscal_year_end, auditor, issued_shares, website, and the people on its board and in its management, each with a name and a title. Any of them can be null, and so can the whole profile.
former_symbolsThe symbols the company traded under before, the latest first: the symbol, the name it carried, and until, the last day Ashum has it on record under them. Empty for most companies.
calendarUp to 12 coming dates from DFM's calendar, the soonest first. Each has the fields of /calendar, without symbol and company.
results_timingWhen the company has filed each set of results since 2019. period is Q1, Q2, Q3 or Yearly, name says it in words, and filed_at holds the time of the first filing in each year, oldest first. A period filed in fewer than three years is left out.

The example is cut short: the real answer lists every member of the board and of the management, every coming date and all four sets of results. A company that changed its symbol answers under both: /companies/GULFNAV returns ETIHADENERGY, with GULFNAV under former_symbols.

Disclosures

GET /api/v1/disclosures

What DFM companies have filed with the exchange, newest first: results, board decisions, dividends, notices. DFM publishes each disclosure twice, in English and in Arabic, as two records with their own ids; lang picks which you get.

You can sendWhat it is
symbolOnly one company's disclosures, by its symbol. Any case; a symbol it used to trade under works too.
categoryOnly disclosures of one kind: results, dividend, board, assembly, ownership, capital, governance, debt, legal, business or other.
majortrue for only the disclosures scored 2 or over on importance: mostly results, dividends, changes of capital and deals.
qOnly disclosures whose headline contains these words. Quotes match an exact phrase. Up to 120 characters.
langen (default) or ar.
sinceOnly disclosures published at or after this time, such as 2026-11-01T00:00:00Z.
untilOnly disclosures published before this time. On trial requests, a time more than 30 days back answers 402 funds_required.
limitHow many disclosures, 1 to 100. Default 25. Every 25 disclosures in the answer, or part of 25, counts as one request.
cursorThe next_cursor from the page before, to get the page after it.
Request
curl "https://ashum.ai/api/v1/disclosures?symbol=EMAAR&limit=1" \
  -H "Authorization: Bearer YOUR_KEY"
Answer
{
  "data": [
    {
      "id": "5422410b-b7cf-4aa3-89b3-f3cbc3834a7f",
      "symbol": "EMAAR",
      "company": "Emaar Properties PJSC",
      "headline": "Notification from the company",
      "published_at": "2026-11-13T11:15:28.000Z",
      "results_period": null,
      "category": "capital",
      "importance": 2.2,
      "lang": "en",
      "documents": [
        {
          "title": "Notification Re EFG Hermes.Pdf", "pages": 1,
          "has_text": true, "text_from": "file"
        }
      ],
      "url": "https://ashum.ai/stocks/EMAAR/disclosures/5422410b-b7cf-4aa3-89b3-f3cbc3834a7f"
    }
  ],
  "next_cursor": "MjAyNi0xMS0xM1QxMToxNToyOC4wMDBafDU0MjI0MTBiLWI3Y2YtNGFhMy04OWIzLWYzY2JjMzgzNGE3Zg"
}
In the answerWhat it is
idThe disclosure's id: what /disclosures/{id} takes. The English and the Arabic record of one disclosure have different ids.
symbolThe company's symbol on DFM today, and company, its name.
headlineThe headline as it was filed, in the record's language.
published_atWhen DFM published it. UTC, ISO 8601.
results_periodDFM's own label on a periodic report: on financial results Q1, Q2, Q3 or Yearly. null on everything else.
categoryWhat kind of disclosure it is: results, dividend, board, assembly, ownership, capital, governance, debt, legal, business or other. A classifier picks it from the headline and the start of the document, so it can be wrong; other is also what a headline that says nothing gets while Ashum holds no text for it.
importanceHow much the disclosure matters to a shareholder, from 0 (routine: the notice of a meeting) to 3 (major: results, a dividend, a change of capital, a deal). A classifier scores it from the headline and the start of the document, so it can be wrong; null while a new disclosure waits to be scored.
langen or ar.
documentsThe files attached, in order; a disclosure can have none. Each has its title, its pages (null for a file Ashum has not read), has_text (whether Ashum holds its text) and text_from: file when the text was inside the file, scan when the pages are pictures of paper that a vision model read, file_and_scan when the file has pages of both kinds, null when no text is held.
urlThe disclosure's page on ashum.ai, where its text can be read.
next_cursorWhere the next page starts, or null when there are no more disclosures. See Paging.

Disclosures go back to 2000. Ashum reads the text of PDF documents filed since 13 November 2024. A file scanned from paper has text only once its pages have been read, and not every scan has been read yet: has_text says which. The English files filed before that day are being read too, newest first: those with text inside the file have it, and the scanned ones get theirs over the coming weeks. Older Arabic files, and files that are not PDFs, are listed without text.

One disclosure and the text of its documents

GET /api/v1/disclosures/{id}

A single disclosure with the text of each attached document, a page at a time, and the address of the original file at DFM.

Request
curl "https://ashum.ai/api/v1/disclosures/bd7523db-e2b6-48b4-82fa-f191cfb6cb9a" \
  -H "Authorization: Bearer YOUR_KEY"
Answer
{
  "data": {
    "id": "bd7523db-e2b6-48b4-82fa-f191cfb6cb9a",
    "symbol": "EMAAR",
    "company": "Emaar Properties PJSC",
    "headline": "Resolutions of General Assembly",
    "published_at": "2026-11-04T12:38:28.000Z",
    "results_period": null,
    "category": "assembly",
    "importance": 1.3,
    "lang": "en",
    "documents": [
      {
        "title": "EP General Assembly Results 4 Nov 26.Pdf",
        "pages": 2,
        "has_text": true,
        "text_from": "scan",
        "file_url": "https://feeds.dfm.ae/documents/2026/Nov/4/bd7523db-e2b6-48b4-82fa-f191cfb6cb9a/EP%20General%20Assembly%20Results%204%20Nov%2026.Pdf.pdf",
        "text": [
          "EMAAR\n\nDisclosure of the Results of General Assembly Meeting ...",
          "EMAAR\n\nclosing date will be 16 November 2026. ..."
        ]
      }
    ],
    "url": "https://ashum.ai/stocks/EMAAR/disclosures/bd7523db-e2b6-48b4-82fa-f191cfb6cb9a"
  }
}
In the answerWhat it is
documentsAs in /disclosures, and for each document also file_url and text. The other fields are those of /disclosures.
file_urlThe original file on DFM's website. The file at DFM is the record.
textThe document's text, one entry for each page, in page order. A page without text is an empty entry. The list is empty when has_text is false.

The text is read from the file by program. Where text_from is scan or file_and_scan, the scanned pages were read by a vision model or a text-recognition program and can carry mistakes. In the example each page is cut to its first words.

Daily prices

GET /api/v1/prices/{symbol}

A share's daily prices as DFM gives them, oldest first, in UAE dirhams. DFM's history starts on 31 December 2024. The symbol can be in any case, and a former symbol works too.

You can sendWhat it is
sinceOnly days on or after this day, such as 2026-11-01.
untilOnly days before this day. On trial requests, a day more than 30 days back answers 402 funds_required.
Request
curl "https://ashum.ai/api/v1/prices/EMAAR?since=2026-11-11&until=2026-11-13" \
  -H "Authorization: Bearer YOUR_KEY"
Answer
{
  "data": [
    {
      "date": "2026-11-11", "open": 12.96, "high": 13, "low": 12.84,
      "close": 12.94, "volume": 39585563, "value": 512216083.82
    },
    {
      "date": "2026-11-12", "open": 12.88, "high": 12.96, "low": 12.8,
      "close": 12.88, "volume": 30245599, "value": 389334155.62
    }
  ],
  "symbol": "EMAAR"
}
In the answerWhat it is
dataThe days, oldest first. Everything asked for comes in one answer; there are no pages.
dateThe trading day.
openThe day's first price. high, low and close are its highest, its lowest and its closing price.
volumeShares traded that day.
valueDirhams traded that day.
symbolThe symbol the company trades under today, whichever one you asked with.

Trial requests reach the last 30 days of this history. All of it opens once the account has added funds.

Financials

GET /api/v1/financials/{symbol}

A DFM company's headline figures by period: revenue (or, for a bank, total income), profit, cash from operations, total assets and total equity. The financial years come first, then the shorter periods, each newest first. Every figure is one the company printed in the financial statements it filed with DFM, and names the filing and the page it stands on.

Request
curl "https://ashum.ai/api/v1/financials/EMAAR" \
  -H "Authorization: Bearer YOUR_KEY"
Answer
{
  "data": [
    {
      "period_end": "2025-12-31",
      "months": 12,
      "currency": "AED",
      "figures": {
        "revenue": {
          "value": 49557263000, "label": "Revenue", "page": 11,
          "disclosure_id": "9e0de168-d6ee-4ebe-a343-58b56a84ab2f",
          "url": "https://ashum.ai/stocks/EMAAR/disclosures/9e0de168-d6ee-4ebe-a343-58b56a84ab2f"
        },
        "profit": {
          "value": 22325535000, "label": "NET PROFIT FOR THE YEAR", "page": 11,
          "disclosure_id": "9e0de168-d6ee-4ebe-a343-58b56a84ab2f",
          "url": "https://ashum.ai/stocks/EMAAR/disclosures/9e0de168-d6ee-4ebe-a343-58b56a84ab2f"
        }
      }
    }
  ],
  "symbol": "EMAAR"
}
In the answerWhat it is
period_endThe last day of the period.
monthsHow long the period is: 12 for a financial year, 3, 6 or 9 for a shorter one.
currencyThe currency the company reports in: AED for most, KWD, USD or another for a company that reports in it. Values are in whole units of it.
figuresThe lines held for the period, by name: revenue, total_income or total_operating_income (a company carries one of them), profit, operating_cash_flow, total_assets and total_equity. A line with no figure is absent. total_assets and total_equity are as at period_end.
valueThe figure, with losses and cash used as negative numbers. label is the wording printed beside it in the statements.
pageThe page of the filed document the figure stands on. disclosure_id is the filing, for /disclosures/{id}, and url its page on Ashum; both are null where the file is on no disclosure Ashum holds.

Figures are as first reported: where a later filing restates an earlier period, the earlier filing's figure stays. profit is the whole profit of the period, before the share of non-controlling interests is taken off, so it can be larger than the profit attributable to shareholders that other sources give. The figures were read from the filings by program; a period is left without a line rather than given a doubtful one. They go back to 2010 for the older companies. The example shows two of the five lines of one year.

DFM calendar

GET /api/v1/calendar

The dates on DFM's calendar: board meetings, general assemblies, earnings calls and the dates of a dividend. Earliest first. With neither since nor until, the answer starts today (Gulf time), so it is the coming dates.

You can sendWhat it is
symbolOnly one company's dates, by its symbol. Any case; a symbol it used to trade under works too.
sinceOnly days on or after this day, such as 2026-11-01.
untilOnly days before this day. On trial requests, a day more than 30 days back answers 402 funds_required.
Request
curl "https://ashum.ai/api/v1/calendar?symbol=EMAAR" \
  -H "Authorization: Bearer YOUR_KEY"
Answer
{
  "data": [
    {
      "symbol": "EMAAR", "company": "Emaar Properties PJSC",
      "kind": "ex_dividend", "date": "2026-11-13",
      "title": "EMAAR - Ex-Dividend Date",
      "disclosure_id": "bd7523db-e2b6-48b4-82fa-f191cfb6cb9a"
    },
    {
      "symbol": "EMAAR", "company": "Emaar Properties PJSC",
      "kind": "record_date", "date": "2026-11-16",
      "title": "EMAAR - Registry Closing Date",
      "disclosure_id": "bd7523db-e2b6-48b4-82fa-f191cfb6cb9a"
    },
    {
      "symbol": "EMAAR", "company": "Emaar Properties PJSC",
      "kind": "dividend_payment", "date": "2026-11-27",
      "title": "EMAAR - Dividends Payment Date",
      "disclosure_id": "bd7523db-e2b6-48b4-82fa-f191cfb6cb9a"
    }
  ]
}
In the answerWhat it is
symbolThe company's symbol on DFM today, and company, its name.
kindboard_meeting, general_assembly, earnings_call, or one of the dates of a dividend: last_day_to_buy (the last day to buy the share and still receive it), ex_dividend, record_date and dividend_payment.
dateThe day, as DFM's calendar has it.
titleDFM's own line for the date, or null.
disclosure_idThe disclosure the date comes from, to ask /disclosures/{id} for, or null.

Ashum reads DFM's calendar after each trading day, for the month before, the month itself and the three months after it. The dates it holds start in October 2026.

Who owns a company

GET /api/v1/ownership/{symbol}

How a DFM company's shares are held by the holder's nationality, by session, newest first, with the limit on foreign holders; and its largest shareholders as DFM lists them. The figures are DFM's own, read by Ashum the morning after each session.

You can sendWhat it is
sinceOnly sessions on or after this day, such as 2026-11-13.
untilOnly sessions before this day. On trial requests, a day more than 30 days back answers 402 funds_required.
Request
curl "https://ashum.ai/api/v1/ownership/DIB" \
  -H "Authorization: Bearer YOUR_KEY"
Answer
{
  "data": [
    {
      "date": "2026-11-13",
      "uae_nationals": 84.99, "gcc_nationals": 2.34,
      "arab_nationals": 1.15, "other_nationalities": 11.52,
      "foreign_owned": 15.01, "foreign_limit": 40, "foreign_room": 24.99
    }
  ],
  "largest_shareholders": [
    { "name": "INVESTMENT CORPORATION OF DUBAI", "percent": 27.9661, "as_of": "2026-11-13" }
  ],
  "symbol": "DIB"
}
In the answerWhat it is
dateThe session the figures are for.
uae_nationalsPercent of the company's shares held by UAE nationals. gcc_nationals, arab_nationals and other_nationalities are the shares held by nationals of the other Gulf states, by other Arab nationals and by everyone else.
foreign_ownedPercent held by all holders who are not UAE nationals, together.
foreign_limitThe most those holders may hold together, in percent. 100 means no limit; null where DFM gives none.
foreign_roomThe limit less what is held, worked out by Ashum; null where either figure is missing.
largest_shareholdersThe shareholders DFM lists for the company today, largest first, each with its percent and the day DFM gives it for. Names are as DFM writes them; some are in Arabic. An empty list where DFM lists none.

With neither since nor until, the answer is the last 30 sessions Ashum holds. Ashum holds these figures for every session from 2 January 2025. The largest shareholders are the latest list only. A company DFM gives no ownership for answers with an empty data.

Who bought and who sold

GET /api/v1/flows

What each kind of investor, and investors of each nationality, bought and sold on DFM in a session, newest session first, in UAE dirhams. The groups and the amounts are DFM's own, read by Ashum the morning after each session.

You can sendWhat it is
sinceOnly sessions on or after this day, such as 2026-11-01.
untilOnly sessions before this day. On trial requests, a day more than 30 days back answers 402 funds_required.
Request
curl "https://ashum.ai/api/v1/flows?since=2026-11-13" \
  -H "Authorization: Bearer YOUR_KEY"
Answer
{
  "data": [
    {
      "date": "2026-11-13",
      "by_investor_type": [
        { "group": "Banks", "bought": 41523107.93, "sold": 82990434.86, "net": -41467326.93 },
        { "group": "Companies", "bought": 428784079.58, "sold": 397299648.98, "net": 31484430.6 }
      ],
      "by_nationality": [
        { "group": "UAE Nationals", "bought": 368291125.03, "sold": 406052884.89, "net": -37761759.86 }
      ]
    }
  ],
  "unit": "AED"
}
In the answerWhat it is
dateThe session.
by_investor_typeDFM's kinds of investor: Banks, Companies, Institutions, Individuals and OTHER. Each has what it bought and sold in the session and net, the first less the second, worked out by Ashum.
by_nationalityThe same session by the investor's nationality, in DFM's groups: UAE Nationals, GCC, ARAB and OTHERS.
unitAlways AED.

With neither since nor until, the answer is the last 30 sessions. DFM gives these figures from 2 January 2025. Across the groups of one list the buying equals the selling. The example shows two of the five kinds of investor and one of the four nationalities.

Block trades

GET /api/v1/block-trades

The block trades DFM lists (it calls them direct deals), newest first, in UAE dirhams. Each row is one share on one day at one price, with how many deals were done at it. The figures are DFM's own, read by Ashum each morning.

You can sendWhat it is
symbolOnly one company's, such as SALIK. An unknown symbol answers 404 not_found.
sinceOnly days on or after this day, such as 2026-11-01.
untilOnly days before this day. On trial requests, a day more than 30 days back answers 402 funds_required.
Request
curl "https://ashum.ai/api/v1/block-trades?since=2026-11-01" \
  -H "Authorization: Bearer YOUR_KEY"
Answer
{
  "data": [
    {
      "date": "2026-11-12", "symbol": "ETIHADENERGY",
      "company": "Etihad Energy Holding P.J.S.C",
      "price": 2.88, "volume": 15400000,
      "value": 44352000, "trades": 2
    }
  ],
  "unit": "AED"
}
In the answerWhat it is
dateThe day of the trade.
priceDirhams a share.
volumeShares that changed hands at that price that day.
valueWhat they were worth, in dirhams.
tradesHow many deals were done at that price that day.

With neither since nor until, the answer is the newest 100 (on trial requests, those of the last 30 days). DFM lists block trades from 2016. A share can have more than one row on a day, one for each price.

Margin trading of a share

GET /api/v1/margin/{symbol}

A DFM share's margin trading by week, newest first, in UAE dirhams, as DFM's weekly report gives it: the shares available for margin trading, and what was bought and sold on margin in the week.

You can sendWhat it is
sinceOnly weeks ending on or after this day, such as 2026-10-01.
untilOnly weeks ending before this day. On trial requests, a day more than 30 days back answers 402 funds_required.
Request
curl "https://ashum.ai/api/v1/margin/AIRARABIA" \
  -H "Authorization: Bearer YOUR_KEY"
Answer
{
  "data": [
    {
      "week_ending": "2026-11-13",
      "available_shares": 28098289,
      "bought": { "trades": 46, "shares": 241672, "value": 1232097.2 },
      "sold": { "trades": 52, "shares": 138361, "value": 703321.64 }
    }
  ],
  "symbol": "AIRARABIA",
  "unit": "AED"
}
In the answerWhat it is
week_endingThe last day of the week the figures are for, as DFM gives it.
available_sharesThe shares available for margin trading, as DFM reports it.
boughtWhat was bought on margin in the week: the number of trades, the shares, and their value in dirhams. sold is the same for what was sold.

With neither since nor until, the answer is the last 12 weeks Ashum holds (on trial requests, those of the last 30 days). Ashum holds these weeks from January 2025. A share DFM reports no margin trading for answers with an empty data.

Shari'a-compliant companies

GET /api/v1/sharia

The DFM companies on DFM's own list of Shari'a-compliant companies for a quarter: the newest list held, or the quarter asked for. The list is DFM's; Ashum makes no judgement of its own.

You can sendWhat it is
yearThe year of the quarter, such as 2025. Give it together with quarter.
quarterThe quarter, 1 to 4. On trial requests, a quarter other than the newest that ended more than 30 days ago answers 402 funds_required.
Request
curl "https://ashum.ai/api/v1/sharia" \
  -H "Authorization: Bearer YOUR_KEY"
Answer
{
  "data": [
    {
      "symbol": "SALAMA",
      "company": "Islamic Arab Insurance Company PJSC",
      "status": "Shari’a Compliance"
    }
  ],
  "year": 2026,
  "quarter": 1
}
In the answerWhat it is
statusWhat DFM writes beside the company on the list. The list holds the compliant companies only: a company that is not in the answer is not on that quarter's list.
yearThe year of the list answered, and quarter its quarter.

DFM publishes the list months after the quarter it is for, so the newest list is answered however old it is. Lists are held from the third quarter of 2012. A quarter with no list held answers 404 not_found. The example shows one of the 50 companies on the list.

Broker ranking

GET /api/v1/brokers

DFM's ranking of its brokers for a month, first by the value they traded, in UAE dirhams, with each broker's share of the market's value, volume and trades. The figures are DFM's own.

You can sendWhat it is
monthA month, such as 2026-09. Without it, the newest month held. On trial requests, a month other than the newest that ended more than 30 days ago answers 402 funds_required.
Request
curl "https://ashum.ai/api/v1/brokers" \
  -H "Authorization: Bearer YOUR_KEY"
Answer
{
  "data": [
    {
      "rank": 1, "broker": "EFG HERMES (UAE)", "code": "EFGH",
      "value": 4802715389.92, "value_percent": 19.526,
      "volume": 910826818, "volume_percent": 10.018,
      "trades": 122679, "trades_percent": 20.461
    }
  ],
  "month": "2026-10",
  "unit": "AED"
}
In the answerWhat it is
rankThe broker's place in the month, by value traded.
brokerThe broker's name as DFM writes it; its code where DFM gives no name.
valueWhat the broker traded in the month, in dirhams, and value_percent what that is of the whole market's. volume (shares) and trades have their own percentages.

DFM ranks a month once it has ended, so the newest month is the last whole one. Ashum holds the ranking from January 2025. A month with no ranking held answers 404 not_found. The example shows the first of 30 brokers.

Exchange rates, fuel and oil prices, and other dated figures

GET /api/v1/series

The dated figures Ashum keeps, each with its latest value. Today that is the Central Bank of the UAE's official exchange rate for 77 currencies, in dirhams for one unit of each, the UAE's fuel prices for the month, in dirhams a litre, and the US Energy Information Administration's daily spot prices for Brent and WTI crude, in dollars a barrel. With day, the answer is the figure in force on that day instead. The rates are the Central Bank's own (© Central Bank of the UAE), read by Ashum each working evening.

You can sendWhat it is
groupOnly one kind of figure. fx: the Central Bank's exchange rates. fuel: the month's fuel prices. oil: the spot prices of Brent and WTI crude.
dayA day, such as 2026-11-14. The answer is then each figure in force on that day: the newest one on or before it, under its own date. A Saturday answers with Friday's rates. On trial requests, a day more than 30 days back answers 402 funds_required.
Request
curl "https://ashum.ai/api/v1/series?group=fx&day=2026-11-14" \
  -H "Authorization: Bearer YOUR_KEY"
Answer
{
  "data": [
    {
      "code": "fx-usd", "name": "US dollar", "group": "fx",
      "unit": "AED per 1 USD", "every": "day",
      "source": "Central Bank of the UAE",
      "date": "2026-11-13", "value": 3.6725
    }
  ],
  "day": "2026-11-14"
}
In the answerWhat it is
codeThe figure's code: what /series/{code} takes. An exchange rate is fx- and the currency's code in small letters.
unitWhat value is counted in. An exchange rate is in dirhams for one unit of the currency, as the Central Bank publishes it: 0.038968 for the Indian rupee means one dirham buys 1 ÷ 0.038968 = 25.66 rupees.
everyHow often the source gives a new figure: day or month.
dateThe day the source gives the figure for.
valueThe figure, as a number.
first_dateThe first day Ashum holds the figure for. Not in an answer to day.
dayThe day asked for, when one was.

Without day, each figure is its latest. The Central Bank gives one rate a currency each working day, out after 18:00 Gulf time, and none at a weekend; Ashum holds them from January 2019. It is an official rate, not a live market rate: a bank or an exchange house sets its own. The example shows one of the 77 currencies. Fuel prices (fuel-super98, fuel-special95, fuel-eplus91, fuel-diesel) are set for each month by the UAE's fuel price committee: a month's prices carry the date of its first day, and Ashum keeps a month only once two of the outlets it follows report the same four prices, so a month it could not confirm is missing. Months from before Ashum began reading were entered by hand from the outlets' own stories and price tables, each only where two outlets give the same figure. Oil spot prices (oil-brent-spot, oil-wti-spot) are the US Energy Information Administration's, a public-domain publication: one price a working day, published weekly a few days behind, from 1987 for Brent and 1986 for WTI. The futures closes on the site's oil page come from Yahoo Finance and are not in the API.

One dated figure over time

GET /api/v1/series/{code}

One dated figure day by day, newest first. The Central Bank of the UAE's rate for the Indian rupee is fx-inr; /series lists every code.

You can sendWhat it is
sinceOnly days on or after this day, such as 2026-11-01.
untilOnly days before this day. On trial requests, a day more than 30 days back answers 402 funds_required.
Request
curl "https://ashum.ai/api/v1/series/fx-inr?since=2026-11-12" \
  -H "Authorization: Bearer YOUR_KEY"
Answer
{
  "data": [
    { "date": "2026-11-13", "value": 0.038968 },
    { "date": "2026-11-12", "value": 0.039049 }
  ],
  "code": "fx-inr", "name": "Indian rupee", "group": "fx",
  "unit": "AED per 1 INR", "every": "day",
  "source": "Central Bank of the UAE"
}
In the answerWhat it is
dateThe day the source gives the figure for. A day with no figure (a weekend, a public holiday) is not listed.
valueThe figure, in the series' unit.

An answer carries 1,000 days at most. With neither since nor until it is the newest 1,000 that Ashum holds; for older days, ask again with until set to the last date you were given. A code that does not exist answers 404 not_found.

Your balance and usage

GET /api/v1/usage

Where the account stands: the requests it holds, what they are worth, and how many calls it made today. This call is free and answers even with no requests left.

Request
curl "https://ashum.ai/api/v1/usage" \
  -H "Authorization: Bearer YOUR_KEY"
Answer
{
  "data": {
    "plan": "payg",
    "credits": 3788,
    "balance_usd": 18.94,
    "requests_per_minute": 300,
    "used_today": 212,
    "archive_days": null
  }
}
In the answerWhat it is
plantrial while the account is on its trial requests, payg once it has added funds.
creditsThe requests left on the account. One credit is one request; the X-Credits-Remaining header carries the same number.
balance_usdWhat those requests are worth in US dollars.
requests_per_minuteHow many requests each key may make in a minute.
used_todayCalls made today (the UTC day) with any of the account's keys. Free calls and calls that ended in an error count too.
archive_daysHow many days back the account's requests reach: 30 on trial requests, null (the whole archive) once it has added funds.

A story

Every story, in every answer, has these fields.

FieldWhat it is
idThe story's id on Ashum. A string of digits; keep it as text.
headlineThe publisher's headline, unchanged.
summaryThe publisher's own short description, or null when the outlet gives none. Ashum keeps up to 1,000 characters, and a summary that was cut mid-sentence ends with ….
urlThe story on the publisher's site.
sourceThe outlet: its id and its name.
topicThe section the story was sorted into, or null for the few minutes before a new story is sorted.
published_atWhen the publisher says the story went out. UTC, ISO 8601.

Headlines and summaries belong to their publishers. Show the outlet’s name with each story and link to the original.

Paging

/stories returns one page and a next_cursor. Send it back as cursor, with the same filters, to get the next page. A next_cursor of null means there is no more. The cursor marks a place in the feed, so pages stay correct while new stories arrive above them. /disclosures pages the same way, with cursors of its own.

Only /stories and /disclosures have pages. /search and /top answer with up to 60 stories at once, and the other lists come whole.

Errors

An error has an HTTP status and one shape. The code is for your program; the message is for you.

An error
{
  "error": {
    "code": "invalid_parameter",
    "message": "limit: must be a whole number from 1 to 100"
  }
}
StatusCodeWhat happened
400invalid_parameterSomething in the address is not what the endpoint takes: a value out of range, or a name it does not list. The message names it.
401missing_keyNo key was sent in the Authorization header. Your keys
401invalid_keyThe key is not recognised, or it was revoked. Your keys
402balance_requiredThe account has no requests left. Add funds
402funds_requiredA trial request asked for something older than 30 days. The whole archive opens once the account has added funds. Add funds
404not_foundNo story or disclosure has that id, no DFM company has that symbol, or the address is not one of the endpoints on this page.
429rate_limitedMore requests in one minute than a key may make. Wait the seconds in Retry-After.
429too_many_attemptsMany requests without a valid key came from your address. Wait a minute.
500server_errorSomething failed on our side. Try again shortly.

Something this page does not answer? Write to support@convertlyft.com. Your keys and your balance are on your account.