---
title: "Detect anomaly alerts for your timeseries"
method: POST
path: "/api/v1/alerts"
---

# Detect anomaly alerts for your timeseries

`POST /api/v1/alerts`

Finds alerts related to the provided metadata.

This is a synchronous billed endpoint — you are charged per alert returned.
No charge is recorded on validation errors or upstream failures.

## Request body

- AlertsRequestV1 — Body of `POST /api/v1/alerts`. `filters.limit` controls how many alerts are returned (default **100**, max **1000**). `date_from` / `date_to` are optional date bounds (YYYY-MM-DD).
  - `context_enriched` boolean, required — When true, treat the supplied metadata as already context-enriched.
  - `date_from` string — Optional start date bound for alert detection (YYYY-MM-DD).
  - `date_to` string — Optional end date bound for alert detection (YYYY-MM-DD).
  - `filters` Filters — Optional narrowing for forecast, drivers, and alerts requests. Category and region ids must fall in **1–9999**. Discover valid ids via `GET /api/v1/regions` and `GET /api/v1/categories` — submitted ids are not cross-checked on submit.
    - `categories` integer[] — Thematic category ids to filter by; each must be an integer **1–9999** inclusive.
    - `general_drivers` boolean — When true, general (non category/region-specific) drivers are included in the driver candidate pool. Defaults to false.
    - `limit` integer — Maximum number of items to return. When omitted, a per-environment default is applied (100 by default). The maximum accepted value is operator-configurable (default 1000).
    - `regions` integer[] — Geographic region ids to filter by; each must be an integer **1–9999** inclusive.
  - `metadata` TimeseriesMetadata, required — Descriptive metadata the ranking model uses to interpret and contextualize the timeseries.
    - `description` string — Extended context for the model, up to 2048 characters. More detail improves driver relevance.
    - `keywords` string[] — Up to 20 semantic tags that help anchor the search to relevant datasets.
    - `title` string, required — Short identifier for the series, 20–511 characters.

## Response `200`

Alerts detected for your timeseries, ordered by relevance.

- object
  - `alerts` AlertItemV1[]
    - `name` string — Human-readable name of the dataset or index that triggered the alert.
    - `news` NewsItemV1[] — Related news articles driving this alert.
      - `category` string — Topical category of the article (e.g. `world`, `business`, `energy`).
      - `description` string — Short summary of the article.
      - `published_at` string, date-time — Publication timestamp (RFC 3339 / ISO 8601).
      - `source_name` string — Name of the publication or media outlet.
      - `title` string — Headline of the news article.
      - `trending` boolean — Whether this article is currently trending across the platform.
      - `url` string, uri — Canonical URL of the article.
    - `pct_change` number, double — Percentage change that triggered the alert (negative = decline, positive = surge).
    - `trending` boolean — Whether this alert is currently trending across the platform.

## Other responses

- `400` — Malformed JSON body.
- `401` — Missing or invalid bearer token.
- `402` — Insufficient credits — the request did not reach the upstream service.
- `413` — Request body too large.
- `422` — Payload failed validation.
- `429` — Rate limit exceeded — too many synchronous billed requests per minute.
- `502` — Upstream service error or unreachable.
- `503` — Service Unavailable

---

[API](https://skmtc.net/sybilion/apis/sybilion-api.md) · [All operations](https://skmtc.net/sybilion/apis/sybilion-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sybilion/sybilion-api/versions/2ba1f4c6f25d/schema)