# mediastack

> Search the news with mediastack: live and historical articles from 7,500+ sources across 50+ countries in 13 languages, plus the publisher directory behind them. Search by keyword, publisher, section, country, language or date range, follow a subject on a rolling window for a scheduled workflow, read the archive of a past day, count how much is being written, see which publishers are covering it, and compare topics or countries side by side.

App · News · 10 actions. Web page: https://docs.lodol.com/docs/integrations/mediastack

## Actions

### Compare countries

Take one subject and see where in the world it is being written about: two to five countries over the same period, ranked, each with its share of the combined coverage and its newest headline. Use it to tell a local story from an international one, or to find the market a launch actually landed in.

**Inputs**

- Search for (`keywords`, text, required): What to look for. Write a phrase plainly (climate summit), separate several with commas, and prefix one with a minus sign to leave it out (tennis,-doubles).
- Countries (`countries`, list, required): The countries to compare: between 2 and 5. Each one is searched separately and costs one request. One or more of: `ae` (United Arab Emirates), `ar` (Argentina), `at` (Austria), `au` (Australia), `be` (Belgium), `bg` (Bulgaria), `br` (Brazil), `ca` (Canada), `ch` (Switzerland), `cn` (China), and 42 more.
- How far back (`window`, text): Optional. How far back to look, counted from the day the step runs, so a workflow on a schedule keeps looking at fresh news instead of a fixed date. Leave it empty to search the live feed with no date filter, which is what the Free plan can reach: filtering by date is a Standard-plan feature. One of: `today`, `thisweek` (This week), `thismonth` (This month), `last7days` (Last 7 days), `last30days` (Last 30 days), `last3months` (Last 3 months), `yeartodate` (Year to date).
- Languages (`languages`, list): Optional. Only keep articles written in these languages. Choose none to take them all. One or more of: `ar` (Arabic), `de` (German), `en` (English), `es` (Spanish), `fr` (French), `he` (Hebrew), `it` (Italian), `nl` (Dutch), `no` (Norwegian), `pt` (Portuguese), and 3 more.

**Outputs**

- `countries` (list): The countries, most coverage first
- `country_count` (number): How many countries were compared
- `from_date` (text): The first day covered (YYYY-MM-DD), empty when no date filter
- `keywords` (text): The subject that was compared
- `languages` (text): The language filter that was applied
- `leading_country` (text): The country code with the most coverage
- `leading_country_label` (text): That country's name
- `requests_used` (number): How many mediastack requests this step spent: one per country
- `to_date` (text): The last day covered (YYYY-MM-DD), empty when no date filter
- `total_results` (number): The combined article count across the countries
- `window` (text): The window that was asked for
- `window_label` (text): That window in words

**Example output**

```json
{
  "countries": [
    {
      "country": "us",
      "country_label": "United States",
      "newest_published_at": "2026-08-19T09:12:00+00:00",
      "newest_source": "Reuters",
      "newest_title": "Chip makers post record quarter as AI demand holds",
      "newest_url": "https://www.reuters.com/technology/chip-makers-record-quarter",
      "share_percent": 72.9,
      "total_results": 62
    },
    {
      "country": "au",
      "country_label": "Australia",
      "newest_published_at": "2026-08-19T07:45:00+00:00",
      "newest_source": "ABC AU",
      "newest_title": "Regulators open review of cloud computing contracts",
      "newest_url": "https://www.abc.net.au/news/cloud-contracts-review",
      "share_percent": 27.1,
      "total_results": 23
    }
  ],
  "country_count": 2,
  "from_date": "2026-08-19",
  "keywords": "semiconductors",
  "languages": "en",
  "leading_country": "us",
  "leading_country_label": "United States",
  "requests_used": 2,
  "to_date": "2026-08-19",
  "total_results": 85,
  "window": "today",
  "window_label": "Today"
}
```

### Compare topics

Compare how much is being written about several subjects (two to five of them) over the same period, ranked, each with its share of the combined coverage and its newest headline. Use it for share of voice against competitors, or to see which of your product lines the press is picking up.

**Inputs**

- Topics (`topics`, list, required): The subjects to compare: between 2 and 5. Each one is searched separately and costs one request.
- How far back (`window`, text): Optional. How far back to look, counted from the day the step runs, so a workflow on a schedule keeps looking at fresh news instead of a fixed date. Leave it empty to search the live feed with no date filter, which is what the Free plan can reach: filtering by date is a Standard-plan feature. One of: `today`, `thisweek` (This week), `thismonth` (This month), `last7days` (Last 7 days), `last30days` (Last 30 days), `last3months` (Last 3 months), `yeartodate` (Year to date).
- Countries (`countries`, list): Optional. Only keep articles from publishers in these countries. Choose none to take the whole world. One or more of: `ae` (United Arab Emirates), `ar` (Argentina), `at` (Austria), `au` (Australia), `be` (Belgium), `bg` (Bulgaria), `br` (Brazil), `ca` (Canada), `ch` (Switzerland), `cn` (China), and 42 more.
- Languages (`languages`, list): Optional. Only keep articles written in these languages. Choose none to take them all. One or more of: `ar` (Arabic), `de` (German), `en` (English), `es` (Spanish), `fr` (French), `he` (Hebrew), `it` (Italian), `nl` (Dutch), `no` (Norwegian), `pt` (Portuguese), and 3 more.

