Alerts Endpoint

The Alerts API allows you to manage cost alerts programmatically.

List Alerts

Get all configured alerts.

GET /v1/alerts

Query Parameters

Parameter	Type	Required	Description
org	string	No	Filter by organization
status	string	No	Filter: active, paused, triggered
type	string	No	Filter: threshold, anomaly

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.cicosts.dev/v1/alerts

Example Response

{
  "data": {
    "alerts": [
      {
        "id": "alert_abc123",
        "name": "Monthly Budget Alert",
        "type": "threshold",
        "status": "active",
        "scope": {
          "type": "organization",
          "org": "my-company"
        },
        "condition": {
          "metric": "monthly_cost",
          "operator": "greater_than",
          "value": 2000
        },
        "notifications": [
          {"type": "email", "target": "team@company.com"},
          {"type": "slack", "channel": "#ci-alerts"}
        ],
        "cooldown_hours": 24,
        "last_triggered_at": "2024-01-10T08:00:00Z",
        "created_at": "2023-12-01T00:00:00Z"
      }
    ]
  }
}

Get Alert Details

Get details for a specific alert.

GET /v1/alerts/:id

Example Response

{
  "data": {
    "id": "alert_abc123",
    "name": "Monthly Budget Alert",
    "type": "threshold",
    "status": "active",
    "scope": {
      "type": "organization",
      "org": "my-company"
    },
    "condition": {
      "metric": "monthly_cost",
      "operator": "greater_than",
      "value": 2000
    },
    "notifications": [
      {"type": "email", "target": "team@company.com"},
      {"type": "slack", "channel": "#ci-alerts"}
    ],
    "cooldown_hours": 24,
    "trigger_history": [
      {
        "triggered_at": "2024-01-10T08:00:00Z",
        "value_at_trigger": 2015.67,
        "resolved_at": null
      }
    ],
    "created_at": "2023-12-01T00:00:00Z",
    "updated_at": "2024-01-05T10:00:00Z"
  }
}

Create Alert

Create a new alert.

POST /v1/alerts

Request Body

{
  "name": "Daily Spike Alert",
  "type": "anomaly",
  "scope": {
    "type": "organization",
    "org": "my-company"
  },
  "condition": {
    "metric": "daily_cost",
    "operator": "percent_increase",
    "value": 50,
    "baseline": "7_day_average"
  },
  "notifications": [
    {"type": "email", "target": "devops@company.com"}
  ],
  "cooldown_hours": 4
}

Alert Types

Threshold Alert:

{
  "type": "threshold",
  "condition": {
    "metric": "daily_cost",
    "operator": "greater_than",
    "value": 100
  }
}

Anomaly Alert:

{
  "type": "anomaly",
  "condition": {
    "metric": "daily_cost",
    "operator": "percent_increase",
    "value": 20,
    "baseline": "7_day_average"
  }
}

Scope Types

// Organization scope
{
  "scope": {
    "type": "organization",
    "org": "my-company"
  }
}

// Repository scope
{
  "scope": {
    "type": "repository",
    "org": "my-company",
    "repo": "api-service"
  }
}

// Workflow scope
{
  "scope": {
    "type": "workflow",
    "workflow_id": "wf_abc123"
  }
}

Metrics

Metric	Description
daily_cost	Cost for the current day
weekly_cost	Cost for the current week
monthly_cost	Cost for the current month
per_run_cost	Average cost per workflow run

Operators

Operator	Description
greater_than	Value exceeds threshold
less_than	Value below threshold
percent_increase	Percentage increase from baseline
percent_decrease	Percentage decrease from baseline

Example Response

{
  "data": {
    "id": "alert_def456",
    "name": "Daily Spike Alert",
    "status": "active",
    "created_at": "2024-01-15T12:00:00Z"
  }
}

Update Alert

Update an existing alert.

PUT /v1/alerts/:id

Request Body

Include only fields you want to update:

{
  "name": "Updated Alert Name",
  "status": "paused",
  "condition": {
    "value": 2500
  }
}

Example Response

{
  "data": {
    "id": "alert_abc123",
    "name": "Updated Alert Name",
    "status": "paused",
    "updated_at": "2024-01-15T12:00:00Z"
  }
}

Delete Alert

Delete an alert.

DELETE /v1/alerts/:id

Example Request

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.cicosts.dev/v1/alerts/alert_abc123

Example Response

{
  "data": {
    "deleted": true,
    "id": "alert_abc123"
  }
}

Test Alert

Trigger a test notification for an alert.

POST /v1/alerts/:id/test

Example Request

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.cicosts.dev/v1/alerts/alert_abc123/test

Example Response

{
  "data": {
    "test_sent": true,
    "notifications": [
      {"type": "email", "status": "sent"},
      {"type": "slack", "status": "sent"}
    ]
  }
}

---

Next: Webhooks Endpoint →