--- title: Get Alert By Plan Id slug: suite-documentation/get-alert-by-plan-id docTags: createdAt: 2026-08-26T09:10:30.649Z --- ## Endpoint Information - **URL**: `{gateway-url}/alerts/plan/{planId}` - **Method**: `GET` - **Authentication**: Required (`Bearer Token`) - **Company Header**: Required (`X-Company-Id`) ## Headers | Header | Type | Required | Description | | --------------- | ------ | -------- | ---------------------------------------------------------------------------- | | `Authorization` | String | Yes | Bearer token used for authentication. Example: `Bearer `. | | `X-Company-Id` | Long | Yes | The company ID used to scope the request. | | `Accept` | String | No | Recommended value: `application/json`. | ## Path Parameters | Parameter | Type | Required | Description | | --------- | ---- | -------- | -------------------------------------------------------------------------------------- | | `planId` | Long | Yes | The unique ID of the test plan whose alerts will be listed. Must be a positive number. | ## Request Body This endpoint does not require a request body. ## Response Body ```json { "data": [ { "id": 173, "planId": 766, "alertType": "EMAIL", "target": "demo@testinium.com", "targetId": null, "targetType": null, "alertSendingStatus": "Beginning of the Each Execution", "alertSendingStatusResult": null, "language": null, "targetTimeZone": null, "enabled": true, "unsubscribeLinkEliminated": false }, { "id": null, "planId": 766, "alertType": "EMAIL", "target": "demo@testinium.com", "targetId": null, "targetType": null, "alertSendingStatus": "End of the Each Execution", "alertSendingStatusResult": [ { "id": 171, "name": "Test Successful" }, { "id": 172, "name": "Test Failed" } ], "language": null, "targetTimeZone": null, "enabled": true, "unsubscribeLinkEliminated": false } ] } ``` If no alert exists for the plan, the endpoint returns an empty list: ```json { "data": [] } ``` ## Response Fields | Parameter | Type | Description | | ---------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `data` | Array of objects | List of alert configurations for the test plan. | | `data[].id` | Long | Unique ID of the alert. For grouped end-of-execution alerts, this value can be `null`; individual alert IDs are listed under `alertSendingStatusResult`. | | `data[].planId` | Long | The ID of the related test plan. | | `data[].alertType` | String | Type of alert. Example values: `EMAIL`, `SLACK`. | | `data[].target` | String | Alert recipient. For email alerts, this is usually an email address. For Slack alerts, this can represent the selected Slack target. | | `data[].targetId` | String | Optional ID of the target, mainly used for Slack targets. | | `data[].targetType` | String | Optional target type. Example values: `USER`, `CHANNEL`. | | `data[].alertSendingStatus` | String | Defines when the alert will be triggered. Example values: `Beginning of the Each Execution`, `End of the Each Execution`. | | `data[].alertSendingStatusResult` | Array of objects | Result statuses for end-of-execution alerts. Returns `null` for beginning-of-execution alerts. | | `data[].alertSendingStatusResult[].id` | Long | Unique ID of the alert record for the related result status. | | `data[].alertSendingStatusResult[].name` | String | Result status name. Example values: `Test Successful`, `Test Failed`, `Test Unexecuted`, `Test Stopped`, `Test Error`, `Test Timed Out`. | | `data[].language` | String | Language code for the alert content, if configured. | | `data[].targetTimeZone` | String | Time zone value for the alert target, if configured. | | `data[].enabled` | Boolean | Indicates whether the alert is enabled. | | `data[].unsubscribeLinkEliminated` | Boolean | Indicates whether the unsubscribe link is eliminated for the alert. | ## Behavior Notes - This endpoint retrieves alerts configured for the given test plan. - The service first validates the test plan by calling the project service. - Alert lookup is scoped by `X-Company-Id`. - Alerts are grouped by `target` and `alertSendingStatus`. - For `End of the Each Execution` alerts, multiple result-based alert records are grouped under `alertSendingStatusResult`. - For grouped end-of-execution alerts, the top-level `id` can be `null` because each result status has its own alert ID. - If the plan exists but has no alerts, the response returns `data` as an empty array. - The response does not include `result.code` or `result.message`. ## Error Response Format Error responses use the common problem detail format. ```json { "instance": "/alerts/plan/999999", "status": 404, "title": "Not Found", "type": "https://errors.testinium.com/exception", "timestamp": "2026-08-18T12:08:41.165927056Z", "errorType": "EXCEPTION", "errors": { "code": 10003, "message": "Plan with id 999999 not found!" } } ``` ## Validation Error Response Example ```json { "instance": "/alerts/plan/0", "status": 400, "title": "Bad Request", "type": "https://errors.testinium.com/validation", "timestamp": "2026-08-18T12:08:41.165927056Z", "errorType": "VALIDATION", "errors": [ { "code": 20005, "message": "must be greater than 0", "field": "planId" } ] } ``` ## Error Codes | HTTP Code | Error Message | Description | | --------- | ----------------------- | -------------------------------------------------------------------------------------------- | | 400 | `BAD_REQUEST` | The request is malformed, contains invalid path parameters, or a required header is missing. | | 401 | `UNAUTHORIZED` | Authentication failed, authentication is required, or the token is invalid. | | 403 | `FORBIDDEN` | The user does not have permission to access the requested company or resource. | | 404 | `NOT_FOUND` | The requested test plan could not be found. | | 405 | `METHOD_NOT_ALLOWED` | The HTTP method is not supported. This endpoint only supports `GET`. | | 503 | `SERVICE_UNAVAILABLE` | The routed notification service or downstream project service is unavailable. | | 500 | `INTERNAL_SERVER_ERROR` | An unexpected error occurred on the server side. | ## Application Error Codes | Code | Error Type | HTTP Code | Description | | ------- | ------------ | --------- | ----------------------------------------------------------------------------------------------------- | | `10000` | `EXCEPTION` | 401 | Authentication failed. | | `10001` | `EXCEPTION` | 401 | Authentication is required to access this resource. | | `10002` | `EXCEPTION` | 401 | The provided token is invalid. | | `10003` | `EXCEPTION` | 403 / 404 | The user is not authorized for the requested resource, or the requested test plan could not be found. | | `10004` | `EXCEPTION` | 400 | A required header is missing. For example, `X-Company-Id` is not provided. | | `10005` | `EXCEPTION` | 401 | A required token claim is missing. | | `10007` | `EXCEPTION` | 403 / 503 | The user does not have access to the requested resource, or a downstream service is unavailable. | | `10008` | `EXCEPTION` | 503 | The routed notification service is unavailable. | | `20005` | `VALIDATION` | 400 | The `planId` path parameter is invalid. For example, it is not a positive number. | | `20008` | `EXCEPTION` | 400 | The `planId` path parameter has an invalid type. | | `20009` | `EXCEPTION` | 405 | The HTTP method is not supported. | ## Example Request ```bash curl --location '{gateway-url}/alerts/plan/{planId}' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --header 'X-Company-Id: ' ```