**Outputs**

- `countries` (text): The country filter that was applied
- `from_date` (text): The first day covered (YYYY-MM-DD), empty when no date filter
- `languages` (text): The language filter that was applied
- `leading_topic` (text): The most covered topic
- `requests_used` (number): How many mediastack requests this step spent: one per topic
- `to_date` (text): The last day covered (YYYY-MM-DD), empty when no date filter
- `topic_count` (number): How many topics were compared
- `topics` (list): The topics, most covered first
- `total_results` (number): The combined article count across the topics
- `window` (text): The window that was asked for
- `window_label` (text): That window in words

**Example output**

```json
{
  "countries": null,
  "from_date": "2026-08-19",
  "languages": "en",
  "leading_topic": "semiconductors",
  "requests_used": 2,
  "to_date": "2026-08-19",
  "topic_count": 2,
  "topics": [
    {
      "newest_published_at": "2026-08-19T09:12:00+00:00",
      "newest_source": "Reuters",
      "newest_title": "Chip makers post record quarter as AI demand holds",
      "newest_url": "https://www.reuters.com/technology/chip-makers-record-quarter",
      "share_percent": 62.0,
      "topic": "semiconductors",
      "total_results": 62
    },
    {
      "newest_published_at": "2026-08-19T06:02:00+00:00",
      "newest_source": "ABC AU",
      "newest_title": "Lab reports longer qubit coherence times",
      "newest_url": "https://www.abc.net.au/news/qubit-coherence",
      "share_percent": 38.0,
      "topic": "quantum computing",
      "total_results": 38
    }
  ],
  "total_results": 100,
  "window": "today",
  "window_label": "Today"
}
```

### Count news

Count how many articles match, and return the newest one. It costs a single request whether the answer is three articles or thirty thousand, so it is the cheap check to branch a workflow on: alert someone when coverage of your brand spikes, or skip the rest of the run when there is nothing new.

**Inputs**

- Search for (`keywords`, text): What to look for. Write a phrase plainly (climate summit), separate several with commas, and prefix one with a minus sign to leave it out (tennis,-doubles). Optional here: leave it empty to take everything that matches the other filters.
- How far back (`window`, text): Optional. How far back to look, counted from the day the step runs, so a workflow on a schedule keeps looking at fresh news instead of a fixed date. Leave it empty to search the live feed with no date filter, which is what the Free plan can reach: filtering by date is a Standard-plan feature. One of: `today`, `thisweek` (This week), `thismonth` (This month), `last7days` (Last 7 days), `last30days` (Last 30 days), `last3months` (Last 3 months), `yeartodate` (Year to date).
- Sections (`categories`, list): Optional. Only keep articles filed under these sections of the news. Choose none to take them all. One or more of: `general`, `business`, `entertainment`, `health`, `politics`, `science`, `sports`, `technology`.
- Countries (`countries`, list): Optional. Only keep articles from publishers in these countries. Choose none to take the whole world. One or more of: `ae` (United Arab Emirates), `ar` (Argentina), `at` (Austria), `au` (Australia), `be` (Belgium), `bg` (Bulgaria), `br` (Brazil), `ca` (Canada), `ch` (Switzerland), `cn` (China), and 42 more.
- Languages (`languages`, list): Optional. Only keep articles written in these languages. Choose none to take them all. One or more of: `ar` (Arabic), `de` (German), `en` (English), `es` (Spanish), `fr` (French), `he` (Hebrew), `it` (Italian), `nl` (Dutch), `no` (Norwegian), `pt` (Portuguese), and 3 more.
- Publishers (`sources`, list): Optional. Only keep articles from these publishers, named by their mediastack id (cnn, abc-au). Use the Search publishers action to find an id. Prefix one with a minus sign to leave that publisher out instead.

**Outputs**

- `categories` (text): The section filter that was applied
- `countries` (text): The country filter that was applied
- `from_date` (text): The first day covered (YYYY-MM-DD), empty when no date filter
- `has_articles` (true/false): True when at least one article matches
- `keywords` (text): The search that ran
- `languages` (text): The language filter that was applied
- `newest_article` (object): The most recent matching article
- `sources` (text): The publisher filter that was applied
- `to_date` (text): The last day covered (YYYY-MM-DD), empty when no date filter
- `total_results` (number): How many articles match
- `window` (text): The window that was asked for
- `window_label` (text): That window in words

**Example output**

```json
{
  "categories": "business",
  "countries": "us",
  "from_date": "2026-08-19",
  "has_articles": true,
  "keywords": "semiconductors",
  "languages": "en",
  "newest_article": {
    "author": "Jane Okafor",
    "category": "business",
    "category_label": "Business",
    "country": "us",
    "country_label": "United States",
    "description": "Revenue across the sector rose 18% year on year, with data-centre orders leading the way.",
    "domain": "reuters.com",
    "has_image": true,
    "image": "https://www.reuters.com/resizer/chips.jpg",
    "language": "en",
    "language_label": "English",
    "published_at": "2026-08-19T09:12:00+00:00",
    "source": "Reuters",
    "title": "Chip makers post record quarter as AI demand holds",
    "url": "https://www.reuters.com/technology/chip-makers-record-quarter"
  },
  "sources": null,
  "to_date": "2026-08-19",
  "total_results": 62,
  "window": "today",
  "window_label": "Today"
}
```

