Recipes / Follow earnings coverage for a listed company

Follow earnings coverage for a listed company

/stories in keyword mode. This page is the operational half — what comes back, how it breaks, and what running it for real takes.

The request

GET /stories
  ?q="<TICKER>"
  &mode=keyword
  &from=2026-07-22
  &to=2026-07-29

As a call you can paste:

curl -s -G "https://api.unzoi.com/stories" \
  -H "x-api-key: $UNZOI_KEY" \
  --data-urlencode "q="<TICKER>"" \
  --data-urlencode "mode=keyword" \
  --data-urlencode "from=2026-07-22" \
  --data-urlencode "to=2026-07-29"

For an agent rather than a script, the same query is the list_stories MCP tool with these as its arguments.

Parameters used here

• from
• mode
• q
• to

What comes back

Coverage clusters around the announcement. During reporting season this reliably collapses several hundred syndicated items into a readable set of distinct events.

Field by field: the /stories response reference.

How this goes wrong

Using the company name in keyword mode and concluding coverage is thin. Fall back to hybrid if the ticker is ambiguous — some collide with ordinary words, and a three-letter ticker in keyword mode can return a great deal of nothing.

Adapting it

For a portfolio rather than one company, issue one query per ticker rather than an OR query — you want to attribute results, and a combined query makes that ambiguous. For companies without a liquid listing, fall back to hybrid mode with the registered name, and accept that recall will be lower. Japanese and Korean coverage is a special case: the ticker is often the only stable identifier because the name appears in several scripts.

Running it for real

Reporting season concentrates volume enormously, so budget for a peak that is many times the baseline rather than for the average. Bound queries to the reporting window rather than running a rolling window year-round, which spends most of its requests on quiet periods. If you are computing anything from tone, fix the outlet set first — financial coverage tone varies more by publication than by quarter.

Related recipes

• Detect layoff announcements as they are reported
• Catch supply chain disruption before the wires

Why this approach

The case for these parameters over the obvious alternatives — and when this recipe is the wrong tool entirely — is on the recipe's page on unzoi.com. It is kept there rather than repeated here, so the argument and the operations cannot drift apart.