Create alert configuration

curl --request POST \
  --url https://api.unusualwhales.com/api/alerts/configuration \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input": "add @energy where calls and volume > 100",
  "name": "Energy call sweeps",
  "noti_type": "flow_alerts"
}
'

import requests

url = "https://api.unusualwhales.com/api/alerts/configuration"

payload = {
    "input": "add @energy where calls and volume > 100",
    "name": "Energy call sweeps",
    "noti_type": "flow_alerts"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    input: 'add @energy where calls and volume > 100',
    name: 'Energy call sweeps',
    noti_type: 'flow_alerts'
  })
};

fetch('https://api.unusualwhales.com/api/alerts/configuration', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unusualwhales.com/api/alerts/configuration",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'input' => 'add @energy where calls and volume > 100',
    'name' => 'Energy call sweeps',
    'noti_type' => 'flow_alerts'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unusualwhales.com/api/alerts/configuration"

	payload := strings.NewReader("{\n  \"input\": \"add @energy where calls and volume > 100\",\n  \"name\": \"Energy call sweeps\",\n  \"noti_type\": \"flow_alerts\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.unusualwhales.com/api/alerts/configuration")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": \"add @energy where calls and volume > 100\",\n  \"name\": \"Energy call sweeps\",\n  \"noti_type\": \"flow_alerts\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unusualwhales.com/api/alerts/configuration")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input\": \"add @energy where calls and volume > 100\",\n  \"name\": \"Energy call sweeps\",\n  \"noti_type\": \"flow_alerts\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "config": {
      "expression": {
        "op": "and",
        "terms": [
          {
            "sectors": [
              "Energy"
            ]
          },
          {
            "op": "and",
            "terms": [
              {
                "is_call": true
              },
              {
                "compare": {
                  "lhs": {
                    "field": "volume"
                  },
                  "op": "gt",
                  "rhs": {
                    "literal": "100"
                  }
                }
              }
            ]
          }
        ]
      },
      "symbols": "all"
    },
    "created_at": "2025-07-01T14:00:00.000Z",
    "dsl": "@Energy where calls and volume > 100",
    "id": "ebe24953-a0bf-4b4d-98be-14f721a1199a",
    "name": "Energy call sweeps",
    "noti_type": "flow_alerts",
    "status": "active"
  }
}

{
  "msg": "Invalid path input: MSFT12 (valid example: AAPL) - Invalid query input(s): date=2023-02-140 (valid example: date=2024-01-18)",
  "path": "/api/darkpool/MSFT12",
  "query": "date=2023-02-140",
  "url": "localhost:4000/api/darkpool/MSFT12?date=2023-02-140"
}

{
  "code": "authentication_required",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "expected_format": "uuid",
  "message": "The API token provided is not in the expected format. Unusual Whales API tokens are UUIDs, such as 123e4567-e89b-12d3-a456-426614174000.",
  "reason": "malformed_token",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "code": "payment_required",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "message": "This API token is paused because the payment for your API subscription failed. Update your card at https://unusualwhales.com/settings. The same token works again once a payment succeeds.",
  "reason": "payment_failed",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "code": "missing_access",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "message": "The API token provided is valid but is not permitted to access this route.",
  "reason": "route_not_permitted",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "msg": "Invalid path input: MSFT12 (valid example: AAPL) - Invalid query input(s): date=2023-02-140 (valid example: date=2024-01-18)",
  "path": "/api/darkpool/MSFT12",
  "query": "date=2023-02-140",
  "url": "localhost:4000/api/darkpool/MSFT12?date=2023-02-140"
}

{
  "msg": "Invalid path input: MSFT12 (valid example: AAPL) - Invalid query input(s): date=2023-02-140 (valid example: date=2024-01-18)",
  "path": "/api/darkpool/MSFT12",
  "query": "date=2023-02-140",
  "url": "localhost:4000/api/darkpool/MSFT12?date=2023-02-140"
}

alerts

Create alert configuration

Creates a new alert configuration, or updates an existing one when id is given.

The alert filters can be given in one of two ways, but never both:

config: a structured filter object for the given noti_type, the same configuration as returned by the alert configurations endpoint.
input: a Query language expression. Use the Query language for complex filter expressions.

Before creating an alert fetch the available filters:

GET /api/alerts/filters lists per alert type (noti_type) the filter fields that can be used in config, their accepted values, and whether your account can create alerts of that type.
GET /api/alerts/query/grammar returns the Query language syntax. GET /api/alerts/query/grammar?target=option_trade the full field reference for one target.

Example with a structured config:

{
  "name": "FED news",
  "noti_type": "news",
  "config": {"symbols": "all", "contains": ["FED"]}
}

Example with a Query language input:

{
  "name": "Energy sector calls",
  "noti_type": "flow_alerts",
  "input": "add @energy where calls and volume > 100 and (dte > 10 or (dte = 0 and ticker = 'XOM'))"
}

The created alerts are delivered like the alerts created on https://unusualwhales.com/custom-alerts and their triggers can be fetched from the alerts endpoint or streamed over the custom_alerts websocket channel.

The alerts and usage of the websocket are the easiest way to setup and get notified on anything that matches your filter configs. The query language is a powerful tool to create complex configurations in a SQL like language.

POST

