Entity Retrieval

retrieve_entity returns a realtime context package for one Ultralayer entity. Single required param: entity (case-insensitive canonical name). No time window, no top_k — the package shape is fixed.

When to use

Use retrieve_entity when you need to:

• Bootstrap a company / person / commodity / country / institution briefing
• Resolve the correct canonical_name + entity_id before Wire filters
• Read 14-day mention sentiment without hand-rolling Wire aggregation
• Discover who co-moves in the news with the target
• Pull attribute bags (CEO, ticker, products, market cap, …) as starting facts — then verify

Do not use when you need:

• A filtered multi-entity news firehose → Wire
• Quoteable document passages → semantic_search
• Point-in-time / as-of packages → not supported (realtime only)
• Sparse / quiet entities → fails with insufficient_entity_activity

Use cases

Company dossier seed — One call for recent headlines, 14-day sentiment, who else is in the story, and structured attributes.

Code
{ "entity": "Tesla, Inc." }

Resolve the name before Wire — Get the exact registry name so later company watches don’t silently miss.

Code
{ "entity": "Nvidia Corporation" }

Then reuse entity.canonical_name exactly in list_wire entity filters.

Person → affiliated universe — See which companies and projects dominate the news around a person.

Code
{ "entity": "Elon Musk" }

Follow co-mentions (Tesla, Inc., SpaceX, xAI) with more retrieve_entity or Wire.

Commodity / macro driver — Brief a commodity and discover the geopolitics and related markets moving with it.

Code
{ "entity": "Brent Crude" }

Use co-mentions (Iran, Hormuz, WTI) to choose Wire entity filters and semantic queries.

Institution — Quick context pack for a policy body that drives markets.

Code
{ "entity": "Federal Reserve" }

Country — High-volume national tape: recent prints, sentiment trend, and co-moving names.

Code
{ "entity": "Iran" }

What you get back

Requires sufficient recent wire activity; sparse entities return 422 insufficient_entity_activity.

Name resolution

Match is case-insensitive exact canonical_name. Tickers and loose aliases are not resolved.

Short brand names that look right can fail the activity gate because they hit the wrong identity. Prefer full legal-style names for listed cos ("Apple Inc.", "Nvidia Corporation", "easyJet plc"). Best practice: take canonical_name from a prior Wire hit or a successful package and reuse it.

Unknown names → unresolved_entities + suggestions (candidates to retry, not confirmed identities). Sparse-but-resolved names → insufficient_entity_activity with no suggestions — often means “wrong short name,” not “entity is quiet.”

How to read each section

Recent wire items. Decision-grade headlines. Duplicates stripped. Use wire_id → wire_storyline for story evolution.

Sentiment chart. end_timestamp is the exclusive end of the UTC day (bar for 2026-07-23 ends at 2026-07-24T00:00:00Z). Interpret with mention_count and weighted_std — one-mention days and high std are noisy. Mega-entities (countries) show flatter averages.

Co-mentions. “Who shares the recent high-relevance tape?” Near-duplicate registry rows often both appear (SpaceX + Space Exploration Technologies Corp., United States + United States of America). Collapse when briefing.

Attributes. Useful starting facts, not a fundamentals database. Companies are densest; commodities/countries often thin or empty. Lists are synonym-heavy. Can flip quickly off NER (e.g. CEO field updating with succession headlines) — treat as hypothesis to verify.

Works well for COMPANY, PERSON, COMMODITY, COUNTRY, GOVERNMENT. Products (e.g. "ChatGPT") often fail the activity gate.

Workflow

1. Choose the best canonical guess (full legal-style name for listed companies).
2. Call retrieve_entity. On insufficient_entity_activity, retry fuller forms before concluding the entity is quiet. On unresolved_entities, retry the best suggestion.
3. Brief from: recent wires → sentiment turn → co-mentions → attributes (facts to verify).
4. Hand off: Wire for monitoring/storylines; semantic search for evidence passages.

Limitations

• Realtime only — no as-of.
• One entity per call.
• Activity gate hides quiet names and punishes ambiguous short names.
• Public input is name only (passing entity_id as a string does not work).
• Recent strip is fixed at 5 non-duplicate high-relevance items.
• Attributes are NER aggregates: incomplete, contradictory, occasionally wrong.
• Co-mentions surface unmerged duplicate identities.
• Not a substitute for Wire novelty clustering or semantic passage retrieval.

FAQ

Q: Why does "Tesla" fail with insufficient_entity_activity but "Tesla, Inc." works?
A: Short "Tesla" matches a different sparse registry entity. Same trap as Wire’s empty [] on short names — here it surfaces as an activity 422.

Q: Can I pass TSLA or the numeric entity_id?
A: No. Tickers and id-strings → unresolved_entities. Use the canonical name.

Q: Why is Gold’s attribute COMPANY: Robinhood Markets, Inc.?
A: Attribute noise from document NER. Cross-check before citing.

Q: Why do SpaceX and “Space Exploration Technologies Corp.” both show as co-mentions?
A: Incomplete entity merges. Treat as one org in the narrative unless you need registry fidelity.

Q: Empty attributes on Brent / United States — broken?
A: Common for non-company types. Lean on wires + co-mentions instead.

Q: Are attributes filings-grade facts?
A: No. Verify material facts before citing.