Alert History Import and Export API¶

The Robusta SaaS platform exposes several HTTP APIs for exporting data and sending alerts:

• API to export alerts - Export historical alert data

• API to fetch aggregate alert statistics - Get aggregated alert statistics

• API to send alerts - Send custom alerts programmatically

• API to send configuration changes - Track configuration changes

For a simpler webhook integration guide, see Custom Webhooks.

There is an quick-start Prometheus report-generator on GitHub that demonstrates how to use the export APIs.

GET https://api.robusta.dev/api/query/alerts¶

Use this endpoint to export alert history data. You can filter the results based on specific criteria using query parameters such as alert_name, account_id, and time range.

Query Parameters¶

Example Request¶

The following curl command demonstrates how to export alert history data for the CrashLoopBackoff alert:

curl --location 'https://api.robusta.dev/api/query/alerts?alert_name=CrashLoopBackoff&account_id=ACCOUNT_ID&start_ts=2024-09-02T04%3A02%3A05.032Z&end_ts=2024-09-17T05%3A02%3A05.032Z' \
--header 'Authorization: Bearer API-KEY'

In the command, make sure to replace the following placeholders:

• ACCOUNT_ID: Your account ID, which can be found in your generated_values.yaml file.

• API-KEY: Your API Key for authentication. You can generate this token in the platform by navigating to Settings -> API Keys -> New API Key, and creating a key with the "Read Alerts" permission.

Request Headers¶

Response Format¶

The API will return a list of alerts in JSON format. Each alert object contains detailed information about the alert, including the name, priority, source, and related resource information.

Example Response¶

[
    {
        "alert_name": "CrashLoopBackoff",
        "title": "Crashing pod api-gateway-123abc in namespace prod",
        "description": null,
        "source": "kubernetes_api_server",
        "priority": "HIGH",
        "started_at": "2024-09-03T04:09:31.342818+00:00",
        "resolved_at": null,
        "cluster": "prod-cluster-1",
        "namespace": "prod",
        "app": "api-gateway",
        "kind": null,
        "resource_name": "api-gateway-123abc",
        "resource_node": "gke-prod-cluster-1-node-1"
    },
    {
        "alert_name": "CrashLoopBackoff",
        "title": "Crashing pod billing-service-xyz789 in namespace billing",
        "description": null,
        "source": "kubernetes_api_server",
        "priority": "HIGH",
        "started_at": "2024-09-03T04:09:31.496713+00:00",
        "resolved_at": null,
        "cluster": "prod-cluster-2",
        "namespace": "billing",
        "app": "billing-service",
        "kind": null,
        "resource_name": "billing-service-xyz789",
        "resource_node": "gke-prod-cluster-2-node-3"
    }
]

Response Fields¶

GET https://api.robusta.dev/api/query/report¶

Use this endpoint to retrieve aggregated alert data, including the count of each type of alert during a specified time range. Filters can be applied using query parameters such as account_id and the time range.

Query Parameters¶

Example Request¶

The following curl command demonstrates how to query aggregated alert data for a specified time range:

curl --location 'https://api.robusta.dev/api/query/report?account_id=XXXXXX-XXXX_XXXX_XXXXX7&start_ts=2024-10-27T04:02:05.032Z&end_ts=2024-11-27T05:02:05.032Z' \
--header 'Authorization: Bearer API-KEY'

In the command, make sure to replace the following placeholders:

• account_id: Your account ID, which can be found in your generated_values.yaml file.

• API-KEY: Your API Key for authentication. Generate this token in the platform by navigating to Settings -> API Keys -> New API Key, and creating a key with the "Read Alerts" permission.

Request Headers¶

Response Format¶

The API will return a JSON array of aggregated alerts, with each object containing:

• `aggregation_key`: The unique identifier of the alert type (e.g., KubeJobFailed).

• `alert_count`: The total count of occurrences of this alert type within the specified time range.

