Wire

The Wire is Ultralayer’s structured news firehose: short, fact-dense headlines with novelty links, entity mentions, sector/asset tagging, and trust/importance scores. Public surface exposes metadata + headline only (no article body).

When to use

Use the Wire when you need to:

• Scan what is moving now (earnings, guidance, geopolitics, rates, M&A)
• Monitor a company, commodity, country, sector, or publisher
• Deduplicate the firehose via novelty (new / update vs duplicate)
• Reconstruct how a story evolved (updates, corrections, cross-publisher copies)
• Backtest a window with start_timestamp / end_timestamp
• Build alert-ready conditions (wire alerts take the same filter fields, minus timestamps)

Do not use the Wire when you need:

• Open-web research (article body, quotes, filings, prices) → your native web search tool
• A full entity package → retrieve_entity
• Semantic “find similar stories by meaning” — list_wire is filter/recency, not embedding search

Use cases

Realtime desk scan — See the latest material earnings and guidance prints without the syndication noise.

{
  "max_records": 25,
  "novelty": ["new", "update", "correction"],
  "categories": ["earnings", "guidance"],
  "min_importance_score": 0.5,
  "min_trustworthiness_score": 0.7
}

Company name watch — Pull only headlines where a specific company is a primary or major subject.

{
  "max_records": 20,
  "entities": ["Tesla, Inc."],
  "entity_relevance": ["primary", "significant"],
  "novelty": ["new", "update", "correction"]
}

Strong ± sentiment on a name — Surface mentions that are clearly bullish or bearish on the company, not mild noise.

{
  "entities": ["easyJet plc"],
  "entity_relevance": ["primary", "significant"],
  "min_entity_sentiment": 0.3,
  "max_entity_sentiment": -0.3,
  "max_records": 20
}

Geopolitics → commodities — Catch geopolitics that matter for energy and commodities.

{
  "max_records": 20,
  "sectors": ["energy"],
  "asset_classes": ["commodities"],
  "categories": ["geopolitics"],
  "novelty": ["new", "update"],
  "min_importance_score": 0.5
}

Issuer originals only — Read what the company itself released, not second-hand rewrites.

{
  "content_type": ["press_release"],
  "source_relationship": ["first_party"],
  "novelty": ["new", "update", "correction"],
  "max_records": 20
}

Scheduled / future events — Find upcoming earnings and policy dates, not just what already printed.

{
  "recency": ["report_of_future"],
  "categories": ["earnings", "monetary"],
  "max_records": 20
}

Backtest a window — Reconstruct what looked important during a specific trading session.

{
  "start_timestamp": "2026-07-21T14:00:00Z",
  "end_timestamp": "2026-07-21T18:00:00Z",
  "novelty": ["new", "update"],
  "min_importance_score": 0.6,
  "max_records": 50
}

Storyline with syndication — See how a story evolved and which outlets copied it.

{
  "wire_id": 67337,
  "novelty": ["new", "update", "duplicate", "correction"]
}

Response detail

Both 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 in the agent context (wire lists can be large).

Exact wire percentages are not published yet; treat essential as the big cut and standard as the usual cite-ready middle. Prefer detail: "standard" for normal agent calls. Use essential for dense scans; use full when you need scores, about, or full entity identifiers.

{
  "max_records": 25,
  "novelty": ["new", "update", "correction"],
  "detail": "standard"
}

What you get back

Each item is a compact decision object. Headlines are usually one dense sentence with numbers, entities, and the delta.

Prefer novelty: ["new","update","correction"] and max_records 10–30 with tight filters.

list_wire

Returns up to max_records (1–100, default 20) matching items, newest by source_timestamp. Pass detail (default full; prefer standard — see detail above).

Filtration vs sort

• Filters apply on timestamp (wire clock).
• Response order is source_timestamp descending.
• A tight time window can include items whose source time looks slightly outside the window. Prefer slightly wider windows when backtesting.

Future end_timestamp values are treated as realtime (no upper bound).

Novelty

Default monitoring set: ["new", "update", "correction"] — cuts roughly half the firehose noise from cross-publisher copies while keeping beats and fixes.

Example: Lundbeck FDA Fast Track — pr_newswire item novelty=new, Reuters copy minutes later novelty=duplicate with prior_wire_id → the PR.

Entity filter

entities is include-any.

Pair with entity_relevance and min_entity_sentiment / max_entity_sentiment. When both sentiment bounds are set, min must be greater than max (directional OR: strong positive or strong negative).

Sentiment bounds apply to the matching mention, not the whole item.

Other high-value filters

Filters combine with AND across dimensions; within multi-value arrays, include-any (OR).

Keep filter lists tight: across categories, entities, sectors, industries, countries, asset_classes, and publisher, at most 12 values total are allowed in one request.

wire_storyline

Given a wire_id, returns the novelty storyline: linear prior_wire_id ancestors plus first-degree children of every chain node.

{
  "seed_wire_id": 67583,
  "root_wire_id": 49200,
  "items": [ ]
}

Items are chronological by source_timestamp ascending.

Topology

1. Walk seed → prior_wire_id → … until root, time-window break, or max_ancestor_depth.
2. Ancestors are walked even through duplicates so the chain stays connected; novelty filtering is applied when projecting the response (seed always kept).
3. Children: only direct children of chain nodes, capped by max_children.
4. root_wire_id is set only if the walk reached a row with prior_wire_id: null. root_wire_id: null means truncated (time window or depth).
5. Seed outside the requested time window → 404. Unknown wire_id → 404.

Default novelty trap

wire_storyline defaults to novelty: ["new", "update", "correction"] — duplicates excluded. That hides cross-publisher fanout.

• Default: good for “how did the story evolve?”
• Include "duplicate" when you need “who else printed this?”

Example — easyJet earnings: default novelty → only the Reuters new seed; with duplicates → Reuters + Bloomberg + FT copies.

Example — earnings correction chain: new → correction → update → later conflicting correction. Storyline is how you catch conflicting prints.

Example — multi-day geopolitics: seed linked through consecutive updates to a root days earlier; a tight time window truncates the chain and returns root_wire_id: null.

Workflow

1. Clarify scope (entity / sector / theme / time).
2. list_wire with novelty new|update|correction, an importance floor, and the tightest true filters.
3. Pick the highest-importance hit → wire_storyline (add duplicate if coverage breadth matters).
4. Brief from headlines + novelty path; escalate to your native web search tool (or the URL) for body text.

Limitations

• No full article text on the public wire surface.
• publisher, industries, and categories are messy real-world strings.
• Storyline is shallow by design (linear ancestors + one hop of children).
• Unfiltered list_wire is noisy — bias novelty + importance.
• importance_score is relative rank, not a guarantee.

FAQ

Q: Why doesn’t storyline show Bloomberg/FT copies?
A: Default novelty drops duplicate. Add it explicitly.

Q: root_wire_id is null but items exist.
A: Ancestry was truncated by time window or max_ancestor_depth. Widen start_timestamp, raise the depth cap, or treat as a partial chain.

Q: Sort order looks wrong vs IDs.
A: list_wire sorts by source_timestamp desc, not wire_id. Filtration still uses timestamp.

Q: list_wire vs alerts?
A: Same filter vocabulary. The Wire is the pull API; a wire alert matches each new item against those conditions as it lands and delivers it.