Creates an alert, first checked at the next quarter past the hour.
Guide: Alerts
| Status | type | code | When |
|---|---|---|---|
| 400 | invalid_request | invalid_analytics_alert | For a rule that could not run, or a project already at 25 alerts. |
It can also fail with the errors every operation shares, such as unauthenticated; see Errors.
Something wrong or missing on this page? Tell us by email or on Discord.
A project secret key: vh_sk_... for production, vh_sk_test_... for test. Keep it on your servers.
In: header
The project's id, proj_.... A secret key works only in the project it belongs to.
application/json
TypeScript definitions
Use the request body type in TypeScript.
The alert's name, 1 to 255 characters.
1 <= length <= 255What the alert watches: event_count fires when an event happens at least threshold times to at least minPeople people; failure_share fires when the share of attempts that failed is clearly above threshold, an attempt being eventName (the failure) or successEventName; volume_drop fires when an event falls by at least threshold against the median of the same window in the four weeks before.
Value in
The event to count or watch, up to 256 characters; for failure_share, the event of a failed attempt.
1 <= length <= 256The event of an attempt that worked, different from eventName. Required for failure_share, and only allowed there.
The trailing window each check reads, in hours: 1, 6, 24 or 168 (7 days).
-9007199254740991 <= value <= 9007199254740991When the alert fires: for event_count a whole count of at least 1; for failure_share and volume_drop a share greater than 0 and less than 1, such as 0.2 for 20%.
The distinct people an event_count alert's events must come from: at least 1, and 2 when omitted. Only allowed for event_count.
curl -X POST "https://api.voidhash.com/api/v1/projects/proj_tz4a98xxat96iws9zmbrgj3a/analytics/alerts" \ -H "Authorization: Bearer vh_sk_..." \ -H "Content-Type: application/json" \ -d '{ "name": "Workout sync failing", "kind": "failure_share", "eventName": "workout_sync_failed", "successEventName": "workout_sync_completed", "windowHours": 24, "threshold": 0.2 }'{ "id": "alert_k3v9m2x7c1q8w4e6r0t5y2u8", "projectId": "proj_tz4a98xxat96iws9zmbrgj3a", "name": "Workout sync failing", "kind": "failure_share", "eventName": "workout_sync_failed", "successEventName": "workout_sync_completed", "windowHours": 24, "threshold": 0.2, "minPeople": null, "isEnabled": true, "state": "pending", "value": null, "baseline": null, "baselineWeeks": null, "checkedThrough": null, "firingSince": null, "createdAt": "2026-03-05T12:00:00.000Z"}{ "error": { "type": "invalid_request", "code": "invalid_analytics_alert", "message": "A project can have 25 alerts. Delete one to add another." }}{ "error": { "type": "unauthenticated", "code": "invalid_api_key", "message": "This secret key is not valid." }}{ "error": { "type": "permission_denied", "code": "permission_denied", "message": "Insufficient permissions." }}{ "error": { "type": "not_found", "code": "project_not_found", "message": "There is no project proj_tz4a98xxat96iws9zmbrgj3a, or this credential cannot use it.", "param": "projectId" }}{ "error": { "type": "internal", "code": "internal_error", "message": "Something went wrong on our side. Try again, and contact support with the Request-Id header if it keeps failing." }}application/json
application/json
application/json
application/json
application/json
application/json