> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tradingnews.press/llms.txt
> Use this file to discover all available pages before exploring further.

# Search News

> Semantic search over the article archive

<Note>
  Available on the **Max** plan only. Requests from Starter or Pro keys return `403`.
</Note>

## Query Parameters

<ParamField query="q" type="string" required>
  Natural-language query. 2 to 500 characters.
</ParamField>

<ParamField query="limit" type="integer" default="20" optional>
  Number of articles to return. Min: 1, Max: 100.
</ParamField>

## Response

<ResponseField name="count" type="integer">
  Number of articles returned.
</ResponseField>

<ResponseField name="query" type="string">
  The original query string, echoed back.
</ResponseField>

<ResponseField name="articles" type="Article[]">
  Articles ranked by semantic relevance to the query. Same schema as `/v1/news`. Because semantic search is Max-only, each article includes a `tickers` array with per-ticker sentiment (e.g. `[{"ticker": "AAPL", "sentiment": "positive"}]`); the array is empty when no tickers were detected.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -H "X-API-Key: YOUR_KEY" \
    "https://api.tradingnews.press/v1/news/search?q=Fed%20interest%20rate%20decision&limit=5"
  ```

  ```python Python theme={null}
  import httpx

  resp = httpx.get(
      "https://api.tradingnews.press/v1/news/search",
      headers={"X-API-Key": "YOUR_KEY"},
      params={"q": "Fed interest rate decision", "limit": 5},
  )
  articles = resp.json()["articles"]
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "count": 2,
    "query": "Fed interest rate decision",
    "articles": [
      {
        "id": "01KP8JCVDPYSS17HNRZPXNAZCP",
        "content": "Federal Reserve official Hammack stated that there are risks regarding the direction of interest rate targets...",
        "urgency": "regular",
        "sentiment": null,
        "published_at": "2026-04-15T12:38:07+00:00",
        "received_at": "2026-04-15T12:38:28.022468+00:00",
        "tickers": []
      },
      {
        "id": "01KP8JCVDPYSS17HNRZPXNAZCQ",
        "content": "Bank of America raises terminal rate forecast after stronger-than-expected payrolls print.",
        "urgency": "flash",
        "sentiment": "hawkish",
        "published_at": "2026-04-15T12:35:00+00:00",
        "received_at": "2026-04-15T12:35:18.114002+00:00",
        "tickers": [
          {"ticker": "BAC", "sentiment": "neutral"}
        ]
      }
    ]
  }
  ```

  ```json 403 theme={null}
  {
    "detail": "Semantic search is available on the Max plan only."
  }
  ```

  ```json 503 theme={null}
  {
    "detail": "Embedding service temporarily unavailable; please retry shortly."
  }
  ```
</ResponseExample>