---
title: "List alerts"
method: GET
path: "/alerts"
---

# List alerts

`GET /alerts`

List alerts for the current account with optional filtering

## Query parameters

- `page` integer — The page number to fetch.
- `page_size` integer — The number of records to fetch on each page.
- `alert_type` string — Filter alerts by alert type
- `start_at` string, date-time — Filter alerts created after or at this datetime (inclusive)
- `end_at` string, date-time — Filter alerts created before or at this datetime (inclusive)
- `acked` string — Filter alerts by acknowledged status.
- `environment` string — Filter alerts by environment (e.g., production, staging)

## Response `200`

OK

- ListAlertsResponse
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `alerts` Alert[], required — List of alerts
    - `acked` boolean, required
    - `alert_type` string, required
    - `created_at` string, date-time, required
    - `detail` object, required
      - `app` App, required
        - `created_at` string, date-time, required — The date and time this app was created.
        - `health_status` 'healthy' | 'warning', required — This property is deprecated. It will always be 'healthy'.
        - `is_example` boolean, required — Whether this app was deployed from the Tower examples catalog.
        - `is_externally_accessible` boolean, required
        - `last_run` Run
          - `$link` string, required — $link is deprecated. Individual responses include links.
          - `app_name` string, required
          - `app_slug` string — This property is deprecated. Use app_name instead.
          - `app_version` string, required
          - `attempts` RunAttempt[] — Previous attempt details. Populated on describe, omitted on list.
            - `ended_at` string, date-time, nullable, required — When this attempt ended.
            - `exit_code` integer, nullable, required — Exit code for this attempt.
            - `seq` integer, required — 1-based attempt number.
            - `started_at` string, date-time, nullable, required — When the run started executing your code.
            - `starting_at` string, date-time, nullable, required — When the runner environment started to get setup.
            - `status` string, required — Terminal status of this attempt.
          - `cancelled_at` string, date-time, nullable, required
          - `created_at` string, date-time, required
          - `created_by` RunCreator
            - `name` string, required — The creator's name: a user's full name (or email) or a service account's name.
            - `type` 'user' | 'service_account', required — The kind of principal that created the run.
          - `ended_at` string, date-time, nullable, required
          - `environment` string, required
          - `exit_code` integer, nullable, required — Exit code of the run, if the run is completed. Null if there is no exit code
          - `hostname` string — hostname is deprecated, use subdomain
          - `initiator` RunInitiator, required
            - `details` union, required — Additional information about the initiator of a run.
              - …
            - `type` string, nullable, required — The type of initiator for this run. Null if none or unknown.
          - `is_scheduled` boolean, required — Whether this run was triggered by a schedule (true) or on-demand (false). Historical records default to false.
          - `num_attempts` integer, required — Number of attempts for this run (1 = original, 2+ = retries).
          - `number` integer, required
          - `parameters` RunParameter[], required — Parameters used to invoke this run.
            - `hidden` boolean — Whether this parameter is hidden/secret. Defaults to false.
            - `is_override` boolean, nullable — Whether this parameter's value was supplied as an override at run/schedule creation time (true) or comes from the app version's default (false).
            - `name` string, required
            - `value` string, required
          - `retry_policy` RunRetryPolicy
            - `max_retries` integer, required
            - `retry_delay_seconds` integer, required
            - `use_exponential_backoff` boolean, required
          - `run_id` string, required
          - `scheduled_at` string, date-time, required
          - `started_at` string, date-time, nullable, required — When the run started executing your code.
          - `starting_at` string, date-time, nullable, required — When the runner environment started to get setup.
          - `status` 'scheduled' | 'retrying' | 'pending' | 'starting' | 'running' | 'crashed' | 'errored' | 'exited' | 'cancelled', required
          - `status_group` 'successful' | 'failed' | '', required
          - `subdomain` string, nullable — If app is externally accessible, then you can access this run with this hostname.
        - `name` string, required — The name of the app.
        - `next_run_at` string, date-time, nullable, required — The next time this app will run as part of it's schedule, null if none.
        - `owner` string, required — The account slug that owns this app.
        - `pending_timeout` integer, required — The maximum time in seconds that a run can stay in the pending state before being marked as cancelled.
        - `retry_policy` RunRetryPolicy
          - `max_retries` integer, required
          - `retry_delay_seconds` integer, required
          - `use_exponential_backoff` boolean, required
        - `run_results` RunResults
          - `cancelled` integer, required
          - `crashed` integer, required
          - `errored` integer, required
          - `exited` integer, required
          - `pending` integer, required
          - `retrying` integer, required
          - `running` integer, required
          - `starting` integer, required
        - `running_timeout` integer, required — The number of seconds that a run can stay running before it gets cancelled. Value of 0 (default) means no timeout.
        - `schedule` string, nullable, required — The schedule associated with this app, null if none.
        - `short_description` string, required — A short description of the app. Can be empty.
        - `slug` string — This property is deprecated. Use name instead.
        - `status` 'active' | 'disabled' — The status of the app.
        - `subdomain` string — The subdomain that this app is accessible via. Must be externally accessible first.
        - `tags` AppTag[] — The tags applied to the app.
          - `name` string, required
          - `value` string, required
        - `version` string, nullable, required — The current version of this app, null if none.
      - `environment` string, required — Environment this run was in
      - `run` Run, required
        - `$link` string, required — $link is deprecated. Individual responses include links.
        - `app_name` string, required
        - `app_slug` string — This property is deprecated. Use app_name instead.
        - `app_version` string, required
        - `attempts` RunAttempt[] — Previous attempt details. Populated on describe, omitted on list.
          - `ended_at` string, date-time, nullable, required — When this attempt ended.
          - `exit_code` integer, nullable, required — Exit code for this attempt.
          - `seq` integer, required — 1-based attempt number.
          - `started_at` string, date-time, nullable, required — When the run started executing your code.
          - `starting_at` string, date-time, nullable, required — When the runner environment started to get setup.
          - `status` string, required — Terminal status of this attempt.
        - `cancelled_at` string, date-time, nullable, required
        - `created_at` string, date-time, required
        - `created_by` RunCreator
          - `name` string, required — The creator's name: a user's full name (or email) or a service account's name.
          - `type` 'user' | 'service_account', required — The kind of principal that created the run.
        - `ended_at` string, date-time, nullable, required
        - `environment` string, required
        - `exit_code` integer, nullable, required — Exit code of the run, if the run is completed. Null if there is no exit code
        - `hostname` string — hostname is deprecated, use subdomain
        - `initiator` RunInitiator, required
          - `details` union, required — Additional information about the initiator of a run.
            - object
              - …
            - object
              - …
          - `type` string, nullable, required — The type of initiator for this run. Null if none or unknown.
        - `is_scheduled` boolean, required — Whether this run was triggered by a schedule (true) or on-demand (false). Historical records default to false.
        - `num_attempts` integer, required — Number of attempts for this run (1 = original, 2+ = retries).
        - `number` integer, required
        - `parameters` RunParameter[], required — Parameters used to invoke this run.
          - `hidden` boolean — Whether this parameter is hidden/secret. Defaults to false.
          - `is_override` boolean, nullable — Whether this parameter's value was supplied as an override at run/schedule creation time (true) or comes from the app version's default (false).
          - `name` string, required
          - `value` string, required
        - `retry_policy` RunRetryPolicy
          - `max_retries` integer, required
          - `retry_delay_seconds` integer, required
          - `use_exponential_backoff` boolean, required
        - `run_id` string, required
        - `scheduled_at` string, date-time, required
        - `started_at` string, date-time, nullable, required — When the run started executing your code.
        - `starting_at` string, date-time, nullable, required — When the runner environment started to get setup.
        - `status` 'scheduled' | 'retrying' | 'pending' | 'starting' | 'running' | 'crashed' | 'errored' | 'exited' | 'cancelled', required
        - `status_group` 'successful' | 'failed' | '', required
        - `subdomain` string, nullable — If app is externally accessible, then you can access this run with this hostname.
    - `seq` integer, required
    - `status` string, required
  - `pages` Pagination, required
    - `num_pages` integer, required
    - `page` integer, required
    - `page_size` integer, required
    - `total` integer, required

## Other responses

- `default` — Error

---

[API](https://skmtc.net/tower/apis/tower-api.md) · [All operations](https://skmtc.net/tower/apis/tower-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tower/tower-api/revisions/0e42b0fb26d9/schema)