Example Response¶

[
    {"aggregation_key": "KubeJobFailed", "alert_count": 17413},
    {"aggregation_key": "KubePodNotReady", "alert_count": 11893},
    {"aggregation_key": "KubeDeploymentReplicasMismatch", "alert_count": 2410},
    {"aggregation_key": "KubeDeploymentRolloutStuck", "alert_count": 923},
    {"aggregation_key": "KubePodCrashLooping", "alert_count": 921},
    {"aggregation_key": "KubeContainerWaiting", "alert_count": 752},
    {"aggregation_key": "PrometheusRuleFailures", "alert_count": 188},
    {"aggregation_key": "KubeMemoryOvercommit", "alert_count": 187},
    {"aggregation_key": "PrometheusOperatorRejectedResources", "alert_count": 102},
    {"aggregation_key": "KubeletTooManyPods", "alert_count": 94},
    {"aggregation_key": "NodeMemoryHighUtilization", "alert_count": 23},
    {"aggregation_key": "TargetDown", "alert_count": 19},
    {"aggregation_key": "test123", "alert_count": 7},
    {"aggregation_key": "KubeAggregatedAPIDown", "alert_count": 4},
    {"aggregation_key": "KubeAggregatedAPIErrors", "alert_count": 4},
    {"aggregation_key": "KubeMemoryOvercommitTEST2", "alert_count": 1},
    {"aggregation_key": "TestAlert", "alert_count": 1},
    {"aggregation_key": "TestAlert2", "alert_count": 1},
    {"aggregation_key": "dsafd", "alert_count": 1},
    {"aggregation_key": "KubeMemoryOvercommitTEST", "alert_count": 1},
    {"aggregation_key": "vfd", "alert_count": 1}
]

Response Fields¶

Notes¶

• Ensure that the start_ts and end_ts parameters are in ISO 8601 format and are correctly set to cover the desired time range.

• Use the correct Authorization token with sufficient permissions to access the alert data.

POST https://api.robusta.dev/api/alerts¶

Use this endpoint to send alert data to Robusta. You can send up to 1000 alerts in a single request.

Request Body Schema¶

The request body must include the following fields:

Each alert in the alerts list must follow the specific schema, which includes the following fields:

Example Request¶

Here is an example of a POST request to send a list of alerts:

curl --location --request POST 'https://api.robusta.dev/api/alerts' \
--header 'Authorization: Bearer API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "account_id": "ACCOUNT_ID",
    "alerts": [
        {
            "title": "Test Service Down",
            "description": "The Test Service is not responding.",
            "source": "monitoring-system",
            "priority": "high",
            "aggregation_key": "test-service-issues",
            "failure": true,
            "starts_at": "2024-10-07T10:00:00Z",
            "labels": {
                "environment": "production"
            },
            "annotations": {
                "env1": "true"
            },
            "cluster": "prod-cluster-1",
            "subject_namespace": "prod",
            "subject_node": "gke-prod-cluster-1-node-1"
        }
    ]
}'

In this request, replace the following placeholders:

• ACCOUNT_ID: Your account ID, which can be found in your generated_values.yaml file.

• API-KEY: Your API Key for authentication. You can generate this token by navigating to Settings -> API Keys -> New API Key.

Request Headers¶

Response Format¶

Success Response

If the request is successful, the API will return the following response:

{
    "success": true
}

• Status Code: 200 OK

Error Response

If there is an error in processing the request, the API will return the following format:

{
    "msg": "Error message here",
    "error_code": 123
}

• Status Code: Varies based on the error (e.g., 400 Bad Request, 500 Internal Server Error).

POST https://api.robusta.dev/api/config-changes¶

Use this endpoint to send configuration changes to Robusta. You can send up to 1000 configuration changes in a single request.

Request Body Schema¶

The request body must include the following fields:

Each configuration change in the config_changes list must follow the specific schema, which includes the following fields:

