Skip to main content

Alerts Endpoint

The Alerts API allows you to manage cost alerts programmatically. Set up budget thresholds and anomaly detection to stay on top of your CI/CD spending.

List Alerts​

Get all alerts for an organization.

GET /api/v1/alerts

Parameters​

ParameterTypeRequiredDescription
org_idUUIDYesOrganization ID

Example Request​

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.cicosts.dev/api/v1/alerts?org_id=your-org-id"

Example Response​

{
  "alerts": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Monthly Budget Alert",
      "alert_type": "budget",
      "threshold_amount": 500.00,
      "check_frequency": "daily",
      "notify_email": true,
      "enabled": true,
      "created_at": "2025-01-15T12:00:00Z",
      "updated_at": "2025-01-15T12:00:00Z"
    }
  ]
}

Get Alert Details​

Get details for a specific alert including trigger history.

GET /api/v1/alerts/{id}

Example Response​

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Monthly Budget Alert",
  "alert_type": "budget",
  "threshold_amount": 500.00,
  "check_frequency": "daily",
  "notify_email": true,
  "enabled": true,
  "org_id": "org-uuid",
  "created_at": "2025-01-15T12:00:00Z",
  "updated_at": "2025-01-15T12:00:00Z"
}

Create Alert​

Create a new alert.

POST /api/v1/alerts

Parameters​

ParameterTypeRequiredDescription
org_idUUIDYesOrganization ID (query param)

Request Body​

{
  "name": "Daily Spend Limit",
  "alert_type": "budget",
  "threshold_amount": 50.00,
  "check_frequency": "daily",
  "notify_email": true,
  "enabled": true
}

Alert Types​

TypeDescription
budgetTriggers when spending exceeds threshold
anomalyTriggers on unusual spending patterns

Check Frequencies​

FrequencyDescription
dailyCheck once per day
weeklyCheck once per week
monthlyCheck once per month

Example Request​

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Budget Alert",
    "alert_type": "budget",
    "threshold_amount": 50.00,
    "check_frequency": "daily",
    "notify_email": true,
    "enabled": true
  }' \
  "https://api.cicosts.dev/api/v1/alerts?org_id=your-org-id"

Example Response​

{
  "id": "new-alert-uuid",
  "name": "Daily Budget Alert",
  "alert_type": "budget",
  "threshold_amount": 50.00,
  "check_frequency": "daily",
  "notify_email": true,
  "enabled": true,
  "created_at": "2025-01-15T12:00:00Z"
}

Update Alert​

Update an existing alert.

PUT /api/v1/alerts/{id}

Request Body​

Include any fields you want to update:

{
  "name": "Updated Alert Name",
  "threshold_amount": 75.00,
  "enabled": false
}

Example Response​

{
  "id": "alert-uuid",
  "name": "Updated Alert Name",
  "alert_type": "budget",
  "threshold_amount": 75.00,
  "check_frequency": "daily",
  "notify_email": true,
  "enabled": false,
  "updated_at": "2025-01-15T14:00:00Z"
}

Delete Alert​

Delete an alert.

DELETE /api/v1/alerts/{id}

Example Request​

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.cicosts.dev/api/v1/alerts/alert-uuid"

Example Response​

{
  "message": "Alert deleted successfully"
}

Get Trigger History​

Get the history of when an alert was triggered.

GET /api/v1/alerts/{id}/triggers

Example Response​

{
  "triggers": [
    {
      "id": "trigger-uuid",
      "alert_id": "alert-uuid",
      "triggered_at": "2025-01-15T08:00:00Z",
      "current_value": 52.45,
      "threshold_value": 50.00,
      "notified": true
    },
    {
      "id": "trigger-uuid-2",
      "alert_id": "alert-uuid",
      "triggered_at": "2025-01-14T08:00:00Z",
      "current_value": 55.20,
      "threshold_value": 50.00,
      "notified": true
    }
  ]
}

Manually Check Alert​

Manually trigger an alert check (useful for testing).

POST /api/v1/alerts/{id}/check

Example Request​

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.cicosts.dev/api/v1/alerts/alert-uuid/check"

Example Response​

{
  "checked": true,
  "triggered": false,
  "current_value": 45.20,
  "threshold_value": 50.00
}

If the alert triggers:

{
  "checked": true,
  "triggered": true,
  "current_value": 52.45,
  "threshold_value": 50.00,
  "notification_sent": true
}

Notification Delivery​

When an alert triggers, notifications are sent based on your configuration:

Email Notifications​

If notify_email is true, an email is sent to organization owners and admins who have alert notifications enabled in their settings.

The email includes:

  • Alert name
  • Current spending value
  • Threshold that was exceeded
  • Link to the dashboard

Slack Notifications​

If your organization has a Slack webhook configured, alerts are also sent to Slack with a formatted message including the same details.

Best Practices​

Start Conservative​

Begin with higher thresholds and adjust down as you understand your spending patterns:

{
  "name": "Monthly Budget",
  "alert_type": "budget",
  "threshold_amount": 1000.00,
  "check_frequency": "daily"
}

Use Multiple Alerts​

Set up tiered alerts for different thresholds:

  • 80% of budget - early warning
  • 100% of budget - at limit
  • 120% of budget - over budget

Combine with Anomaly Detection​

Use both budget and anomaly alerts:

// Budget alert for absolute limits
{
  "name": "Hard Budget Limit",
  "alert_type": "budget",
  "threshold_amount": 500.00
}

// Anomaly alert for unusual spikes
{
  "name": "Spending Spike Detection",
  "alert_type": "anomaly",
  "threshold_amount": 50.00  // % increase threshold
}

Next: Webhooks Endpoint →