An agent reacting to an earnings announcement needs live grounded data, not its model's memory. A model trained months ago has no idea Nvidia just beat on revenue and missed on guidance an hour ago, and if you ask it to comment it will confidently make something up. The fix is to pull the ticker's live search results at the moment earnings drop and hand that structured text to the LLM as context. This tutorial wires three Scavio endpoints into a grounding bundle: Google SERP (2 credits with light_request false), Reddit search, and YouTube search. To be clear about scope: Scavio is the data and grounding layer only. It returns search results. It does not generate trading signals, and nothing here is financial advice. What your agent does with the data, and whether you trade on it, is your own decision and your own risk.
Prerequisites
- A Scavio API key (50 free credits on signup, no card) — used as Authorization: Bearer {API_KEY}
- Python 3.9+ or Node 18+, plus an LLM client (any provider) to consume the grounding bundle
- A ticker symbol and the company name (for example AAPL / Apple) and the earnings date you want to react to
Walkthrough
Step 1: 1. Pull the live Google SERP for the ticker on the earnings date
At the moment earnings post, hit POST /api/v1/google with light_request set to false (2 credits) for the query "<ticker> earnings". Full features return organic results, people_also_ask, knowledge_graph, and related_searches in one call. Organic results carry headlines from press wires and analyst sites; knowledge_graph often holds the current quote and basic facts; people_also_ask surfaces the questions retail investors are actually typing. This is your factual spine. Note: Scavio does not return Google AI Overviews, so do not rely on a synthesized answer box — you ground on the raw results.
curl -X POST https://api.scavio.dev/api/v1/google \
-H "Authorization: Bearer $SCAVIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "NVDA earnings", "light_request": false}'Step 2: 2. Pull Reddit sentiment to gauge the retail reaction
Call POST /api/v1/reddit/search for "<ticker> earnings" to see what retail traders are saying in the minutes after the print. Reddit threads on subs like r/wallstreetbets and r/stocks react fast and emotionally, which is exactly the signal a news SERP misses. You are not treating upvotes as truth — you are giving the agent a read on crowd mood so it can flag divergence between the headline numbers and how the crowd is taking them. Reddit search is 1 credit; a full post with its comment tree is 2.
curl -X POST https://api.scavio.dev/api/v1/reddit/search \
-H "Authorization: Bearer $SCAVIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "NVDA earnings"}'Step 3: 3. Optionally pull YouTube coverage for analyst takes
If you want video commentary, call POST /api/v1/youtube/search. The body uses search, not query — this endpoint is the one exception, so do not send query here. YouTube surfaces analyst breakdowns and livestream reactions that publish within an hour of the call. Titles and descriptions are usually enough context for grounding; you rarely need the transcripts. This step is optional and costs 1 credit. Skip it if you are optimizing for latency or credits.
curl -X POST https://api.scavio.dev/api/v1/youtube/search \
-H "Authorization: Bearer $SCAVIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"search": "NVDA earnings reaction"}'Step 4: 4. Hand the structured bundle to the agent as grounding context
Merge the SERP, Reddit, and YouTube responses into one JSON object and put it in the LLM prompt as retrieved context, with an explicit instruction: summarize only what is supported by the provided results, and say so when the data is thin. This is the whole point — the model now describes what actually happened in the last hour instead of reciting stale training data. Keep the agent's job to summarization and structured extraction. It is a grounding consumer, not a signal generator, and it should never be the thing that places a trade on its own.
# Pseudocode: feed bundle as context, constrain the model to grounded claims
prompt = f"""You are summarizing an earnings reaction. Use ONLY the data below.
If the data does not support a claim, say it is unknown. Do not give advice.
GROUNDING:
{json.dumps(bundle)}
"""
response = llm.complete(prompt)Python Example
import os, json, requests
API = "https://api.scavio.dev/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SCAVIO_API_KEY']}",
"Content-Type": "application/json"}
def post(path, body):
r = requests.post(f"{API}{path}", headers=HEADERS, json=body, timeout=30)
r.raise_for_status()
return r.json()
def ground_earnings(ticker):
serp = post("/google", {"query": f"{ticker} earnings", "light_request": False})
reddit = post("/reddit/search", {"query": f"{ticker} earnings"})
youtube = post("/youtube/search", {"search": f"{ticker} earnings reaction"})
return {
"ticker": ticker,
"serp": {
"organic": serp.get("organic", [])[:5],
"people_also_ask": serp.get("people_also_ask", []),
"knowledge_graph": serp.get("knowledge_graph", {}),
},
"reddit": reddit.get("results", [])[:5],
"youtube": youtube.get("results", [])[:5],
}
# Scavio returns the data; your agent/LLM decides what to do with it.
# This is not financial advice and not a trading signal.
bundle = ground_earnings("NVDA")
print(json.dumps(bundle, indent=2)[:2000])JavaScript Example
const API = "https://api.scavio.dev/api/v1";
const HEADERS = {
"Authorization": `Bearer ${process.env.SCAVIO_API_KEY}`,
"Content-Type": "application/json",
};
async function post(path, body) {
const res = await fetch(`${API}${path}`, {
method: "POST",
headers: HEADERS,
body: JSON.stringify(body),
});
if (!res.ok) throw new Error(`${path} ${res.status}`);
return res.json();
}
async function groundEarnings(ticker) {
const [serp, reddit, youtube] = await Promise.all([
post("/google", { query: `${ticker} earnings`, light_request: false }),
post("/reddit/search", { query: `${ticker} earnings` }),
post("/youtube/search", { search: `${ticker} earnings reaction` }),
]);
return {
ticker,
serp: {
organic: (serp.organic || []).slice(0, 5),
people_also_ask: serp.people_also_ask || [],
knowledge_graph: serp.knowledge_graph || {},
},
reddit: (reddit.results || []).slice(0, 5),
youtube: (youtube.results || []).slice(0, 5),
};
}
// Scavio is the grounding layer. Decisions and trades are yours, and risky.
const bundle = await groundEarnings("NVDA");
console.log(JSON.stringify(bundle, null, 2).slice(0, 2000));Expected Output
{
"ticker": "NVDA",
"serp": {
"organic": [
{"title": "Nvidia reports Q earnings, revenue tops estimates", "link": "https://...", "snippet": "Nvidia posted revenue above consensus while guidance ..."},
{"title": "Analysts react to Nvidia's print", "link": "https://...", "snippet": "..."}
],
"people_also_ask": [
{"question": "Did Nvidia beat earnings this quarter?"},
{"question": "What is Nvidia's guidance for next quarter?"}
],
"knowledge_graph": {"title": "NVIDIA Corporation", "type": "Technology company"}
},
"reddit": [
{"title": "NVDA earnings thread", "subreddit": "wallstreetbets", "score": 1840, "url": "https://..."}
],
"youtube": [
{"title": "NVDA earnings reaction LIVE", "channel": "...", "url": "https://..."}
]
}
# The agent consumes this bundle as grounding context. It summarizes what the
# results actually say. It does not invent numbers and it does not place trades.