---
title: "List health actions for an agent"
method: GET
path: "/api/v1/agents/{agent}/agent_health_actions"
---

# List health actions for an agent

`GET /api/v1/agents/{agent}/agent_health_actions`

Returns all health actions associated with a given agent. Health actions
represent required or recommended steps — such as setting environment
variables, completing OAuth installations, or running custom verifiers —
that an agent needs to reach a healthy state.

Results are not paginated; the full list for the agent is returned. Use
the `source`, `status`, and `kind` filters to narrow results to the
subset your UI or workflow needs. Multiple values for the same filter
are treated as OR (e.g. passing two statuses returns actions matching
either). The caller must be authenticated and scoped to the app that
owns the agent.

## Path parameters

- `agent` string, required

## Query parameters

- `source` string[]
- `status` string[]
- `kind` string[]

## Response `200`

Successful response

- HealthActionListResponse — List response containing agent health actions for a given agent or organization.
  - `data` AgentHealthAction[], required — Array of agent health action objects representing setup checklist items and probe-detected issues.
    - `agent` string — ID of the agent this action is scoped to (`agt_...`). `null` for org-level actions.
    - `app` string — ID of the application this action is associated with (`app_...`). `null` when not app-scoped.
    - `created_at` string, date-time — When this health action was first created (ISO 8601).
    - `depends_on` string[] — IDs of other health actions that must reach `"completed"` status before this action can be started. Empty array when there are no dependencies.
    - `description` string — Longer Markdown-formatted explanation of what the action requires and why. `null` if not provided.
    - `id` string, required — Health action ID (`aha_...`).
    - `kind` string, required — Category of action to take. One of `"env_var"` (set a secret), `"install"` (authorize an OAuth integration), or `"custom"` (agent-defined step).
    - `last_verified_at` string, date-time — When the verifier last ran for this action (ISO 8601). `null` until the verifier has been invoked at least once.
    - `last_verifier_message` string — Human-readable output from the most recent verifier run. `null` if the verifier has not run yet.
    - `org` string — ID of the organization this action is associated with (`org_...`). `null` when not org-scoped.
    - `params` object — Kind-specific structured data used to construct the deep-link for this action. For `"env_var"` actions includes `key` and `scope`; for `"install"` actions includes `installation_kind`. Empty object `{}` when no additional parameters are needed.
    - `required` boolean, required — `true` if this action must be completed before the agent is considered fully operational and counts toward the blocking checklist progress bar.
    - `sort_order` integer, required — Display order within the same `source` group. Lower values appear first.
    - `source` string, required — Lifecycle stage that produced this action. One of `"setup"` (post-install checklist item) or `"health"` (probe-detected issue).
    - `status` string, required — Current resolution state. One of `"pending"` (not yet completed), `"completed"` (resolved), `"skipped"` (dismissed by the user), or `"degraded"` (completed but the verifier is reporting a warning).
    - `title` string, required — Short display label for this action, intended for use as a checklist item heading.
    - `updated_at` string, date-time — When this health action was last modified (ISO 8601).
    - `verify_config` object — Configuration for the action's verifier step. Contains at minimum a `type` field that indicates which verification affordance to render. Server-internal fields are stripped before this is returned.

## Other responses

- `401` — Unauthorized
- `403` — App-scoped token required. Use a token scoped to the target app.; Forbidden
- `404` — Agent not found

---

[API](https://skmtc.dev/archastro/apis/archastro-platform-api.md) · [All operations](https://skmtc.dev/archastro/apis/archastro-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/archastro/archastro-platform-api/revisions/a8772b442f86/schema)