hawkcrawl

API Reference

One endpoint. Send a query, get structured news back — from the last hour or from 2010.

Quickstart

Every account gets 5,000 free credits a month — 5,000 searches, or 250 articles with full text, or any mix. No card, and no delay on results: the free tier returns the same live articles the paid ones do.

# your first request
curl "https://api.hawkcrawl.com/v1/news?q=tesla" \
  -H "Authorization: Bearer hc_live_YOUR_KEY"

That is the whole integration. There is no SDK to install and no client to configure — but here is the same call in the two languages people actually use.

Python

import requests

r = requests.get(
    "https://api.hawkcrawl.com/v1/news",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={
        "q": "tesla earnings",
        "limit": 10,
        "content": "true",   # full article text
        "dedupe": "true",    # drop syndicated copies, uncharged
    },
    timeout=60,
)
r.raise_for_status()
data = r.json()

print(f"{data['count']} articles, {data['credits_used']} credits")
for a in data["articles"]:
    # content is None when the publisher refused us — and was not charged
    if a.get("content"):
        print(a["source"], "—", len(a["content"]), "chars")
    else:
        print(a["source"], "— no text:", a.get("content_status"))

JavaScript

const params = new URLSearchParams({
  q: "tesla earnings",
  limit: "10",
  content: "true",
  dedupe: "true",
});

const res = await fetch(`https://api.hawkcrawl.com/v1/news?${params}`, {
  headers: { Authorization: `Bearer ${process.env.HAWKCRAWL_KEY}` },
});

if (res.status === 402) {
  // the body says what you hold and what the call needed
  const { balance, required } = await res.json();
  throw new Error(`need ${required} credits, have ${balance}`);
}

const { articles, credits_used } = await res.json();
for (const a of articles) {
  // a.content is null when the publisher would not give it up
  console.log(a.source, a.content ? `${a.content.length} chars` : a.content_status);
}

Authentication

Pass your key as a bearer token. Keys are shown once at creation — store it then, because we only keep a hash.

Authorization: Bearer hc_live_YOUR_KEY

A key can also go in the key query parameter when a header is inconvenient, though the header is preferred so the key stays out of logs and browser history.

GET /v1/news

The response

Every response is JSON. articles is ordered newest first.

{
  "query": "tesla",
  "count": 2,
  "credits_used": 1,
  "cached": false,
  "articles": [
    {
      "id": "CBMipAFBVV95cUxNWldfU2Jy...",
      "title": "Tesla’s Cybercab Launch Fizzles, Leaving Waymo as the Robotaxi Leader",
      "source": "Yahoo Finance",
      "published_at": "2026-09-15T20:14:02Z",
      "url": "https://news.google.com/rss/articles/CBMipAFBV...",
      "resolved_url": null
    },
    {
      "id": "CBMijwFBVV95cUxQQXFwOTFB...",
      "title": "Woman hit on Pacific Beach boardwalk by man driving a stolen Tesla",
      "source": "KCRA",
      "published_at": "2026-09-15T22:03:00Z",
      "url": "https://news.google.com/rss/articles/CBMijwFBV...",
      "resolved_url": null
    }
  ]
}

What we return, and what we don't

We would rather you find this out here than after you have written the integration.

Date ranges and the archive

Historical queries are ordinary queries with from and to. We have verified results at 2010, 2018, 2020, 2022, 2023, 2024 and 2025.

curl "https://api.hawkcrawl.com/v1/news?q=tesla&from=2024-01-01&to=2024-02-01" \
  -H "Authorization: Bearer hc_live_YOUR_KEY"

{
  "query": "tesla",
  "from": "2024-01-01",
  "to": "2024-02-01",
  "count": 2,
  "credits_used": 1,
  "cached": true,
  "articles": [
    {
      "id": "CBMilgFBVV95cUxPSlFxM1Z6...",
      "title": "I rented an EV from Hertz. I'm not surprised they're dumping 20,000 electric cars.",
      "source": "Business Insider",
      "published_at": "2024-01-11T08:00:00Z",
      "url": "https://news.google.com/rss/articles/CBMilgFBV...",
      "resolved_url": null
    },
    {
      "id": "CBMivAFBVV95cUxPSWJkYWJ6...",
      "title": "Tesla loses EV sales crown to BYD in Q4, despite annual sales record",
      "source": "Wards Auto",
      "published_at": "2024-01-03T08:00:00Z",
      "url": "https://news.google.com/rss/articles/CBMivAFBV...",
      "resolved_url": null
    }
  ]
}

Note "cached": true. A date range that has already passed cannot change, so historical queries are served from cache and answer in milliseconds. They cost the same credit either way.