### Get historical news

Read the archive: the news of one past day, or of a range of days, with the same filters as a live search. Use it to reconstruct how a story broke, to pull the coverage around a launch date, or to build a dataset from a period that has already passed. Reaching back past today needs the Standard plan or higher.

**Inputs**

- Day to read (`from_date`, date, required): The day to read the news for, or the first day, if you want a range.
- Up to and including (`to_date`, date): Optional. The last day of the range. Leave it empty to read a single day.
- Search for (`keywords`, text): What to look for. Write a phrase plainly (climate summit), separate several with commas, and prefix one with a minus sign to leave it out (tennis,-doubles). Optional here: leave it empty to take everything that matches the other filters.
- Publishers (`sources`, list): Optional. Only keep articles from these publishers, named by their mediastack id (cnn, abc-au). Use the Search publishers action to find an id. Prefix one with a minus sign to leave that publisher out instead.
- Sections (`categories`, list): Optional. Only keep articles filed under these sections of the news. Choose none to take them all. One or more of: `general`, `business`, `entertainment`, `health`, `politics`, `science`, `sports`, `technology`.
- Countries (`countries`, list): Optional. Only keep articles from publishers in these countries. Choose none to take the whole world. One or more of: `ae` (United Arab Emirates), `ar` (Argentina), `at` (Austria), `au` (Australia), `be` (Belgium), `bg` (Bulgaria), `br` (Brazil), `ca` (Canada), `ch` (Switzerland), `cn` (China), and 42 more.
- Languages (`languages`, list): Optional. Only keep articles written in these languages. Choose none to take them all. One or more of: `ar` (Arabic), `de` (German), `en` (English), `es` (Spanish), `fr` (French), `he` (Hebrew), `it` (Italian), `nl` (Dutch), `no` (Norwegian), `pt` (Portuguese), and 3 more.
- Order results by (`sort`, text): How to order the articles. Newest first is the default; most popular first puts the stories getting the most attention at the top. One of: `published_desc` (Newest first), `published_asc` (Oldest first), `popularity` (Most popular first). Default: `published_desc`.
- Results per page (`limit`, number): How many articles to return, from 1 to 100. Defaults to 25. From 1 to 100. Default: `25`.
- Skip (`offset`, number): How many results to skip before the ones you want. Leave it at 0 for the first page; to walk through a large set, use the 'next_offset' the previous run returned. Skip plus results per page cannot go past 10,000. From 0 to 10000. Default: `0`.

**Outputs**

- `article_count` (number): How many articles this page returned
- `articles` (list): The articles on this page
- `categories` (text): The section filter that was applied
- `countries` (text): The country filter that was applied
- `from_date` (text): The first day covered (YYYY-MM-DD), empty when no date filter
- `has_more` (true/false): True when another page of matches is available
- `keywords` (text): The search that ran
- `languages` (text): The language filter that was applied
- `limit` (number): How many were asked for
- `next_offset` (number): The Skip value for the next page, or empty when there is none
- `offset` (number): How many were skipped
- `sort` (text): The ordering that was applied
- `sources` (text): The publisher filter that was applied
- `to_date` (text): The last day covered (YYYY-MM-DD), empty when no date filter
- `total_results` (number): How many articles match in total, across all pages
- `without_image_count` (number): How many articles were left out because they had no image (0 unless 'Only articles with an image' is on)

**Example output**

```json
{
  "article_count": 2,
  "articles": [
    {
      "author": "Jane Okafor",
      "category": "business",
      "category_label": "Business",
      "country": "us",
      "country_label": "United States",
      "description": "Revenue across the sector rose 18% year on year, with data-centre orders leading the way.",
      "domain": "reuters.com",
      "has_image": true,
      "image": "https://www.reuters.com/resizer/chips.jpg",
      "language": "en",
      "language_label": "English",
      "published_at": "2026-08-19T09:12:00+00:00",
      "source": "Reuters",
      "title": "Chip makers post record quarter as AI demand holds",
      "url": "https://www.reuters.com/technology/chip-makers-record-quarter"
    },
    {
      "author": "Tom Reilly",
      "category": "technology",
      "category_label": "Technology",
      "country": "au",
      "country_label": "Australia",
      "description": "The inquiry will look at exit fees and data transfer costs.",
      "domain": "abc.net.au",
      "has_image": true,
      "image": "https://live-production.wcms.abc-cdn.net.au/cloud.jpg",
      "language": "en",
      "language_label": "English",
      "published_at": "2026-08-19T07:45:00+00:00",
      "source": "ABC AU",
      "title": "Regulators open review of cloud computing contracts",
      "url": "https://www.abc.net.au/news/cloud-contracts-review"
    }
  ],
  "categories": "business",
  "countries": "us",
  "from_date": "2026-07-17",
  "has_more": true,
  "keywords": "semiconductors",
  "languages": "en",
  "limit": 25,
  "next_offset": 2,
  "offset": 0,
  "sort": "published_asc",
  "sources": "reuters",
  "to_date": "2026-07-17",
  "total_results": 293,
  "without_image_count": 0
}
```

