---
title: "Create Alert"
method: POST
path: "/v0/alert/create_alert"
tags: ["V0", "Alert", "HAS_MCP_EQUIVALENT"]
---

# Create Alert

`POST /v0/alert/create_alert`

## Request

- Base URL: `https://api.ultralayer.ai`
- URL: `https://api.ultralayer.ai/v0/alert/create_alert`
- Auth: HTTP bearer

Create an alert that periodically polls an endpoint and delivers new results to your configured receivers (webhook, email, and/or telegram).

## Request body

- AlertInstructions
  - `name` string, nullable: Unique label; auto-generated if omitted
  - `path` '/v0/search/list_wire' | '/v0/search/semantic_search' | '/v0/search/search_developments' | '/v0/search/retrieve_event_developments' | '/v0/search/search_events' | '/v0/filings/list_guidance' | '/v0/filings/list_changes' | '/v0/filings/list_guidance_outcomes', required: Endpoint the alert polls.
  - `arguments` object, required: Endpoint arguments, dont provide system timestamps.
  - `interval_minutes` integer, required: Poll interval; multiple of 5.
  - `lookback_minutes` integer, nullable: Defaults to interval_minutes
  - `threshold` integer: Items required to fire.
  - `receivers` union[], required: 1-2 unique targets.
    - union
      - WebhookReceiver
        - `type` 'webhook', required
        - `url` string, required
        - `headers` object, nullable: POST headers.
        - `body_wrap_key` string, nullable: Place the alert envelope under this body key. Dot-separated for one level of nesting (e.g. variables.PAYLOAD).
        - `body_wrap_as_string` boolean: JSON-encode the envelope to a string before placing it under body_wrap_key. Requires body_wrap_key.
        - `body_extra` object, nullable: Static keys merged into the top level of the body. String, number, boolean or null values only.
      - EmailReceiver
        - `type` 'email', required
      - TelegramReceiver
        - `type` 'telegram', required
        - `chat_id` string, required: Chat ID; start the alerts bot first.

## Response `200`

Successful Response

- AlertRecord
  - `alert_id` integer, required: Unique identifier for the alert.
  - `name` string, required: Human label for the alert.
  - `status` 'active' | 'paused', required: Current status of the alert.
  - `path` '/v0/search/list_wire' | '/v0/search/semantic_search' | '/v0/search/search_developments' | '/v0/search/retrieve_event_developments' | '/v0/search/search_events' | '/v0/filings/list_guidance' | '/v0/filings/list_changes' | '/v0/filings/list_guidance_outcomes', required: The endpoint the alert polls.
  - `arguments` object, required: The endpoint arguments.
  - `interval_minutes` integer, required: How often the alert checks the endpoint, in minutes.
  - `lookback_minutes` integer, required: Rolling lookback window, in minutes.
  - `threshold` integer, required: Minimum item count before the alert fires.
  - `receivers` union[], required: The configured delivery targets.
    - union
      - WebhookReceiver
        - `type` 'webhook', required
        - `url` string, required
        - `headers` object, nullable: POST headers.
        - `body_wrap_key` string, nullable: Place the alert envelope under this body key. Dot-separated for one level of nesting (e.g. variables.PAYLOAD).
        - `body_wrap_as_string` boolean: JSON-encode the envelope to a string before placing it under body_wrap_key. Requires body_wrap_key.
        - `body_extra` object, nullable: Static keys merged into the top level of the body. String, number, boolean or null values only.
      - EmailReceiver
        - `type` 'email', required
      - TelegramReceiver
        - `type` 'telegram', required
        - `chat_id` string, required: Chat ID; start the alerts bot first.
  - `last_triggered_end_timestamp` string, date-time, nullable, required: end_timestamp of the last successful delivery, or null.
  - `attempts` AlertAttempt[], required: Recent execution attempts (no payload).
    - `end_timestamp` string, date-time, required: End of the query window used (== the start the next run dedups against).
    - `execution_finished_at` string, date-time, required: When this execution finished.
    - `outcome` 'no_data' | 'below_threshold' | 'endpoint_error' | 'delivered' | 'delivery_partial' | 'delivery_failed', required: Terminal state of this execution.
    - `item_count` integer, required: Items found in the window (0 on no_data / endpoint_error).
  - `deliveries` AlertDelivery[], required: Recent deliveries (includes payload).
    - `end_timestamp` string, date-time, required: End of the query window used.
    - `delivered_at` string, date-time, required: Latest successful per-receiver delivery time.
    - `payload` object, required: The envelope that was delivered ({name, response}).
    - `receiver_results` ReceiverResult[], required: Per-receiver delivery outcomes.
      - `type` 'webhook' | 'email' | 'telegram', required: The receiver channel.
      - `target` string, required: Where it was delivered (webhook url, telegram chat id, or account email).
      - `status` 'success' | 'failed', required: Whether delivery to this receiver succeeded.
      - `delivered_at` string, date-time, nullable: When this receiver was successfully delivered to, or null on failure.
      - `error` string, nullable: Failure reason, or null on success.
  - `created_at` string, date-time, required: When the alert was created.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/ultralayer/apis/ultralayer-api.md) · [All operations](https://skmtc.dev/ultralayer/apis/ultralayer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ultralayer/apis/ultralayer-api/revisions/4185459222be?raw)