api

alerts

configuration

Create alert configuration

curl --request POST \
  --url https://api.unusualwhales.com/api/alerts/configuration \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input": "add @energy where calls and volume > 100",
  "name": "Energy call sweeps",
  "noti_type": "flow_alerts"
}
'

import requests

url = "https://api.unusualwhales.com/api/alerts/configuration"

payload = {
    "input": "add @energy where calls and volume > 100",
    "name": "Energy call sweeps",
    "noti_type": "flow_alerts"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    input: 'add @energy where calls and volume > 100',
    name: 'Energy call sweeps',
    noti_type: 'flow_alerts'
  })
};

fetch('https://api.unusualwhales.com/api/alerts/configuration', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unusualwhales.com/api/alerts/configuration",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'input' => 'add @energy where calls and volume > 100',
    'name' => 'Energy call sweeps',
    'noti_type' => 'flow_alerts'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unusualwhales.com/api/alerts/configuration"

	payload := strings.NewReader("{\n  \"input\": \"add @energy where calls and volume > 100\",\n  \"name\": \"Energy call sweeps\",\n  \"noti_type\": \"flow_alerts\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.unusualwhales.com/api/alerts/configuration")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": \"add @energy where calls and volume > 100\",\n  \"name\": \"Energy call sweeps\",\n  \"noti_type\": \"flow_alerts\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unusualwhales.com/api/alerts/configuration")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input\": \"add @energy where calls and volume > 100\",\n  \"name\": \"Energy call sweeps\",\n  \"noti_type\": \"flow_alerts\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "config": {
      "expression": {
        "op": "and",
        "terms": [
          {
            "sectors": [
              "Energy"
            ]
          },
          {
            "op": "and",
            "terms": [
              {
                "is_call": true
              },
              {
                "compare": {
                  "lhs": {
                    "field": "volume"
                  },
                  "op": "gt",
                  "rhs": {
                    "literal": "100"
                  }
                }
              }
            ]
          }
        ]
      },
      "symbols": "all"
    },
    "created_at": "2025-07-01T14:00:00.000Z",
    "dsl": "@Energy where calls and volume > 100",
    "id": "ebe24953-a0bf-4b4d-98be-14f721a1199a",
    "name": "Energy call sweeps",
    "noti_type": "flow_alerts",
    "status": "active"
  }
}

{
  "msg": "Invalid path input: MSFT12 (valid example: AAPL) - Invalid query input(s): date=2023-02-140 (valid example: date=2024-01-18)",
  "path": "/api/darkpool/MSFT12",
  "query": "date=2023-02-140",
  "url": "localhost:4000/api/darkpool/MSFT12?date=2023-02-140"
}

{
  "code": "authentication_required",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "expected_format": "uuid",
  "message": "The API token provided is not in the expected format. Unusual Whales API tokens are UUIDs, such as 123e4567-e89b-12d3-a456-426614174000.",
  "reason": "malformed_token",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "code": "payment_required",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "message": "This API token is paused because the payment for your API subscription failed. Update your card at https://unusualwhales.com/settings. The same token works again once a payment succeeds.",
  "reason": "payment_failed",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "code": "missing_access",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "message": "The API token provided is valid but is not permitted to access this route.",
  "reason": "route_not_permitted",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "msg": "Invalid path input: MSFT12 (valid example: AAPL) - Invalid query input(s): date=2023-02-140 (valid example: date=2024-01-18)",
  "path": "/api/darkpool/MSFT12",
  "query": "date=2023-02-140",
  "url": "localhost:4000/api/darkpool/MSFT12?date=2023-02-140"
}

{
  "msg": "Invalid path input: MSFT12 (valid example: AAPL) - Invalid query input(s): date=2023-02-140 (valid example: date=2024-01-18)",
  "path": "/api/darkpool/MSFT12",
  "query": "date=2023-02-140",
  "url": "localhost:4000/api/darkpool/MSFT12?date=2023-02-140"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Alert configuration

Create alert config request
Create alert config request

Creates a new alert configuration, or updates an existing one when id is given.

The alert filters can be given in one of two ways, but never both:

config: a structured filter object for the given noti_type. Fetch the available filter fields per alert type from GET /api/alerts/filters.
input: a DSL expression such as add @energy where calls and volume > 100. Fetch the DSL grammar from GET /api/alerts/query/grammar. The noti_type field is required for DSL expressions.

config

The configuration of an alert. · object

required

An alert configuration, there is no fixed schema for this as each alert will have a different configuration.

Example:

{
  "config": {
    "option_symbols": ["TGT241122C00177500"],
    "symbols": "all"
  }
}

name

string

required

Example:

"Chain OI Chg: TGT241122C00177500"

noti_type

string

required

Example:

"chain_oi_change"

string<uuid>

When given, updates the existing alert configuration with this id instead of creating a new one.

input

string

A DSL expression describing the alert filters. Use instead of config for complex filter expressions. See the DSL grammar endpoint for the syntax.

Example:

"where calls and volume > 100 and premium > 10000"

status

enum<string>

Available options:

active,

rate_limit,

paused

Example:

"active"

Response

The created or updated alert configuration

data

object

required

Show child attributes

Docs

Endpoints

Create alert configuration

Authorizations

Body

Response