### Get news by publisher

Everything chosen publishers are running: one masthead, or a shortlist of the trade titles and local papers that matter to you. Name them by the ids Search publishers returns, and prefix one with a minus sign to leave it out of the set instead.

**Inputs**

- Publishers (`sources`, list, required): The publishers to read, named by their mediastack id (cnn, abc-au). Use the Search publishers action to find an id. Prefix one with a minus sign to leave that publisher out of the set.
- Search for (`keywords`, text): What to look for. Write a phrase plainly (climate summit), separate several with commas, and prefix one with a minus sign to leave it out (tennis,-doubles). Optional here: leave it empty to take everything that matches the other filters.
- Languages (`languages`, list): Optional. Only keep articles written in these languages. Choose none to take them all. One or more of: `ar` (Arabic), `de` (German), `en` (English), `es` (Spanish), `fr` (French), `he` (Hebrew), `it` (Italian), `nl` (Dutch), `no` (Norwegian), `pt` (Portuguese), and 3 more.
- How far back (`window`, text): Optional. How far back to look, counted from the day the step runs, so a workflow on a schedule keeps looking at fresh news instead of a fixed date. Leave it empty to search the live feed with no date filter, which is what the Free plan can reach: filtering by date is a Standard-plan feature. One of: `today`, `thisweek` (This week), `thismonth` (This month), `last7days` (Last 7 days), `last30days` (Last 30 days), `last3months` (Last 3 months), `yeartodate` (Year to date).
- Order results by (`sort`, text): How to order the articles. Newest first is the default; most popular first puts the stories getting the most attention at the top. One of: `published_desc` (Newest first), `published_asc` (Oldest first), `popularity` (Most popular first). Default: `published_desc`.
- Results per page (`limit`, number): How many articles to return, from 1 to 100. Defaults to 25. From 1 to 100. Default: `25`.
- Skip (`offset`, number): How many results to skip before the ones you want. Leave it at 0 for the first page; to walk through a large set, use the 'next_offset' the previous run returned. Skip plus results per page cannot go past 10,000. From 0 to 10000. Default: `0`.

**Outputs**

- `article_count` (number): How many articles this page returned
- `articles` (list): The articles on this page
- `from_date` (text): The first day covered (YYYY-MM-DD), empty when no date filter
- `has_more` (true/false): True when another page of matches is available
- `keywords` (text): The keyword filter that was applied
- `languages` (text): The language filter that was applied
- `limit` (number): How many were asked for
- `next_offset` (number): The Skip value for the next page, or empty when there is none
- `offset` (number): How many were skipped
- `sort` (text): The ordering that was applied
- `source_count` (number): How many publishers were included
- `sources` (text): The publisher ids that were asked for
- `to_date` (text): The last day covered (YYYY-MM-DD), empty when no date filter
- `total_results` (number): How many articles match in total, across all pages
- `window` (text): The window that was asked for
- `window_label` (text): That window in words
- `without_image_count` (number): How many articles were left out because they had no image (0 unless 'Only articles with an image' is on)

**Example output**

```json
{
  "article_count": 2,
  "articles": [
    {
      "author": "Jane Okafor",
      "category": "business",
      "category_label": "Business",
      "country": "us",
      "country_label": "United States",
      "description": "Revenue across the sector rose 18% year on year, with data-centre orders leading the way.",
      "domain": "reuters.com",
      "has_image": true,
      "image": "https://www.reuters.com/resizer/chips.jpg",
      "language": "en",
      "language_label": "English",
      "published_at": "2026-08-19T09:12:00+00:00",
      "source": "Reuters",
      "title": "Chip makers post record quarter as AI demand holds",
      "url": "https://www.reuters.com/technology/chip-makers-record-quarter"
    },
    {
      "author": "Tom Reilly",
      "category": "technology",
      "category_label": "Technology",
      "country": "au",
      "country_label": "Australia",
      "description": "The inquiry will look at exit fees and data transfer costs.",
      "domain": "abc.net.au",
      "has_image": true,
      "image": "https://live-production.wcms.abc-cdn.net.au/cloud.jpg",
      "language": "en",
      "language_label": "English",
      "published_at": "2026-08-19T07:45:00+00:00",
      "source": "ABC AU",
      "title": "Regulators open review of cloud computing contracts",
      "url": "https://www.abc.net.au/news/cloud-contracts-review"
    }
  ],
  "from_date": null,
  "has_more": true,
  "keywords": null,
  "languages": "en",
  "limit": 25,
  "next_offset": 2,
  "offset": 0,
  "sort": "published_desc",
  "source_count": 2,
  "sources": "cnn,abc-au",
  "to_date": null,
  "total_results": 293,
  "window": null,
  "window_label": null,
  "without_image_count": 0
}
```

### Get top headlines

The stories getting the most attention rather than the most recent ones: mediastack's popularity ranking, narrowed to a country, a section of the news, a language or a keyword. This is the front page; Search news is for going after something in particular.

**Inputs**

