---
title: "Search the news for stories on a subject"
method: GET
path: "/search/news"
tags: ["Search"]
---

# Search the news for stories on a subject

`GET /search/news`

## Request

- Base URL: `https://api.socially.run/v1`
- URL: `https://api.socially.run/v1/search/news`
- Auth: HTTP bearer

What the press published about a subject inside a window: headline, publisher, and the date the story ran, read from Google News' public search feed. This is the subject half of trending: a trending board takes no query at all, so `q` plus `recency` is how you ask what is being said about one thing right now. Links are Google's own redirect, not the publisher's URL. Cached for ten minutes.

## Query parameters

- `q` string, required: The subject to read about, the way you would say it.
- `limit` integer: Stories to return, 1–50. One feed is one read: a larger `limit` on the same question is served from it.
- `recency` 'day' | 'week' | 'month' | 'year': Only stories published within the window: `day`, `week`, `month` or `year`. Absent means any time, which for news is rarely the question.
- `country` string: The Google News edition, ISO 3166-1 alpha-2 (BR, US, ES). There is no worldwide edition: leave it out and one is chosen from `language`. The answer always says which one ran.
- `language` string: The edition's language, ISO 639-1 (en, pt, es). Default `en`.
- `refresh` boolean: Read the feed again instead of serving the ten-minute cache. Charged like any read.

## Response `200`

Search the news for stories on a subject

- object
  - `data` unknown, required

## Other responses

- `400`: VALIDATION_ERROR / INVALID_TARGET / SSRF_BLOCKED: the issues, never the values.
- `401`: UNAUTHORIZED / INVALID_TOKEN: the key is missing or wrong.
- `402`: PAYMENT_REQUIRED / PLAN_GATE: clears by upgrading or buying credits, never by waiting.
- `429`: RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED: Retry-After says when it clears.
- `default`: Any other failure.

---

[API](https://skmtc.dev/socially/apis/socially-run-send-a-profile-link-get-its-public-data-as-json.md) · [All operations](https://skmtc.dev/socially/apis/socially-run-send-a-profile-link-get-its-public-data-as-json/llms.txt) · [OpenAPI document](https://skmtc.dev/socially/apis/socially-run-send-a-profile-link-get-its-public-data-as-json/revisions/5a0b24534b90?raw)