---
title: "News Article Search"
method: GET
path: "/gateway/v1/search/news"
tags: ["Search"]
---

# News Article Search

`GET /gateway/v1/search/news`

## Request

- Base URL: `https://api.asksurf.ai`
- URL: `https://api.asksurf.ai/gateway/v1/search/news`
- Auth: HTTP bearer

Searches crypto news articles by keyword.

Returns results ranked by relevance (default) or newest first (`sort_by=recency`), with highlighted matching fragments. Optional `from` / `to` bound the publish time; a poller watching a keyword should pass `sort_by=recency` and `from=<last seen published_at>`. Supports pagination via limit and offset.

## Query parameters

- `q` string, required: Search keyword or phrase
- `from` string: Filter articles published on or after this time. Accepts Unix seconds or date string (2024-01-01)
- `to` string: Filter articles published on or before this time. Accepts Unix seconds or date string (2024-02-01)
- `sort_by` 'relevance' | 'recency': Sort order: relevance (best match first) or recency (newest first). Pollers watching a keyword should use recency with from set to their last seen published_at
- `limit` integer: Results per page
- `offset` integer: Pagination offset

## Response `200`

OK

- DataResponseNewsArticleItem
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `data` NewsArticleItem[], nullable, required
    - `highlights` object: Search highlight fragments with <em> tags around matching terms. Only present in search results.
    - `id` string, required: Article ID. Use with the detail endpoint to fetch full content.
    - `project_id` string: Surf project UUID — pass as 'id' parameter to /project/detail, /project/events, or /project/defi/metrics for exact lookup
    - `project_name` string: Primary crypto project referenced in the article
    - `published_at` integer, required: Unix timestamp in seconds when the article was published
    - `source` string: Publisher name (e.g. COINDESK, COINTELEGRAPH)
    - `summary` string: Short summary of the article
    - `title` string, required: Article headline
    - `url` string: Direct URL to the original article
  - `meta` OffsetMeta, required
    - `cached` boolean, required: Whether this response was served from cache
    - `credits_used` integer, required: Credits deducted for this request
    - `empty_reason` string: Hint explaining why the data array is empty, when applicable
    - `has_more` boolean: Whether more items may exist beyond this response. For offset-paged endpoints, continue with a larger offset. For time-series endpoints without offset/cursor controls, true means the requested time range hit an upstream cap; narrow from/to to continue. Omitted when exhaustion cannot be proven.
    - `limit` integer, required: Maximum number of items returned in this response
    - `offset` integer, required: Number of items skipped (pagination offset)
    - `total` integer: Total number of matching items (before pagination). Omitted when total is unknown.
    - `watermark` integer: Warehouse watermark (Unix seconds) this response was computed at, on warehouse-backed endpoints (e.g. Hyperliquid /trades/aggregate) — rows up to this time come from the warehouse, newer rows from the live tail. Omitted elsewhere.

## Other responses

- `default`: Error

## Changes

- **2026-10-28** `3f0042c062ee`: 3 info
  - added the new optional `query` request parameter `from`
  - added the new optional `query` request parameter `sort_by`
  - added the new optional `query` request parameter `to`

[Operation history](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/changes/gateway/v1/search/news/get.md)

---

[API](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api.md) - [All operations](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/revisions/91774fdd5302?raw)