---
title: "List runs"
method: GET
path: "/apps/{name}/runs"
---

# List runs

`GET /apps/{name}/runs`

Generates a list of all the runs for a given app. The list is paginated based on the query string parameters passed in.

## Path parameters

- `name` string, required — The name of the app to fetch runs for.

## Query parameters

- `page` integer — The page number to fetch.
- `page_size` integer — The number of records to fetch on each page.
- `status` string[] — Filter runs by status(es). Define multiple with a comma-separated list. Supplying none will return all statuses.
- `start_at` string, date-time — Filter runs scheduled after or at this datetime (inclusive)
- `end_at` string, date-time — Filter runs scheduled before or at this datetime (inclusive)
- `environment` string — Filter runs by environment. If not provided, all environments will be included.

## Response `200`

OK

- ListRunsResponse
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `pages` Pagination, required
    - `num_pages` integer, required
    - `page` integer, required
    - `page_size` integer, required
    - `total` integer, required
  - `runs` 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
          - `schedule_name` string — The name of the schedule that initiated this run, if type is 'tower_schedule'
        - object
          - `run_app_name` string — The name of the app that initiated this run, if type is 'tower_run'
          - `run_number` integer — The number of the run that initaited this run, if type is 'tower_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.

## 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)