Example Request¶

Here is an example of a POST request to send a list of configuration changes:

curl --location --request POST 'https://api.robusta.dev/api/config-changes' \
--header 'Authorization: Bearer API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "account_id": "ACCOUNT_ID",
    "config_changes": [
        {
            "title": "Updated test-service deployment",
            "old_config": "apiVersion: apps/v1\nkind: Deployment\n....",
            "new_config": "apiVersion: apps/v1...",
            "resource_name": "test sercvice",
            "description": "Changed deployemnt",
            "source": "test-service",
            "cluster": "prod-cluster-1",
            "labels": {
                "environment": "production"
            },
            "annotations": {
                "env1": "true"
            },
            "subject_namespace": "prod",
            "subject_node": "gke-prod-cluster-1-node-1"
        }
    ]
}'

In this request, replace the following placeholders:

• ACCOUNT_ID: Your account ID, which can be found in your generated_values.yaml file.

• API-KEY: Your API Key for authentication. You can generate this token by navigating to Settings -> API Keys -> New API Key.

Request Headers¶

Response Format¶

Success Response

If the request is successful, the API will return the following response:

{
    "success": true
}

• Status Code: 200 OK

Error Response

If there is an error in processing the request, the API will return the following format:

{
    "msg": "Error message here",
    "error_code": 123
}

• Status Code: Varies based on the error (e.g., 400 Bad Request, 500 Internal Server Error).

POST https://api.robusta.dev/api/namespaces/resources¶

Use this endpoint to retrieve an active count of specific Kubernetes resources within a namespace. This is the same data displayed in the Namespaces tab of the Robusta UI.

You can specify exactly which resource kinds you want to query in the request.

This API relies on resource types configured in the Robusta UI sink. Make sure to configure them as described in Monitoring Specific Resources in Namespaces.

Request Body Schema¶

The request body must include the following fields:

Each item in the resources list must include:

• kind (e.g., Deployments)

• apiGroup (e.g., apps, or empty string for core group)

• apiVersion (e.g., v1, v2)

Example Request¶

Here is an example of a POST request to query the resource count in a namespace:

curl --location 'https://api.robusta.dev/api/namespaces/resources' \
--header 'Authorization: Bearer API-KEY-HERE' \
--header 'Content-Type: application/json' \
--data '{
  "namespace": "your-namespace",
  "account_id": "your-account-id",
  "cluster_name": "your-cluster-name",
  "resources": [
    {"kind": "Deployments", "apiGroup": "apps", "apiVersion": "v1"},
    {"kind": "Ingresses", "apiGroup": "networking.k8s.io", "apiVersion": "v1"},
    {"kind": "Services", "apiGroup": "", "apiVersion": "v1"},
    {"kind": "HorizontalPodAutoscalers", "apiGroup": "autoscaling", "apiVersion": "v2"},
    {"kind": "ReplicationControllers", "apiGroup": "", "apiVersion": "v1"}
  ]
}'

Replace:

• API-KEY-HERE with your API Key from Settings → API Keys → New API Key. Make sure the key has Clusters → Read permissions to access namespace resource data.

• your-account-id with the ID found in generated_values.yaml

• your-cluster-name and your-namespace accordingly

Response Format¶

Success Response

If the request is successful, the API returns the following structure:

{
    "cluster": "your-cluster-name",
    "namespace": "your-namespace",
    "resources": [
        {
            "apiGroup": "apps",
            "apiVersion": "v1",
            "count": 2,
            "kind": "Deployments"
        },
        {
            "apiGroup": "",
            "apiVersion": "v1",
            "count": 5,
            "kind": "Pods"
        },
        ...
    ]
}

• Status Code: 200 OK

Error Response

If an error occurs, you will receive a response in the following format:

{
    "msg": "Error message here",
    "error_code": 456
}

• Status Code: Varies depending on the error (e.g., 400, 403, 500)