Search Briefs
Attributes
API Request
Example Request with cURL
curl \
--request GET \
--url 'https://guavy.com/api/v2/commodities/newsroom/search-briefs/<symbol>?keywords=<string>&limit=<integer>' \
--header 'Authorization: Bearer YOUR-GUAVY-ACCESS-TOKEN' \
--header 'Content-Type: application/json'
This request format works across all modern HTTP clients, including Python requests, JavaScript fetch, and other programming language libraries.
Example Response for /api/v2/commodities/newsroom/search-briefs/Oil?keywords=supply+outlook&limit=5
{
"briefs": [
{
"article_id": "92443e38-1b44-45b5-81d8-90fa2a40dba7",
"body": "Texas gas prices dropped by 2 cents to an average of $3.94 per gallon, but experts warn that this re...",
"clout": 48.0,
"date": "2026-10-02",
"fud_fomo_bias": "fud",
"fud_fomo_score": 4,
"impacted_coins": [
{
"asset": "GAS",
"confidence": 8,
"direction": "bullish",
"timeframe": "short"
},
{
"asset": "WTI",
"confidence": 6,
"direction": "bearish",
"timeframe": "short"
}
],
"sentiment": -1,
"speculation_score": 4,
"symbols": [
"Oil"
],
"timestamp": 1790960429938,
"title": "Texas Gas Prices Fall, But Relief May Be Short-Lived Amid Oi...",
"tone": "neutral"
},
{
"article_id": "896747c3-7301-4dae-a1fa-1165bbb19e43",
"body": "Alberta separatists remain unmoved by Premier Danielle Smith's claims that a new oil pipeline to BC ...",
"clout": 82.0,
"date": "2026-10-02",
"fud_fomo_bias": "fud",
"fud_fomo_score": 3,
"impacted_coins": [
{
"asset": "CAD",
"confidence": 6,
"direction": "neutral",
"timeframe": "long"
},
{
"WTI crude oil futures contract on the CME (symbol is CL=F on CBOE Globex, but XLE tracks this asset closely in its index composition and is a reasonable proxy for our analysis in this article.)": "",
"asset": "XLE",
"confidence": 5,
"direction": "neutral",
"timeframe": "short"
},
{
"Cenovus Energy, operator of the Christina Lake oil sands project": "",
"asset": "CNR",
"confidence": 4,
"direction": "neutral",
"timeframe": "short"
},
{
"Suncor Energy Inc., which operates a large oil sands mining and upgrading facility in Alberta,": "direction:bullish (potentially), neutral or bearish could also be valid depending on the interpretation of this article.",
"asset": "SU",
"confidence": 3,
"timeframe": "short"
},
{
"Cenovus Energy": "",
"asset": "CVE",
"confidence": 4,
"direction": "neutral",
"timeframe": "short"
}
],
"sentiment": -2,
"speculation_score": 8,
"symbols": [
"Oil"
],
"timestamp": 1790960370058,
"title": "Alberta Separatists Unfazed by Pipeline Announcement",
"tone": "neutral"
}
]
}
Response Object
Token Costs
Each API call consumes tokens from your monthly budget. Endpoints that return richer or deeper data cost more tokens. Historical endpoints scale with the amount of data requested.
You never have to guess how much is left: every metered response carries your balance in
x-tokens-* headers — x-tokens-cost (what this call cost),
x-tokens-limit / x-tokens-remaining (monthly), and
x-tokens-limit-today / x-tokens-remaining-today (daily). The
remaining values are net of any credit applied to the same request. A 401 refused at your
limit carries them too, with x-tokens-cost at 0 because nothing was charged.
| Endpoint | Token Cost |
|---|---|
| GET /api/v2/commodities/instruments/list-symbols | 1 |
| GET /api/v2/commodities/newsroom/get-recent-briefs/:symbol | 3 – 8 (scales with limit) |
| GET /api/v2/commodities/newsroom/search-briefs/:symbol | 3 – 8 (scales with limit) |
| GET /api/v2/commodities/newsroom/get-article/:id | 3 |
| GET /api/v2/commodities/sentiment/get-sentiment-history/:symbol | 3 – 12 (scales with limit) |
| GET /api/v2/commodities/technical-analysis/get-price-history/:symbol | 5 |
| GET /api/v2/commodities/technical-analysis/get-indicators/:symbol | 8 |
| GET /api/v2/commodities/instruments/scorecard/:symbol | 10 |
| GET /api/v2/commodities/trades/get-current-trend/:symbol | 3 |
| GET /api/v2/commodities/trades/get-trend-segments/:symbol | 5 |
Account Limits
Each plan includes a monthly token budget: 3,000 for Sandbox, 250,000 for Quant, and 1,000,000 for Pro. Your monthly plan budget resets to the full amount on the 1st of each month — unused base tokens don't carry over. You can top up at any time with a one-time token pack; pack tokens never expire and any unused pack balance rolls forward. If you exceed your budget, the API returns a 401 until the next reset or until you purchase more tokens.
Connection Limits
The Guavy API allows 300 requests per minute per API key, returning 429 above that, and has a 120-second timeout per request. We recommend caching responses that don't change frequently to reduce token consumption and improve performance.
