Build a news signal dashboard

This recipe assembles a daily news-flow digest from the Sugra News direction: what was just published, which themes dominate world media right now, how coverage volume and tone are moving for a theme you watch, and how one company's news sentiment and attention look today. Six GET requests against https://sugra.ai with the x-api-key header are all it takes, and every endpoint is available on every plan.

What you build

Four dashboard panels, each fed by one or two of the requests below. Run them on a schedule (hourly for the headline board, daily for the rest), keep the JSON, and render each panel from data; every response carries meta.data_time so each panel can display its own freshness. Steps 3 to 5 read the GDELT files Sugra already stores. The served window is at most 24 hours. A missing file is 503 blob_not_ready.

Headline board - the latest curated headlines for a region and category, refreshed every 5 minutes.

Theme radar - the GDELT themes trending across global media over the last 6 hours.

Theme tracker - coverage volume and tone series for a theme you follow (here: energy).

Ticker panel - news-flow sentiment and attention for one company (here: MSFT).

1. Pull the headline board

{
  "data": {
    "total": 10,
    "count": 2,
    "items": [
      {
        "title": "My husband and I are retired. Our financial adviser, who is in his 30s, called us ‘you guyses.’ Is that unprofessional?",
        "published": "2026-07-19T09:20:00Z",
        "source": "marketwatch",
        "region": "us",
        "category": "business"
      }
    ]
  },
  "meta": { "endpoint": "/api/v1/news/latest", "source": "news_rss" }
}

(Second item and the per-item description, link, and source_name fields truncated; meta is trimmed to endpoint and source in every excerpt on this page.) This is the Sugra News curated feed digest. Filter with region (us, europe, asia, and more) and category (news, business, tech, defense, ...), or swap in GET /api/v1/news/search?q=... to keyword-filter the same item shape for your theme.

2. Scan the theme radar

{
  "data": {
    "themes": [
      { "theme": "TAX_FNCACT", "count": 9114, "share": 0.0297 },
      { "theme": "CRISISLEX_CRISISLEXREC", "count": 4751, "share": 0.0155 },
      { "theme": "EPU_POLICY", "count": 4516, "share": 0.0147 }
    ],
    "stale": false,
    "partial": false
  },
  "meta": { "endpoint": "/api/v1/gdelt/themes/trending", "source": "gdelt_live" }
}

(Two of five themes and the total, window_end, and languages fields truncated.) Each entry is a GDELT GKG theme code with its mention count and share of all theme mentions in the window. Check stale and partial before rendering: they tell you whether the ingest window behind the aggregate is fresh and complete.

3. Chart coverage volume for your theme

{
  "data": {
    "timeline": [ {
      "series": "timelinevol",
      "data": [ { "date": "2026-10-05T19:45:00Z", "value": 4 }, { "date": "2026-10-05T20:00:00Z", "value": 6 } ]
    } ],
    "timespan_served": "24h",
    "window_capped": false
  },
  "meta": { "endpoint": "/api/v1/gdelt/timeline", "source": "gdelt" }
}

timelinevol is the count of stored articles that matched the query in each 15-minute file bucket. A timespan longer than 24 hours is accepted and returned with window_capped: true and timespan_served: "24h". A missing file is 503 blob_not_ready, not an empty series.

4. Add the tone series

{
  "data": {
    "timeline": [ {
      "series": "timelinetone",
      "data": [ { "date": "2026-10-05T19:45:00Z", "value": -0.4 }, { "date": "2026-10-05T20:00:00Z", "value": 0.2 } ]
    } ]
  },
  "meta": { "endpoint": "/api/v1/gdelt/timeline", "source": "gdelt" }
}

Same endpoint, mode=timelinetone: the mean stored document tone in each bucket. Negative means adverse coverage and positive means favorable. A bucket with no tone value is left out of this series. The counts from step 3 stay on their own series.

5. Drill into the articles

{
  "data": {
    "articles": [
      {
        "title": "Grid operator warns of a tight evening",
        "seendate": "20261005T190000Z",
        "domain": "example.com",
        "language": "en",
        "sourcecountry": null,
        "tone": -1.4
      }
    ],
    "count": 3,
    "timespan_served": "24h",
    "window_capped": false
  },
  "meta": { "endpoint": "/api/v1/gdelt/articles", "source": "gdelt" }
}

These cards come from the English file Sugra stores: title, source, time, link and tone. sourcecountry is null because the file does not name the outlet's country. country filters the country named in the article. Omit lang, or pass en, eng, or english, for the English file. lang of por, spa, deu, fra, ita, rus, zho, jpn, kor, ara, hin, fas, tur, ind or vie reads that stored translation file. The two-letter codes pt, es, de, fr, it, ru, zh, ja, ko, ar, hi, fa, tr, id and vi map onto those stored codes. Any other code returns an empty set with coverage: language_not_stored. A broad one-word query is noisy. Only uppercase OR starts a new group. The file has no full article body.

6. Add the ticker panel

{
  "data": {
    "symbol": "MSFT",
    "company_name": "MICROSOFT CORP",
    "sentiment": {
      "latest_tone": 0.0799,
      "average_tone": 0.1595,
      "timeline": [ { "date": "20260706T000000Z", "value": 0.5979 }, { "date": "20260719T000000Z", "value": 0.0799 } ]
    },
    "attention": { "timeline": [], "first_party_article_count": 1 }
  },
  "meta": { "endpoint": "/api/v1/equities/MSFT/news-sentiment", "source": "sugra_news" }
}

(The sample keeps the response shape. query, former_names, recent_headlines and note are omitted here.) The ticker is entity-linked through the SEC registrant name plus former names. Tone is the mean of stored document tone for articles whose organization equals that name. Attention counts those articles per file bucket. The served window is 24 hours even when timespan is 2weeks, and window_capped says so. An empty timeline with unavailable_reason: null means the search ran and nothing matched. A null tone with a reason means the file could not be read. Do not draw a null tone as neutral. This is editorial news-flow sentiment, a screening signal rather than investment advice.

Going further

Sugra News direction - the full endpoint map behind this recipe: curated feeds, GDELT media analytics, and Wikipedia attention series for a reader-demand panel.

Rate limits and errors - budget your refresh cadence against the daily quota and handle 429 / 503 retries cleanly.

Sugra Finance direction - price and fundamentals endpoints to set market context beside the ticker panel.

Build a news signal dashboard

What you build#

1. Pull the headline board#

2. Scan the theme radar#

3. Chart coverage volume for your theme#

4. Add the tone series#

5. Drill into the articles#

6. Add the ticker panel#

Going further#