- Sections (`categories`, list): Optional. Only keep articles filed under these sections of the news. Choose none to take them all. One or more of: `general`, `business`, `entertainment`, `health`, `politics`, `science`, `sports`, `technology`.
- Countries (`countries`, list): Optional. Only keep articles from publishers in these countries. Choose none to take the whole world. One or more of: `ae` (United Arab Emirates), `ar` (Argentina), `at` (Austria), `au` (Australia), `be` (Belgium), `bg` (Bulgaria), `br` (Brazil), `ca` (Canada), `ch` (Switzerland), `cn` (China), and 42 more.
- Languages (`languages`, list): Optional. Only keep articles written in these languages. Choose none to take them all. One or more of: `ar` (Arabic), `de` (German), `en` (English), `es` (Spanish), `fr` (French), `he` (Hebrew), `it` (Italian), `nl` (Dutch), `no` (Norwegian), `pt` (Portuguese), and 3 more.
- Search for (`keywords`, text): What to look for. Write a phrase plainly (climate summit), separate several with commas, and prefix one with a minus sign to leave it out (tennis,-doubles). Optional here: leave it empty to take everything that matches the other filters.
- How far back (`window`, text): Optional. How far back to look, counted from the day the step runs, so a workflow on a schedule keeps looking at fresh news instead of a fixed date. Leave it empty to search the live feed with no date filter, which is what the Free plan can reach: filtering by date is a Standard-plan feature. One of: `today`, `thisweek` (This week), `thismonth` (This month), `last7days` (Last 7 days), `last30days` (Last 30 days), `last3months` (Last 3 months), `yeartodate` (Year to date).
- Results per page (`limit`, number): How many articles to return, from 1 to 100. Defaults to 25. From 1 to 100. Default: `25`.

**Outputs**

- `article_count` (number): How many articles this page returned
- `articles` (list): The articles on this page
- `categories` (text): The section filter that was applied
- `categories_label` (text): The section filter in words
- `countries` (text): The country filter that was applied
- `countries_label` (text): The country filter in words
- `from_date` (text): The first day covered (YYYY-MM-DD), empty when no date filter
- `has_more` (true/false): True when another page of matches is available
- `keywords` (text): The keyword filter that was applied
- `languages` (text): The language filter that was applied
- `limit` (number): How many were asked for
- `next_offset` (number): The Skip value for the next page, or empty when there is none
- `offset` (number): How many were skipped
- `sort` (text): The ordering that was applied
- `to_date` (text): The last day covered (YYYY-MM-DD), empty when no date filter
- `total_results` (number): How many articles match in total, across all pages
- `window` (text): The window that was asked for
- `window_label` (text): That window in words
- `without_image_count` (number): How many articles were left out because they had no image (0 unless 'Only articles with an image' is on)

**Example output**

```json
{
  "article_count": 2,
  "articles": [
    {
      "author": "Jane Okafor",
      "category": "business",
      "category_label": "Business",
      "country": "us",
      "country_label": "United States",
      "description": "Revenue across the sector rose 18% year on year, with data-centre orders leading the way.",
      "domain": "reuters.com",
      "has_image": true,
      "image": "https://www.reuters.com/resizer/chips.jpg",
      "language": "en",
      "language_label": "English",
      "published_at": "2026-08-19T09:12:00+00:00",
      "source": "Reuters",
      "title": "Chip makers post record quarter as AI demand holds",
      "url": "https://www.reuters.com/technology/chip-makers-record-quarter"
    },
    {
      "author": "Tom Reilly",
      "category": "technology",
      "category_label": "Technology",
      "country": "au",
      "country_label": "Australia",
      "description": "The inquiry will look at exit fees and data transfer costs.",
      "domain": "abc.net.au",
      "has_image": true,
      "image": "https://live-production.wcms.abc-cdn.net.au/cloud.jpg",
      "language": "en",
      "language_label": "English",
      "published_at": "2026-08-19T07:45:00+00:00",
      "source": "ABC AU",
      "title": "Regulators open review of cloud computing contracts",
      "url": "https://www.abc.net.au/news/cloud-contracts-review"
    }
  ],
  "categories": "business",
  "categories_label": "Business",
  "countries": "us",
  "countries_label": "United States",
  "from_date": "2026-08-19",
  "has_more": true,
  "keywords": null,
  "languages": "en",
  "limit": 25,
  "next_offset": 2,
  "offset": 0,
  "sort": "popularity",
  "to_date": "2026-08-19",
  "total_results": 293,
  "window": "today",
  "window_label": "Today",
  "without_image_count": 0
}
```

### Get top publishers for a topic

Find out who is covering a subject, not just what has been written: the publishers writing about it most, ranked, each with its share of the coverage and its most recent article. Use it to build a press list, to see where a story is landing, or to pick the publishers to filter a later search down to.

**Inputs**

