Get Alert By Plan Id

11 min

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 <your_access_token>.
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

{
  "data": [
    {
      "id": 173,
      "planId": 766,
      "alertType": "EMAIL",
      "target": "[email protected]",
      "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": "[email protected]",
      "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:

{
  "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.

{
  "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

{
  "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

curl --location '{gateway-url}/alerts/plan/{planId}' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'X-Company-Id: <company_id>'