News Search

{
  "query": "renewable energy",
  "include_summary": true,
  "limit": 1
}

API reference: input, output and error schemas →

{
  "status": "ok",
  "query": "renewable energy",
  "retrieved_at": "2026-10-12T12:00:00Z",
  "window": {
    "start": "2026-10-05T12:00:00Z",
    "end": "2026-10-12T12:00:00Z",
    "date_basis": "gdelt_observed_at"
  },
  "articles": [
    {
      "id": "article-10e46334083ac0e3",
      "headline_id": "headline-9d12a0a05f5e0338",
      "title": "Renewable energy storage pilot opens",
      "url": "https://news.example.org/energy",
      "source_domain": "news.example.org",
      "language": "English",
      "source_country": "",
      "observed_at": "2026-10-11T12:00:00Z",
      "published_at": null,
      "duplicate_count": 1
    }
  ],
  "summary": {
    "basis": "headlines_only",
    "highlights": [
      {
        "text": "Renewable energy storage pilot opens",
        "article_ids": [
          "article-10e46334083ac0e3"
        ]
      }
    ]
  },
  "coverage": {
    "source": "GDELT headline index",
    "source_rows": 3,
    "returned": 1,
    "duplicates_removed": 1,
    "discarded_rows": 0,
    "source_limit": 150,
    "previously_seen_removed": 0,
    "possibly_truncated": false,
    "result_byte_limited": false
  },
  "attribution": {
    "name": "The GDELT Project",
    "url": "https://www.gdeltproject.org/"
  },
  "limitations": [
    "Dates are GDELT monitoring times, not verified publication or first-ever observation times.",
    "Results are a bounded source sample, not exhaustive news coverage or verified facts.",
    "Links remove known tracking fields; publisher canonical URLs and reachability are unverified.",
    "Search matches native-language headlines only. Highlights quote them; articles are not read.",
    "Updates use a45-minute overlap and bounded32-entry history; busy topics can omit coverage or repeat older items."
  ],
  "monitoring": {
    "state": "initial",
    "overlap_seconds": 2700,
    "history_limited": false,
    "next_request": {
      "query": "renewable energy",
      "match": "all",
      "days": 7,
      "limit": 1,
      "sort": "newest",
      "language": "english",
      "include_summary": true,
      "since": "2026-10-12T12:00:00Z",
      "seen": [
        {
          "id": "article-10e46334083ac0e3",
          "headline_id": "headline-9d12a0a05f5e0338"
        }
      ]
    }
  }
}

Calling

Method

POST

Url

https://api.mekler.ai/v1/research/news/find-topic-news

Content type

application/json

Steps

• Send the intended JSON unsigned to receive a402 quote; source retrieval happens only after proof authorization.

• Sign one Base or Solana offer and resend the identical JSON with PAYMENT-SIGNATURE.

• A202 is provisional: retain the original proof and retry the same body until independently finalized. Never sign again for recovery.

• For a new paid poll, send monitoring.next_request as the next unsigned request. Retain the prior packet until delivery; retry an uncertain poll with its own original proof.

Defaults

Match

all

Days

7

Limit

10

Sort

newest

Language

english

Include summary

False

Seen

Retry

Keep identical JSON and original proof. Successful encrypted results recover for30 days; they are never regenerated after charge.

Interpret the result

Articles

Bounded deduplicated source sample. URL cleanup removes known tracking fields; no rel=canonical or reachability assertion.

Observed at

GDELT monitoring UTC time, not verified publication or first-ever observation; published_at remains null.

Summary

Optional exact headline quotations with returned article IDs; not full-text interpretation or fact verification.

Coverage

Source row, returned, discarded and duplicate counts; possibly_truncated flags a full150-row source page. result_byte_limited indicates fewer results to fit the deliverable response bound. previously_seen_removed counts history matches removed from the retrieved page; the index excludes known URL prefixes before applying its150-row bound.

Empty results

A completed poll with no new links is charged0.01 USDC. Source failures or wholly unusable records fail uncharged.

Monitoring

initial/no_matches describe an initial search; updates/no_new_links describe a follow-up. next_request is ready to send, or null for explicit historical dates. A checkpoint advances only on successful delivery. This is bounded polling, not guaranteed exhaustive event monitoring.

Limits

Query characters

3–160 plain topic characters, at most12 words

Date window

last7 days; days excludes explicit dates, which must be paired and not future

Limit

1–30 returned; at most150 source rows considered

Body bytes

4096

Source

Private AWS index of GDELT public headline metadata; stale or preparing indexes fail uncharged

Result bytes

14000

Source search deadline seconds

8

Monitoring

since is a last7-day UTC checkpoint with45-minute overlap; excludes explicit dates. Up to32 seen markers; generated follow-ups fit3500 bytes.

Payment and recovery

Price

0.01 USDC per completed search

Network

Solana mainnet or Base mainnet

Protocol

x402 v2 exact

Quote

Send the intended JSON body without PAYMENT-SIGNATURE. A 402 PAYMENT-REQUIRED header contains two network offers; bodyless preflight is not payable.

Authorization

Choose one accepts entry with a standard x402 v2 client. Check native USDC, network, recipient, amount and intended input before signing. Solana uses an SVM transaction; Base uses an EOA EIP-3009 authorization (USD Coin version 2). Send the proof with identical JSON input. No API key, token approval, bridge or Solana wallet is needed for Base. Never automatically fall back to another network.

Retry

Retry identical JSON and the original proof after uncertainty. Source failures before settlement are uncharged.

Finality

A finalized response independently checks chain success and the exact transfer. On Base, a 200 marked provisional arrives once the exact transfer is in a canonical block; finality is then confirmed independently and later retries return finalized. A 202 remains pending. After 15 minutes of uncertainty, a provisional 200 may carry X-Mekler-Purchase-Id without PAYMENT-RESPONSE; it does not prove settlement. Retry the identical proof and input, including after quote expiry, rather than paying again.

Expiry

Ongoing service under recurring monthly authority. Budget warnings do not stop service. Short-lived quotes and recovery retention still expire.

Networks

• solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp

• eip155:8453

Assets

Solana:5eykt4usfv8p8njdtrepy1vzqkqzkvdp

EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

Eip155:8453

0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

Fees

CDP sponsors the payment transaction gas on both networks. The service price is the same on either network; wallet funding or exchange fees are separate.

Request binding

The server authenticates the complete quote and input and atomically binds the first accepted authorization to them. Standard Base EIP-3009 signs the money terms and nonce, not HTTP content. Keep signatures private; do not reuse an authorization for another quote, operation or body.

Refund policy

Failed source work is uncharged. Valid empty results are completed searches. Preserve original proof for pending/recovery outcomes.