- Search for (`keywords`, text, required): What to look for. Write a phrase plainly (climate summit), separate several with commas, and prefix one with a minus sign to leave it out (tennis,-doubles).
- How far back (`window`, text): Optional. How far back to look, counted from the day the step runs, so a workflow on a schedule keeps looking at fresh news instead of a fixed date. Leave it empty to search the live feed with no date filter, which is what the Free plan can reach: filtering by date is a Standard-plan feature. One of: `today`, `thisweek` (This week), `thismonth` (This month), `last7days` (Last 7 days), `last30days` (Last 30 days), `last3months` (Last 3 months), `yeartodate` (Year to date).
- Countries (`countries`, list): Optional. Only keep articles from publishers in these countries. Choose none to take the whole world. One or more of: `ae` (United Arab Emirates), `ar` (Argentina), `at` (Austria), `au` (Australia), `be` (Belgium), `bg` (Bulgaria), `br` (Brazil), `ca` (Canada), `ch` (Switzerland), `cn` (China), and 42 more.
- Languages (`languages`, list): Optional. Only keep articles written in these languages. Choose none to take them all. One or more of: `ar` (Arabic), `de` (German), `en` (English), `es` (Spanish), `fr` (French), `he` (Hebrew), `it` (Italian), `nl` (Dutch), `no` (Norwegian), `pt` (Portuguese), and 3 more.
- How many publishers (`max_sources`, number): How many publishers to return, most active first, from 1 to 100. From 1 to 100. Default: `10`.

**Outputs**

- `countries` (text): The country filter that was applied
- `from_date` (text): The first day covered (YYYY-MM-DD), empty when no date filter
- `keywords` (text): The subject that ran
- `languages` (text): The language filter that was applied
- `sampled_articles` (number): How many articles the ranking was built from
- `source_count` (number): How many publishers appeared in the sample
- `sources` (list): The publishers covering it, most active first
- `to_date` (text): The last day covered (YYYY-MM-DD), empty when no date filter
- `total_results` (number): How many articles match in total
- `window` (text): The window that was asked for
- `window_label` (text): That window in words

**Example output**

```json
{
  "countries": "us",
  "from_date": "2026-08-13",
  "keywords": "semiconductors",
  "languages": "en",
  "sampled_articles": 100,
  "source_count": 31,
  "sources": [
    {
      "article_count": 14,
      "country": "us",
      "country_label": "United States",
      "domain": "reuters.com",
      "latest_published_at": "2026-08-19T09:12:00+00:00",
      "latest_title": "Chip makers post record quarter as AI demand holds",
      "latest_url": "https://www.reuters.com/technology/chip-makers-record-quarter",
      "share_percent": 14.0,
      "source": "Reuters"
    },
    {
      "article_count": 9,
      "country": "au",
      "country_label": "Australia",
      "domain": "abc.net.au",
      "latest_published_at": "2026-08-19T07:45:00+00:00",
      "latest_title": "Regulators open review of cloud computing contracts",
      "latest_url": "https://www.abc.net.au/news/cloud-contracts-review",
      "share_percent": 9.0,
      "source": "ABC AU"
    }
  ],
  "to_date": "2026-08-19",
  "total_results": 293,
  "window": "last7days",
  "window_label": "Last 7 days"
}
```

### Search news

Search mediastack's news feed (7,500+ sources across 50+ countries in 13 languages) with every filter it offers: keywords, publishers, sections, countries, languages, a published-between range, ordering and paging. Each article comes back with its publisher, the domain it ran on and the readable names of its section, language and country.

**Inputs**

- Search for (`keywords`, text): What to look for. Write a phrase plainly (climate summit), separate several with commas, and prefix one with a minus sign to leave it out (tennis,-doubles). Optional here: leave it empty to take everything that matches the other filters.
- Publishers (`sources`, list): Optional. Only keep articles from these publishers, named by their mediastack id (cnn, abc-au). Use the Search publishers action to find an id. Prefix one with a minus sign to leave that publisher out instead.
- Sections (`categories`, list): Optional. Only keep articles filed under these sections of the news. Choose none to take them all. One or more of: `general`, `business`, `entertainment`, `health`, `politics`, `science`, `sports`, `technology`.
- Countries (`countries`, list): Optional. Only keep articles from publishers in these countries. Choose none to take the whole world. One or more of: `ae` (United Arab Emirates), `ar` (Argentina), `at` (Austria), `au` (Australia), `be` (Belgium), `bg` (Bulgaria), `br` (Brazil), `ca` (Canada), `ch` (Switzerland), `cn` (China), and 42 more.
- Languages (`languages`, list): Optional. Only keep articles written in these languages. Choose none to take them all. One or more of: `ar` (Arabic), `de` (German), `en` (English), `es` (Spanish), `fr` (French), `he` (Hebrew), `it` (Italian), `nl` (Dutch), `no` (Norwegian), `pt` (Portuguese), and 3 more.
- Published on or after (`from_date`, date): Optional. Only keep articles published on or after this day. Reaching back past today needs the Standard plan or higher.
- Published on or before (`to_date`, date): Optional. Only keep articles published on or before this day. Leave it empty to search a single day, or up to now.
- Order results by (`sort`, text): How to order the articles. Newest first is the default; most popular first puts the stories getting the most attention at the top. One of: `published_desc` (Newest first), `published_asc` (Oldest first), `popularity` (Most popular first). Default: `published_desc`.
- Only articles with an image (`only_with_image`, true/false): Leave out articles that came without a lead image. Useful when the result is going somewhere that needs a picture, such as a newsletter or a social post. Default: `false`.
- Results per page (`limit`, number): How many articles to return, from 1 to 100. Defaults to 25. From 1 to 100. Default: `25`.
- Skip (`offset`, number): How many results to skip before the ones you want. Leave it at 0 for the first page; to walk through a large set, use the 'next_offset' the previous run returned. Skip plus results per page cannot go past 10,000. From 0 to 10000. Default: `0`.

