Alerts

Alerts wrap an existing Ultralayer endpoint, poll it on a schedule, skip what was already delivered, and push new matches to email, Telegram, and/or a webhook. Same filters and queries as the underlying endpoint — plus schedule and delivery. Alerts are billed as the underlying endpoint calls — there is no alert surcharge.

When to use

Use alerts when you need:

• Continuous monitoring of Wire, semantic search, developments, or events
• Delivery to inbox, Telegram, or a webhook without running your own cron
• The same conditions you already validated interactively, left running

Do not use alerts when you need:

• A one-shot answer → call the underlying endpoint directly
• To alert on endpoints that are not in the alertable set below

Use cases

Company wire monitor — Get emailed when a company prints material news with strong positive or negative tone, skipping copycat syndication.

Code
{
  "name": "Apple important news",
  "path": "/v0/search/list_wire",
  "arguments": {
    "entities": ["Apple Inc."],
    "novelty": ["new", "update", "correction"],
    "entity_relevance": ["primary", "significant"],
    "min_entity_sentiment": 0.3,
    "max_entity_sentiment": -0.3
  },
  "interval_minutes": 15,
  "threshold": 1,
  "receivers": [{ "type": "email" }]
}

Exact canonical names (see Wire). Sentiment min/max together = strong positive or strong negative. Novelty drops syndication duplicates.

Semantic Monitoring — Watch a theme by meaning (not just a ticker) and push new matching passages to email and a webhook.

Code
{
  "name": "Hormuz Oil Passages",
  "path": "/v0/search/semantic_search",
  "arguments": {
    "query": "Strait of Hormuz tanker disruption Brent crude",
    "top_k": 10,
    "utility_score_ge": 0.5,
    "cosine_similarity_ge": 0.7
  },
  "interval_minutes": 30,
  "receivers": [
    { "type": "email" },
    { "type": "webhook", "url": "https://hooks.example.com/ultralayer" }
  ]
}

Ticker development feed — Get pinged when important new developments land for a ticker, with who is affected already scored.

Code
{
  "name": "Tesla Developments",
  "path": "/v0/search/search_developments",
  "arguments": {
    "stakeholder_symbol": "TSLA",
    "min_importance_score": 0.7,
    "limit": 20
  },
  "interval_minutes": 30,
  "receivers": [{ "type": "telegram", "chat_id": "123456789" }]
}

Tracked event lifecycle — Follow one known story (earnings cycle, M&A, etc.) and get notified as new developments attach to it.

Code
{
  "name": "Tesla 2026 Financial Event",
  "path": "/v0/search/retrieve_event_developments",
  "arguments": {
    "event_id": 125,
    "limit": 20,
    "include_future_developments": true
  },
  "interval_minutes": 60,
  "lookback_minutes": 180,
  "receivers": [{ "type": "email" }]
}

Discover event_id via search_events or a development hit first.

Events scan (M&A) — Stay on top of new deal activity without polling for mergers yourself.

Code
{
  "name": "M&A Events",
  "path": "/v0/search/search_events",
  "arguments": {
    "event_type": "merger_acquisition",
    "developments_per_event": 1,
    "limit": 10
  },
  "interval_minutes": 60,
  "receivers": [{ "type": "email" }]
}

Alertable endpoints

Wire for company/news. Developments/events for structured lifecycle. Semantic search for thematic language.

Create params

Receivers

Envelope: { "name": "<alert name>", "response": <exact upstream JSON> }. Subject: ULTRALAYER ALERT: {name}.

create_alert immediately calls the endpoint and delivers a sample to every receiver before persisting.

Delivery behavior

Each run checks a rolling lookback window and never re-sends data already delivered. The alert fires only when at least threshold new items match. Attempt outcomes (delivered, no_data, below_threshold, endpoint_error, delivery_partial, delivery_failed) and recent deliveries are visible via get_alerts. If all receivers fail, the same data is retried next run.

There is no update-alert endpoint. Changing filters = delete + recreate.

Workflow

1. Prototype filters with the underlying endpoint until results look right.
2. create_alert with those arguments (no timestamps) + receivers + interval. Expect a sample delivery.
3. get_alerts to confirm status and early attempts.
4. execute_alert to force a test run. deactivate_alert / activate_alert to pause/resume.
5. delete_alert when done. Prefer pause over delete if the config may be reused.

Limitations

• Poll-based (minimum 5-minute cadence), not push-on-insert.
• Only the alertable paths listed above.
• Max 2 receivers; email is account-bound.
• Webhooks must be public.
• Create always sends a sample — warn before creating noisy webhooks.
• No patch API for existing alerts.

FAQ

Q: Is this more expensive than calling the API myself on a cron?
A: Same underlying pricing; you gain dedupe, thresholding, multi-channel delivery, history, and managed scheduling.

Q: Why can’t I set start_timestamp in arguments?
A: The alert owns the rolling window. Including timestamps → 422.

Q: Why did create email me immediately?
A: Receiver verification delivers a real sample by design.

Q: no_data every 15 minutes — broken?
A: Healthy. The window had zero matches. Check deliveries for real fires.

Q: How do I change an alert’s filters?
A: There is no patch. Pause or delete + recreate.