Developments and Events
Developments are structured narrative units (name, description, scores, stakeholders with signed impact, sources with quotes) versioned over time. Events are longer-lived story containers that group related developments into a lifecycle (earnings cycle, M&A process, regulatory campaign, geopolitical conflict).
| Operation | Role |
|---|---|
search_developments | Semantic or filter search over developments — returns packages |
retrieve_development | Package for one known development_id (optional as-of) |
search_events | Semantic or filter search over events; embeds recent development summaries |
retrieve_event_developments | Event metadata + developments timeline |
When to use
Use this surface when you need to:
- Explain a market move with who wins/loses (signed
impact_scoreper ticker) and cited sources - Track a storyline lifecycle via an
event_id - Scan for surprising / important developments
- Filter by public-company ticker involvement
- Backtest “what was known as of T” with
end_timestamp
Do not use when you need:
- Realtime novelty-clustered headlines → Wire
- Open-web research (article body, quotes, filings, prices) → your native web search tool
- A single-entity dossier →
retrieve_entity - Entity-filtered headline monitoring → Wire
Use cases
Ticker blast radius — Find developments that hit a ticker hard in either direction, with signed impacts and quotes.
Code
Negative for one ticker — Isolate clearly negative impact on a single name.
Code
Portfolio watchlist — One query for up to eight tickers instead of one call per name.
Code
Surprising geopolitics — Scan for high-surprise security developments, not every geopolitics mention.
Code
Theme → development evidence — Ask in natural language and get structured impact packages back.
Code
Theme → event clusters — See how a theme groups into longer-lived stories, not just one-off updates.
Code
M&A scan — List active deal storylines without inventing your own type labels.
Code
Important prints — Desk scan for high-importance developments without a theme query.
Code
Lifecycle expand — Once you have an event id, pull the full timeline (scheduled → print → follow-ons).
Code
As-of / backtest search — Ask what developments were known as of a past timestamp.
Code
As-of single development — Reconstruct one development’s package as it stood at a prior time.
Code
Mental model
Code
A development can belong to multiple events. Always read events / event_ids.
Three clocks (do not conflate):
| Field | Meaning |
|---|---|
timestamp | System/version time — used for backtest start/end_timestamp and “latest version” collapse |
source_timestamp | Latest source used for the development |
occurrence_timestamp | Estimated real-world when it happened (or will) — lifecycle ordering and include_future_developments |
Response detail
Most operations accept detail. Default is full. Reduced levels drop keys only — surviving fields keep the same names and paths as full. Pricing does not change with detail; this is about response token cost (development packages are heavy).
search_developments / retrieve_development / retrieve_event_developments
Levels: full | standard | essential.
| Level | What you get | Rough token savings vs full |
|---|---|---|
essential | Identity, timing, name/description, stakeholder impacts (no confidence/sources), thin event refs | ~75% (search/retrieve development); ~68% (retrieve_event_developments) |
standard | essential + type/status, heuristic scores, citable sources (title/url; no quotes), fuller event summaries | ~39% (search/retrieve development); ~38% (retrieve_event_developments) |
full | Every field including rationale and source quotes | — |
Prefer detail: "standard" for normal agent calls. Use essential for scanning many packages; use full when you need rationale or quoted evidence in the payload.
Code
search_events
Levels: full | essential only (no standard — the middle tier barely saved tokens on this shape).
| Level | What you get | Rough token savings vs full |
|---|---|---|
essential | Event id/name/description + recent development summaries (id / occurrence / name / description) | ~33% |
full | Includes event_type and richer recent-development fields (scores, types, …) | — |
Prefer detail: "essential" when scanning events; use full when you need event type or summary scores.
search_developments
Optional query: semantic over development descriptions, ranked by cosine (cosine not returned in the response). No query: latest version per development_id matching filters, ordered by timestamp DESC.
Returns development packages shaped by detail (default full; prefer standard — see detail above). You do not need retrieve_development after a search hit unless you need as-of reconstruction for a known id.
| Param | Notes |
|---|---|
query | Optional. Max 2000 chars. |
symbols | Tickers, max 8. Match any. Exact as stored (TSLA, GOOGL, SGRO.L). tsla → []. Not Ultralayer canonical names. |
min_impact_score / max_impact_score | Alone: threshold. Together: directional OR (impact >= min OR impact <= max) — requires min >= max (e.g. 0.5 + -0.5). |
min_importance_score / min_surprise_score / min_confidence_score | Importance ~0.8+ is a strong desk filter |
development_type | Exact free-form string (financial_update, corporate_action, geopolitical_security, …). Invented values silently return []. Discover types from results. |
start_timestamp / end_timestamp | On development timestamp. Future start → 422. Future end → realtime. |
start_occurrence_timestamp / end_occurrence_timestamp | Real-world occurrence clock |
limit | Default 5, max 20 |
detail | Default full. Prefer standard. |
Packages are large at full (rationale + per-stakeholder quotes). Prefer tight limit (3–10) and detail: "standard"; expand event context with retrieve_event_developments when you need the storyline.
occurrence_status values seen: occurred, scheduled, announced, ongoing, rumored — no status filter param.
retrieve_development
Required: development_id. Optional: end_timestamp for as-of (latest version with timestamp <= end). Optional: detail (default full; prefer standard).
Use when you already have an id (from an alert, prior run, or citation) or need as-of reconstruction. Search results already include the package at the requested detail — do not re-fetch the same id after search_developments unless you need a different detail or as-of.
Missing id → 404. As-of before the development existed → 404. Future end_timestamp → realtime.
search_events
Optional query: semantic over event descriptions. No query: ordered by most recent development activity.
Timestamp filters gate on development activity: an older event still appears if it had a development recorded in-window. No activity → [].
| Param | Notes |
|---|---|
query | Optional. Max 2000 chars. |
symbols | Tickers, max 8. Match any. Exact as stored. Gates events via development stakeholder involvement; does not filter embedded recent_developments. |
event_type | Exact free-form (merger_acquisition, earnings, product_launch, executive_succession, …) |
limit | Default 5, max 10 |
developments_per_event | Default 3, max 5, 0 allowed (event cards only — cheap scanning) |
include_future_developments | Default true. Filters on occurrence_timestamp vs now/end — does not drop past-dated scheduled items |
detail | full | essential only (no standard). Prefer essential when scanning. |
Embedded recent_developments are summaries (no rationale/stakeholders/sources). Escalate with retrieve_event_developments or search_developments for development packages.
retrieve_event_developments
Required: event_id. Returns event metadata + developments ordered by occurrence_timestamp DESC. Packages follow detail (default full; prefer standard).
| Param | Notes |
|---|---|
limit | Default 5, max 20 |
start_timestamp / end_timestamp | Filter on development recording time (useful for polling new packages) |
include_future_developments | Default true |
detail | Default full. Prefer standard. |
Missing event → 404.
Workflow
| User intent | Approach |
|---|---|
| “Who is affected by X?” | search_developments → read stakeholder impacts; cite quotes |
| “What’s the Tesla earnings story this year?” | search_developments or search_events → take event_id → retrieve_event_developments |
| “Any big M&A?” | search_events with event_type: merger_acquisition |
| “Negative for GOOGL?” | symbols: ["GOOGL"], max_impact_score: -0.5 |
| “What just printed that’s important?” | No-query search + min_importance_score: 0.8 |
| “Headline triage / first print” | Wire first; escalate here for structured impact |
| “Reconstruct this development as of T” | retrieve_development with end_timestamp |
- Decide grain: atomic impact update (developments) vs storyline cluster (events).
- Prefer ticker + score filters for desk questions; prefer semantic query for themes.
- Keep
limitsmall; setdetail: "standard"(oressentialonsearch_events); setdevelopments_per_eventlow (or 0) when scanning events. search_developmentsalready returns packages at your chosendetail— do not callretrieve_developmenton those ids unless you need as-of or a richerdetail. Expand storylines withretrieve_event_developments.- Collapse near-duplicate developments under the same event before briefing.
- Hand off to Wire for live novelty, your native web search tool for open-web research,
retrieve_entityfor identity packages.
Limitations
- Near-duplicate developments can exist as separate ids for the same real-world fact — dedupe by event + occurrence window + name similarity.
- Stakeholders are PUBLIC_COMPANY + ticker only — no countries/commodities/people as stakeholders.
- Ticker strings are exact and case-sensitive (
TSLA≠tsla), max 8 chars. development_type/event_typeare not closed enums — inventing labels yields empty results.- Cosine not exposed for thresholding.
- Packages are heavy at
full— bad default for large scans withoutdetail: "standard"/essential, tight limits, ordevelopments_per_event: 0. scheduledstatus can linger after occurrence time.- Not filterable by Ultralayer entity ids; use tickers or semantic query text.
FAQ
Q: Wire already has Tesla headlines — why developments?
A: Developments add multi-ticker impact scores, rationales, and event clustering. Wire tells you it printed; developments tell you who is in the blast radius and why.
Q: Why did development_type: "earnings" return nothing?
A: Earnings prints are often typed financial_update; earnings appears more as an event_type. Discover types from hits.
Q: include_future_developments: false still showed “scheduled” items.
A: Filter is on occurrence_timestamp vs now, not on status label. Past-dated schedules remain.
Q: Can I filter by Ultralayer entity name Tesla, Inc.?
A: No. Use symbols: ["TSLA"] or semantic query text.
Q: search_events with a July window returned an older long-running event — bug?
A: Timestamps gate development activity. Old events with new developments in-window correctly appear.
Q: retrieve_development as-of before the print 404s.
A: Expected — no version existed yet.
Q: search_events vs search_developments?
A: Events for clusters/lifecycles (summaries); developments for atomic updates + stakeholder math (full packages). Typical flow: search either → expand with retrieve_event_developments when you need the timeline; use retrieve_development only for a known id or as-of.