For relative windows use when instead: when=1h, when=7d, when=1y. With neither parameter you get roughly the last five days.

Languages

Pass lang, and country when you want a different edition of the same language. Every row below was checked against the live API and returned articles from publishers in that language.

Anything else returns 400 invalid_request naming the codes we support. We would rather refuse than quietly hand you English and let you ship it.

Resolving article URLs

The url we return is a redirect, not the publisher's address. Pass resolve=true and we look up each article's real URL and return it in resolved_url.

curl "https://api.hawkcrawl.com/v1/news?q=tesla&limit=10&resolve=true" \
  -H "Authorization: Bearer hc_live_YOUR_KEY"

Billing: 1 credit for the search, plus 4 credits for each article resolved. A resolved URL is cached permanently, so the same article never costs twice.

Leave it off when you only need headlines — most monitoring and alerting use cases never need the publisher URL.

Speed: resolving is work we do per article. A cold limit=50 with resolve=true takes a few seconds; because resolved URLs are cached permanently, the same articles come back instantly afterwards. If you are polling a feed on a schedule, only the first call pays for it.

Article text

Pass content=true and we resolve the article, fetch the publisher's page, and return the body text in content. It implies resolve=true.

This is the whole article, not a preview. For comparison, NewsAPI's documentation says its content field "is truncated to 200 chars" — ours is the full body or an honest null.

curl "https://api.hawkcrawl.com/v1/news?q=tesla&limit=10&content=true" \
  -H "Authorization: Bearer YOUR_KEY"

A short body is reported as paywalled rather than returned as content — a 400-character news article is a subscription teaser, and passing that to a model is worse than passing nothing. We would rather return you an honest null than something that reads like an article and isn't.

Billing: 20 credits per article whose text we actually returned, on top of 1 for the search and 4 per article resolved. Extracted text is cached for 30 days and a cached article is never billed twice.

Syndicated duplicates

Measured over 160 articles across eight queries on 18 September 2026: 18% of what a search returns is a story already in the same result set. Almost all of it is syndication — one article republished by content partners. "Prediction: Tesla Stock Will Be Worth This Much in 2031" came back from The Motley Fool, Yahoo Finance and AOL.ca, character for character.

For a retrieval pipeline that is worse than waste: the same claim three times in a context window makes a model more confident, not better informed. And at 20 credits an article, you paid three times for one story.

curl "https://api.hawkcrawl.com/v1/news?q=tesla&limit=20&content=true&dedupe=true" \
  -H "Authorization: Bearer YOUR_KEY"

The copies are collapsed before anything is resolved or extracted, so you are never charged for them. The article Google ranked highest is kept and the rest are listed against it:

{
  "title": "Prediction: Tesla Stock Will Be Worth This Much in 2031",
  "source": "The Motley Fool",
  "content": "...",
  "duplicates": [
    { "source": "Yahoo Finance", "title": "...", "url": "..." },
    { "source": "AOL.ca", "title": "...", "url": "..." }
  ]
}

Relevance scores

Google News is good on mainstream subjects and weaker on narrow ones. A search for semiconductor export controls returned, among real coverage, a SanDisk share-price page, a Goldman Sachs note about futures traders, and a market-report advert. Keyword matching cannot catch those — the word semiconductor is right there in each.

relevance=true adds a score from 0 to 1 and a short reason to every article:

{
  "title": "AT&T Inc Share Price - T, RNS News, Quotes",
  "relevance": 0,
  "relevance_note": "ticker page, not an article"
}

Billing: 5 credits for the whole result set, not per article, and only when the scores actually arrive. If the model is slow or unreachable you get your articles unscored and are charged nothing for it. Expect it to add one to three seconds; it is off by default for that reason.

Credits and caching

A credit is a tenth of a cent, so a dollar buys a thousand — and more than a thousand when you top up more at once.

Failed requests cost nothing: if we cannot reach the index, the query returns no articles, an article will not resolve, or a publisher refuses us the text, you are not charged. Given that roughly half of articles return no text, that is not a courtesy — write your integration against it.

5,000 free credits arrive every month and do not need a card. Bought credits do not expire at all: there is no subscription and no reset. Pricing has the volume rates and worked examples.

Cached responses carry "cached": true and return in milliseconds. They still cost the one search credit — you received the answer — but a resolve or an extraction already paid for is never charged again.

Rate limits

10 requests per second and 120 per minute per key. Exceeding either returns 429 with a Retry-After header. Rate limits are per key, so splitting work across keys splits the limit rather than raising it.

Errors

Every error has the same shape, so you can branch on error and show message.

{
  "error": "insufficient_credits",
  "message": "You have 3 credits remaining. Top up at https://api.hawkcrawl.com/billing."
}