Documentation Index
Fetch the complete documentation index at: https://docs.wokelo.ai/llms.txt
Use this file to discover all available pages before exploring further.
1. Overview
The Industry News Monitoring API fetches the latest news articles for a given industry topic or sector, enriched with AI-generated summaries, geographic signals, and source metadata. Results are returned synchronously in the HTTP response — no job polling required. This is a synchronous GET API — you pass a free-text topic and optional filters as URL parameters, and receive a paginated array of enriched news articles immediately. Unlike the Company News Monitoring API, which fetches news anchored to a specific company, this API accepts any natural-language topic — a sector, a technology, a theme, a geopolitical event, or a cross-company trend. The breadth of coverage is defined by thetopic string and optionally narrowed by geo and date range.
Each article in the response includes:
- AI summary — a concise, machine-generated synopsis of the article’s key facts and implications
- Geographic tags — ISO 3166-1 alpha-3 country codes identifying which geographies are relevant to the article
- Publisher and source metadata — article URL, title, publication datetime, and source attribution
- Article identifier — a stable numeric
idfor deduplication across paginated requests
- Sector monitoring for investment research — Track news on themes like “warehouse automation”, “GLP-1 drugs”, or “offshore wind” across a rolling 30-day window without being tied to a specific company
- Geopolitical and macro intelligence — Monitor topics like “US-China trade war”, “European energy security”, or “emerging market debt” filtered to specific regions using the
geoparameter - LP and fund reporting — Aggregate industry-level developments across portfolio sectors for quarterly reporting or LP briefings
- Market entry and expansion research — Filter a topic to a specific country or region (e.g., “electric vehicle charging” in
IND) to surface market-specific activity - Thematic investment screening — Use the
ai_summaryfield to efficiently triage large volumes of sector news before reading full articles - Regulatory and policy tracking — Monitor topics like “data privacy regulation”, “carbon border adjustment”, or “AI legislation” with geographic narrowing to track jurisdiction-specific developments
This API is synchronous. Results are returned directly in the HTTP response — no job submission or polling required. See How Sync APIs work.
2. Quick Start
Step 1 — Make a simple request3. Authentication
All requests must include a Bearer token in theAuthorization HTTP header. No other authentication method is supported.
4. Request Reference
Endpoint| Parameter | Type | Required | Description |
|---|---|---|---|
topic | string | Required | Free-text description of the industry, sector, or theme to monitor. The query engine matches articles by relevance to this string. Specific, descriptive topics yield tighter results than broad single-word queries. Examples: "Warehouse Automation", "GLP-1 obesity drugs", "Real Estate Development", "US-China trade tariffs". |
start_date | string | Optional | Start of the date window for articles (YYYY-MM-DD). Inclusive. |
end_date | string | Optional | End of the date window for articles (YYYY-MM-DD). Inclusive. |
limit | integer | Optional | Maximum number of articles to return. Default 100, max 1000. |
offset | integer | Optional | Number of articles to skip before returning results. Default 0. Use with limit for pagination. |
blacklisted | string | Optional | Comma-separated list of publisher domains to exclude. Include the full domain starting with https:// (e.g. "https://www.prnewswire.com/"). |
geo | string | Optional | Comma-separated list of ISO 3166-1 alpha-3 country codes to filter articles by geography (e.g. "USA", "GBR,DEU,FRA", "ARE"). Returns only articles tagged with at least one of the specified countries. |
5. Response
Response structure
| Field | Type | Description |
|---|---|---|
status | string | "success" when the request was processed successfully. |
data | array | Array of enriched article objects. |
count | integer | Number of articles returned in this response batch. |
total | integer | Total number of matching articles available across all pages (before limit and offset are applied). |
limit | integer | The limit value applied to this response. |
offset | integer | The offset value applied to this response. |
Article object fields
Each object in thedata array contains the following fields:
Article identity
| Field | Type | Description |
|---|---|---|
id | integer | Stable numeric identifier for this article in Wokelo’s index. Use for deduplication when paginating or comparing runs across different date windows. |
url | string | Canonical URL of the original article. |
title | string | Headline of the article as published. |
published_date | string | Publication datetime in YYYY-MM-DD HH:MM:SS format (UTC). |
| Field | Type | Description |
|---|---|---|
ai_summary | string | AI-generated 2–4 sentence summary of the article’s key facts and implications for the topic. |
| Field | Type | Description |
|---|---|---|
source | string | Wokelo’s internal signal source designation. Either "Wokelo" (directly indexed) or "Google" (sourced via search). |
geo | string[] | Array of ISO 3166-1 alpha-3 country codes identifying the geographies covered or referenced in the article (e.g. ["USA", "CHN"]). Empty array when no country was detected. |
The Industry News Monitoring API returns a leaner article object than the Company News Monitoring API. Fields like
sentiment, primary_tag, secondary_tags, newsworthiness_impact, company_names, publisher, author, and scraped_text are not included in industry news responses. Use ai_summary for content triage and url to fetch the full article when needed.Notes on the geo field
The geo array reflects countries that are mentioned or relevant in the article — not necessarily where the article was published. A single article covering US-China trade policy may have ["USA", "CHN"]. An article about a regional development project may have only one code.
- Multi-country articles — articles covering diplomatic events, bilateral trade deals, or multinational company activity commonly list three or more country codes
- Empty geo — some articles have an empty
geoarray when country detection was inconclusive; these are still returned unless you have filtered bygeo geofilter behaviour — when you passgeo=IND,SGP, the API returns articles tagged withINDorSGP, not exclusively articles tagged with both
Pagination notes
Industry topic queries can return very large result sets. For broad topics like “trade war” or “artificial intelligence” thetotal count can exceed several thousand. Always check total against count and paginate using offset until all records have been retrieved. The recommended approach is to stop when count returns 0 or len(all_articles) >= total.
6. Examples
Monitoring a sector in a specific region
Fetch all real estate development news in the UAE for a specific month — useful for generating a sector brief or LP update.Multi-region sector sweep
Monitor a technology sector across several markets simultaneously by passing multiplegeo codes. Useful for tracking a theme across different regulatory or market environments.
Rolling 30-day monitoring pipeline
Set up a recurring pull that always covers the most recent 30 days, suitable for a weekly digest or automated feed.Paginating through large topic result sets
For broad topics,total can significantly exceed limit. Paginate using offset until all records are retrieved.
Comparing sector activity across geographies
Pull the same topic for multiple regions and compare article volume and recency — useful for understanding where in the world a theme is most actively developing.JavaScript / Node.js
7. Error Handling
The API uses standard HTTP status codes. All error responses include a JSON body with adetail or message field.
| Status | Meaning | Cause & Resolution |
|---|---|---|
200 OK | Success | Articles returned successfully. |
400 Bad Request | Invalid parameters | A required parameter is missing or a value is invalid — e.g. missing topic, malformed start_date, or invalid ISO country code in geo. Check the detail field. |
401 Unauthorized | Auth failed | The Authorization header is missing, malformed, or contains an invalid token. Verify your key in Settings → API Keys. |
403 Forbidden | Insufficient access | Your plan does not include access to this endpoint. Contact support@wokelo.ai to review your plan. |
429 Too Many Requests | Rate limit exceeded | Implement exponential back-off. The response includes a Retry-After header. |
500 Internal Server Error | Server error | Retry after a brief delay. If the issue persists, contact support@wokelo.ai. |
8. Best Practices
Write a specific, descriptivetopic — this is the single highest-impact parameter
The topic field drives the entire article retrieval. A vague topic like "technology" returns an enormous, noisy result set. A specific topic describing the exact theme, technology, or event produces a tight, actionable feed:
geo to narrow scope, not to replace topic specificity
The geo filter restricts articles to those tagged with specific countries, but a vague topic with aggressive geo filtering can still return a noisy result set. Lead with a specific topic and use geo to reduce geographic noise:
geo parameter requires 3-letter codes ("USA", "GBR", "DEU") not the 2-letter equivalents ("US", "GB", "DE"). Passing alpha-2 codes will not filter correctly and may return unexpected results.
start_date and end_date, the query returns articles across the full Wokelo index, which for active topics can mean thousands of articles. Always bound queries to the window you intend to process — 30-day windows work well for regular monitoring runs, 7-day windows for weekly digests:
id for deduplication across runs
The id field is a stable identifier for each article in Wokelo’s index. When running the same topic query on an overlapping date range (e.g. daily refreshes), deduplicate by id to avoid processing the same article twice:
prnewswire.com, businesswire.com, globenewswire.com) publish high volumes of company-issued releases that can dominate topic results. Blacklisting these domains surfaces editorial journalism and independent analysis:
ai_summary for fast triage before fetching full articles
The ai_summary field provides a reliable 2–4 sentence synopsis that is sufficient for most triage decisions. Read full articles via the url field only for items that pass your relevance threshold, rather than attempting to scrape all articles in a result set.
Understand the difference from Company News Monitoring
The Industry API response schema is intentionally leaner — it does not include sentiment, primary_tag, secondary_tags, newsworthiness_impact, company_names, publisher, author, or scraped_text. If you need these enrichment fields, or if your monitoring is anchored to specific companies, use the Company News Monitoring API instead. The two APIs are complementary: industry monitoring for broad thematic coverage, company monitoring for entity-level depth.
9. Related APIs
Company News Monitoring
Fetch company-specific news with richer enrichment — sentiment, event categories, company mentions, and full article text.
Newsfeed
Retrieve a curated, cross-company newsfeed based on a topic, theme, or portfolio watchlist.
Industry Deep Intelligence
Generate a comprehensive AI research report on any industry — market size, competitive dynamics, key players, and outlook.
Industry Research
Run a structured, async AI research workflow on an industry topic and receive a formatted output report.
Market Map
Discover and map all companies competing in a specific market or product category.
Supporting APIs
Company Search, Request Status, and other utilities used alongside monitoring workflows.