**Outputs**

- `article_count` (number): How many articles this page returned
- `articles` (list): The articles on this page
- `categories` (text): The section filter that was applied
- `countries` (text): The country filter that was applied
- `from_date` (text): The first day covered (YYYY-MM-DD), empty when no date filter
- `has_more` (true/false): True when another page of matches is available
- `keywords` (text): The search that ran
- `languages` (text): The language filter that was applied
- `limit` (number): How many were asked for
- `next_offset` (number): The Skip value for the next page, or empty when there is none
- `offset` (number): How many were skipped
- `only_with_image` (true/false): Whether image-less articles were left out
- `sort` (text): The ordering that was applied
- `sources` (text): The publisher filter that was applied
- `to_date` (text): The last day covered (YYYY-MM-DD), empty when no date filter
- `total_results` (number): How many articles match in total, across all pages
- `without_image_count` (number): How many articles were left out because they had no image (0 unless 'Only articles with an image' is on)

**Example output**

```json
{
  "article_count": 2,
  "articles": [
    {
      "author": "Jane Okafor",
      "category": "business",
      "category_label": "Business",
      "country": "us",
      "country_label": "United States",
      "description": "Revenue across the sector rose 18% year on year, with data-centre orders leading the way.",
      "domain": "reuters.com",
      "has_image": true,
      "image": "https://www.reuters.com/resizer/chips.jpg",
      "language": "en",
      "language_label": "English",
      "published_at": "2026-08-19T09:12:00+00:00",
      "source": "Reuters",
      "title": "Chip makers post record quarter as AI demand holds",
      "url": "https://www.reuters.com/technology/chip-makers-record-quarter"
    },
    {
      "author": "Tom Reilly",
      "category": "technology",
      "category_label": "Technology",
      "country": "au",
      "country_label": "Australia",
      "description": "The inquiry will look at exit fees and data transfer costs.",
      "domain": "abc.net.au",
      "has_image": true,
      "image": "https://live-production.wcms.abc-cdn.net.au/cloud.jpg",
      "language": "en",
      "language_label": "English",
      "published_at": "2026-08-19T07:45:00+00:00",
      "source": "ABC AU",
      "title": "Regulators open review of cloud computing contracts",
      "url": "https://www.abc.net.au/news/cloud-contracts-review"
    }
  ],
  "categories": "business,technology",
  "countries": "us,-gb",
  "from_date": "2026-08-12",
  "has_more": true,
  "keywords": "semiconductors",
  "languages": "en",
  "limit": 25,
  "next_offset": 2,
  "offset": 0,
  "only_with_image": false,
  "sort": "published_desc",
  "sources": null,
  "to_date": "2026-08-19",
  "total_results": 293,
  "without_image_count": 0
}
```

### Search publishers

Search the directory of publishers mediastack carries, by name, subject or country, and narrow it by section, country and language. Each result carries the id the news actions take, so this is how 'the Australian broadcaster' becomes abc-au.

**Inputs**

- Look for (`search`, text, required): What to search the directory for: part of a publisher's name, a subject, or a country. mediastack searches the directory rather than listing it, so this is required.
- Sections (`categories`, list): Optional. Only keep publishers filed under these sections of the news. One or more of: `general`, `business`, `entertainment`, `health`, `science`, `sports`, `technology`.
- Countries (`countries`, list): Optional. Only keep publishers based in these countries. One or more of: `ae` (United Arab Emirates), `ar` (Argentina), `at` (Austria), `au` (Australia), `be` (Belgium), `bg` (Bulgaria), `br` (Brazil), `ca` (Canada), `ch` (Switzerland), `cn` (China), and 42 more.
- Languages (`languages`, list): Optional. Only keep publishers writing in these languages. One or more of: `ar` (Arabic), `de` (German), `en` (English), `es` (Spanish), `fr` (French), `he` (Hebrew), `it` (Italian), `nl` (Dutch), `no` (Norwegian), `pt` (Portuguese), and 3 more.
- Results per page (`limit`, number): How many publishers to return, from 1 to 100. Defaults to 25. From 1 to 100. Default: `25`.
- Skip (`offset`, number): How many results to skip before the ones you want. Leave it at 0 for the first page; to walk through a large set, use the 'next_offset' the previous run returned. Skip plus results per page cannot go past 10,000. From 0 to 10000. Default: `0`.

**Outputs**

- `categories` (text): The section filter that was applied
- `countries` (text): The country filter that was applied
- `has_more` (true/false): True when another page is available
- `languages` (text): The language filter that was applied
- `limit` (number): How many were asked for
- `next_offset` (number): The Skip value for the next page, or empty when there is none
- `offset` (number): How many were skipped
- `search` (text): The search that ran
- `source_count` (number): How many publishers this page returned
- `source_ids` (list): Just the ids, ready to pass to Get news by publisher
- `sources` (list): The publishers that match
- `total_results` (number): How many publishers match in total

**Example output**

