REST API

What it is

Four endpoints on https://api.gloom.sh/v1: quotes, data by ticker and field, history, and the field dictionary. They read the same market data as the MCP server and take the same keys. Tickers and fields can be written the Bloomberg way, so AAPL US Equity with PX_LAST works next to AAPL with price.

The OpenAPI document is at https://api.gloom.sh/v1/openapi.json; import it into Postman, Insomnia or a client generator. For spreadsheets, use the Google Sheets functions.

Keys and limits

Create a key with Market data only access in Cloud settings, Agents and send it as Authorization: Bearer gloom_mcp_... or x-api-key. A key with broader access is refused (403 key_too_broad): data keys end up in shared sheets and scripts, where it would let their readers reach your notes, teams and brokers. Data calls need Gloom Pro; /v1/fields and the OpenAPI document need no key.

A key spends 120 units a minute and 5,000 a day, shared with its MCP use, where one tool call is one unit. A request costs about what the same data costs over MCP, and the X-Gloom-Units header says what it cost. Over the limit answers 429 with Retry-After. News API keys (gloom_news_) only work for /v1/news.

Every endpoint takes GET with comma-separated lists or POST with a JSON body. /v1/data and /v1/history answer within about 12 seconds: anything not ready by then comes back as a timeout error on its item, and a retry a moment later reads it from the cache.

Example

curl -s -G 'https://api.gloom.sh/v1/data' \
  -H 'Authorization: Bearer gloom_mcp_...' \
  --data-urlencode 'tickers=AAPL US Equity,VOD LN Equity,SPX Index' \
  --data-urlencode 'fields=PX_LAST,BEST_PE_RATIO,SALES_REV_TURN'

curl -s -G 'https://api.gloom.sh/v1/history' \
  -H 'Authorization: Bearer gloom_mcp_...' \
  --data-urlencode 'tickers=CL1 Comdty' \
  --data-urlencode 'fields=PX_LAST,PX_VOLUME' \
  -d start=2026-01-01 -d period=weekly

Tickers

Send any of these, mixed in one request. Each item echoes how it was read in resolved: our own form, the exchange, the dialect and the name.

CL1 Comdty is the rolling front-month generic, built from Gloom's settlement archive. In Bloomberg form it rolls at expiry, as Bloomberg's generics do, and reads as our CL1E; our own CL1 rolls when the next month's open interest passes it. Index futures take the Index key as on Bloomberg: ES1 Index, NQ1 Index, RTY1 Index, DM1 Index (Dow), UX1 Index (VIX). CN covers Toronto and TSX Venture, TT Taiwan and TPEx. Government bonds, corporate bonds and other Govt or Corp securities are not served.

Fields and units

Fields take our id or a Bloomberg mnemonic, in any case. Values come back keyed by the field as you sent it. A Bloomberg alias exists only where we serve Bloomberg's definition; the list below shows each one, and fields we do not serve say why.

• London, Johannesburg and Tel Aviv listings asked in Bloomberg form answer in pence, cents and agorot, as Bloomberg quotes them: PX_LAST for VOD LN Equity is 124 and CRNCY is GBp (ZAr, ILs). Market cap stays in the main currency and currencies says so. Gloom and exchange-suffixed forms (VOD:XLON, VOD.L) answer in pounds.
• Statement fields read the latest annual statement (period=quarterly for the latest quarter), from the same statements /v1/history reads: the filings first for US companies. Under Bloomberg names they are in millions, as Bloomberg reports them; under our ids in full units. periods gives the fiscal period end behind each value, and currencies any value not in the price currency, such as revenue in the reporting currency.
• Where a filing has no fiscal Q4 row, the quarter is the full year less Q1 to Q3 (year-end figures for the balance sheet; average share counts are left out). derived lists those values in /v1/data and those dates in /v1/history.
• BEST_EPS, BEST_SALES and BEST_PE_RATIO use the first unreported fiscal year, Bloomberg's default. BEST_PE_RATIO converts the estimate into the price currency.
• VOLATILITY_30D and its siblings annualize daily log returns with the square root of 260. BETA_RAW_OVERRIDABLE regresses two years of weekly returns on the S&P 500; EQY_BETA is 0.67 times that plus 0.33. Both for US listings only.

Errors

One bad item never fails the request. An unreadable or unknown ticker comes back as that item's error; a field that does not apply or has no value comes back in the item's errors with a null value. Only a malformed request (400), a missing or revoked key (401), a free plan (402), a key broader than Market data only (403) or a rate limit (429) fails the whole call, with { "error": code, "message": text }.