```json
{
  "categories": "general",
  "countries": "au",
  "has_more": false,
  "languages": "en",
  "limit": 25,
  "next_offset": null,
  "offset": 0,
  "search": "abc",
  "source_count": 1,
  "source_ids": [
    "abc-au"
  ],
  "sources": [
    {
      "category": "general",
      "category_label": "General",
      "country": "au",
      "country_label": "Australia",
      "domain": "abc.net.au",
      "id": "abc-au",
      "language": "en",
      "language_label": "English",
      "name": "ABC AU",
      "url": "http://abc.net.au/"
    }
  ],
  "total_results": 12
}
```

### Search recent news

Search news published within a window that moves with the clock (today, this week, the last 7 days) counted back from the day the step runs. This is the search to put on a schedule: a fixed date range would return the same articles on every run, while this one always looks at what is new.

**Inputs**

- Search for (`keywords`, text, required): What to look for. Write a phrase plainly (climate summit), separate several with commas, and prefix one with a minus sign to leave it out (tennis,-doubles).
- How far back (`window`, text): How far back to look, counted from the day the step runs, so a workflow on a schedule keeps looking at fresh news instead of a fixed date. Anything wider than today needs the Standard plan or higher. One of: `today`, `thisweek` (This week), `thismonth` (This month), `last7days` (Last 7 days), `last30days` (Last 30 days), `last3months` (Last 3 months), `yeartodate` (Year to date). Default: `today`.
- Sections (`categories`, list): Optional. Only keep articles filed under these sections of the news. Choose none to take them all. One or more of: `general`, `business`, `entertainment`, `health`, `politics`, `science`, `sports`, `technology`.
- Countries (`countries`, list): Optional. Only keep articles from publishers in these countries. Choose none to take the whole world. One or more of: `ae` (United Arab Emirates), `ar` (Argentina), `at` (Austria), `au` (Australia), `be` (Belgium), `bg` (Bulgaria), `br` (Brazil), `ca` (Canada), `ch` (Switzerland), `cn` (China), and 42 more.
- Languages (`languages`, list): Optional. Only keep articles written in these languages. Choose none to take them all. One or more of: `ar` (Arabic), `de` (German), `en` (English), `es` (Spanish), `fr` (French), `he` (Hebrew), `it` (Italian), `nl` (Dutch), `no` (Norwegian), `pt` (Portuguese), and 3 more.
- Order results by (`sort`, text): How to order the articles. Newest first is the default; most popular first puts the stories getting the most attention at the top. One of: `published_desc` (Newest first), `published_asc` (Oldest first), `popularity` (Most popular first). Default: `published_desc`.
- Results per page (`limit`, number): How many articles to return, from 1 to 100. Defaults to 25. From 1 to 100. Default: `25`.

**Outputs**

- `article_count` (number): How many articles this page returned
- `articles` (list): The articles on this page
- `categories` (text): The section filter that was applied
- `countries` (text): The country filter that was applied
- `from_date` (text): The first day covered (YYYY-MM-DD), empty when no date filter
- `has_more` (true/false): True when another page of matches is available
- `keywords` (text): The search that ran
- `languages` (text): The language filter that was applied
- `limit` (number): How many were asked for
- `next_offset` (number): The Skip value for the next page, or empty when there is none
- `offset` (number): How many were skipped
- `sort` (text): The ordering that was applied
- `to_date` (text): The last day covered (YYYY-MM-DD), empty when no date filter
- `total_results` (number): How many articles match in total, across all pages
- `window` (text): The window that was asked for
- `window_label` (text): That window in words
- `without_image_count` (number): How many articles were left out because they had no image (0 unless 'Only articles with an image' is on)

**Example output**

```json
{
  "article_count": 2,
  "articles": [
    {
      "author": "Jane Okafor",
      "category": "business",
      "category_label": "Business",
      "country": "us",
      "country_label": "United States",
      "description": "Revenue across the sector rose 18% year on year, with data-centre orders leading the way.",
      "domain": "reuters.com",
      "has_image": true,
      "image": "https://www.reuters.com/resizer/chips.jpg",
      "language": "en",
      "language_label": "English",
      "published_at": "2026-08-19T09:12:00+00:00",
      "source": "Reuters",
      "title": "Chip makers post record quarter as AI demand holds",
      "url": "https://www.reuters.com/technology/chip-makers-record-quarter"
    },
    {
      "author": "Tom Reilly",
      "category": "technology",
      "category_label": "Technology",
      "country": "au",
      "country_label": "Australia",
      "description": "The inquiry will look at exit fees and data transfer costs.",
      "domain": "abc.net.au",
      "has_image": true,
      "image": "https://live-production.wcms.abc-cdn.net.au/cloud.jpg",
      "language": "en",
      "language_label": "English",
      "published_at": "2026-08-19T07:45:00+00:00",
      "source": "ABC AU",
      "title": "Regulators open review of cloud computing contracts",
      "url": "https://www.abc.net.au/news/cloud-contracts-review"
    }
  ],
  "categories": "technology",
  "countries": "us",
  "from_date": "2026-08-13",
  "has_more": true,
  "keywords": "semiconductors",
  "languages": "en",
  "limit": 25,
  "next_offset": 2,
  "offset": 0,
  "sort": "published_desc",
  "to_date": "2026-08-19",
  "total_results": 293,
  "window": "last7days",
  "window_label": "Last 7 days",
  "without_image_count": 0
}
```