---
title: "Retrieve an agent's health profile"
method: GET
path: "/api/v1/agents/{agent}/health"
---

# Retrieve an agent's health profile

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

Returns an aggregate health profile for the specified agent, including an overall
status, a numeric health score, recent activity metrics, and a list of recommended
remediation actions.

The health check is computed on demand at request time. The `checked_at` timestamp
in the response reflects when the evaluation ran. Use this endpoint to surface
diagnostics about tool availability, model configuration, and runtime activity in
dashboards or monitoring workflows.

The authenticated caller must own the agent or hold sufficient permissions within
its owning org or team. When called under a developer app scope, the caller must
hold the app scope for the target app.

## Path parameters

- `agent` string, required

## Response `200`

Successful response

- AgentHealth — Aggregate health profile for an agent, summarizing its current operational status, score, and the full list of setup and health actions.
  - `activity` object, required — Timestamps for the agent's most recent and next scheduled activity, used to surface last-run and upcoming-run information.
  - `agent` Agent, required — An AI agent that can be configured with tools, routines, and skills, and invoked to handle conversations or tasks.
    - `acl` Acl — An access-control list payload that supports either full replacement or targeted patch operations on a resource's grants.
      - `add` AclGrant[] — Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.
        - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
        - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.
        - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
      - `grants` AclGrant[] — Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`.
        - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
        - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.
        - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
      - `remove` AclRemoveTarget[] — Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.
        - `principal` string — The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.
        - `principal_type` string, required — The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
    - `app` string — ID of the application that owns this agent (`dap_...`).
    - `created_at` string, date-time — When the agent was created (ISO 8601).
    - `default_model` string — Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `"claude-3-7-sonnet-latest"`).
    - `email` string — Email address provisioned for this agent. `null` if email delivery is not configured.
    - `id` string, required — Agent ID (`agi_...`).
    - `identity` string — System-level identity prompt that shapes the agent's persona and behavior.
    - `last_applied_template_config` string — ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.
    - `lookup_key` string — Stable, user-defined identifier for this agent within the application. Unique per app.
    - `metadata` object — Arbitrary key-value metadata attached to the agent. Not interpreted by the platform.
    - `name` string — Human-readable display name for the agent. `null` if not set.
    - `org` string — ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.
    - `org_name` string — Display name of the organization this agent belongs to. `null` when the agent is not org-scoped or when the org association was not preloaded.
    - `originator` string — Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).
    - `phone_number` string — Phone number provisioned for this agent. `null` if SMS is not configured.
    - `sandbox` string — ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.
    - `source_solution` AgentSourceSolution — Summary of the Solution and AgentTemplate that an agent was last provisioned from. Returned on single-agent responses; `null` for hand-built agents and agents whose tracked template or parent Solution has been deleted.
      - `solution` SolutionSummary, required — A catalog entry for an imported Solution, including its display metadata, bundled templates, owner scopes, and any available upgrade information.
        - `category_keys` string[] — Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.
        - `created_at` string, date-time — When the Solution config was first imported (ISO 8601).
        - `description` string — Short tagline or summary declared in the Solution body, used as the card subhead in catalog UIs. `null` when the Solution body does not set one.
        - `id` string, required — Solution config ID (`cfg_...`).
        - `kind` string, required — Resource type. Always `"Solution"`.
        - `latest_solution` string — When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.
        - `latest_version` string — When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.
        - `lookup_key` string — The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.
        - `metadata` object — Arbitrary key-value metadata declared in the Solution body (e.g. category or display hints). Present as an empty object when the body declares none.
        - `name` string — Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.
        - `org` string — Organization ID (`org_...`) that owns this Solution config, when the Solution is scoped to a specific org. `null` for system-scope (app-level) Solutions.
        - `org_logo` ImageSource — Resolved metadata for an image, including its delivery URL, dimensions, and optional references to the underlying storage file or media record.
          - `file` string — ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.
          - `height` integer — Height of the image in pixels. `null` if not known.
          - `media` string — ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.
          - `mime_type` string — MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.
          - `refresh_url` string — Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.
          - `url` string — Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.
          - `width` integer — Width of the image in pixels. `null` if not known.
        - `org_name` string — Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.
        - `org_slug` string — Resolved slug of the Solution body's `org` (the publishing organization), when set and it resolves to a real org visible to the viewer. When present this is the Solution's principal catalog category key — clients group the Solution under this org ahead of `category_keys`. `null` when the body has no `org` or it doesn't resolve.
        - `owners` string[], required — Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer's org scope).
        - `readme_url` string — Relative path to the public README endpoint with a signed token already embedded. `null` when the Solution has no README. Token expires in 1 hour — refresh via `GET /api/v1/solutions/:solution`.
        - `solution_id` string — Stable UUID declared in the Solution body, used to identify the same logical Solution across multiple installed copies and owner scopes. `null` when the body omits it.
        - `solution_version` string — Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version.
        - `tag_keys` string[] — Freeform tag keys declared in the Solution body. An empty array when the body declares none.
        - `template_kind` string — Wrapped template kind — `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles.
        - `templates` SolutionTemplateSummary[], required — Template configs bundled by this Solution, in declaration order — the first entry is the deployable template the Solution wraps; the rest are sibling templates the wrapped template references.
          - `description` string — Short prose blurb from the template body's `description:` field. `null` when the body doesn't set one. Used as the card subhead in the Library carousel.
          - `display_name` string — Human-facing label from the template body's `display_name:` field. `null` when the body doesn't set one. Library carousels use this for the card title, falling back to a humanized `name`.
          - `id` string — Template config ID (`cfg_...`). `null` for inline-only templates.
          - `kind` string, required — Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved.
          - `lookup_key` string — Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.
          - `name` string — Canonical name from the template body. For `AgentTemplate` this doubles as the human-facing label; for `AgentToolTemplate` it's the LLM-facing tool function identifier (snake_case); for `AgentRoutineTemplate` it's the routine identifier (kebab-case). Clients rendering carousels should prefer `display_name` and fall back to humanizing `name`.
          - `readme_url` string — Relative path to the public README endpoint with a signed token already embedded, scoped to this template's bundled markdown asset. `null` when the Solution body's `templates[].readme_path` is unset for this entry. Token expires in 1 hour — refresh via `GET /api/v1/solutions/:solution`.
          - `virtual_path` string — Stable virtual path assigned to the template config. `null` when no virtual path was set.
        - `updated_at` string, date-time — When the Solution config was last modified (ISO 8601).
        - `upgrade_available` boolean, required — `true` when this Solution is installed at the viewer's org scope and the app-level system scope carries a higher `solution_version`. Always `false` for system-only rows.
        - `virtual_path` string — The stable virtual path assigned to this Solution config, used as the deduplication key when the same Solution appears under multiple owner scopes. `null` when unset.
      - `template` UpgradeTemplateSummary, required — Compact summary of an AgentTemplate config referenced by an agent upgrade or source-solution response.
        - `created_at` string, date-time — When this template config was created (ISO 8601).
        - `description` string — Description of the template from the config body. `null` if the current version has no `description` field.
        - `display_name` string — Human-readable display name from the config body. `null` if the current version has no `display_name` field.
        - `id` string, required — Template config ID (`cfg_...`).
        - `kind` string, required — Config kind identifier for this template (e.g. `"agent_tool_template"`).
        - `lookup_key` string — Stable lookup key assigned to this template config. `null` if no lookup key is set.
        - `name` string — Template name as stored in the config body. `null` if the current version has no `name` field.
        - `updated_at` string, date-time — When this template config was last modified (ISO 8601).
        - `virtual_path` string — Virtual filesystem path for this template config. `null` if not set.
    - `team` string — ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.
    - `updated_at` string, date-time — When the agent was last modified (ISO 8601).
    - `user` string — ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.
  - `checked_at` string, date-time, required — When the health profile was last computed (ISO 8601).
  - `checks` object[], required — Renderable health check results. Each object includes at minimum `key`, `label`, `status`, and `summary` fields.
  - `counts` object, required — Action counts broken down by dependency area and resolution status, used to render progress indicators per category.
  - `health_actions` AgentHealthAction[], required — All actionable items tracked for this agent, including both `"setup"` items (post-install checklist) and `"health"` items (probe-detected issues). Sorted by `(source, sort_order, id)`. Use each item's `params` field to construct deep-links that route the user to the correct resolution flow.
    - `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.
  - `recent` object, required — Recent execution metrics for the agent, including run counts and failure counts over a recent time window.
  - `score` integer, required — Normalized health score from `0` (fully degraded) to `100` (fully healthy), derived from the weight and status of all health actions.
  - `status` string, required — Overall health status of the agent. One of `"ok"`, `"warning"`, or `"critical"`.

## Other responses

- `401` — Unauthorized
- `403` — Forbidden - app scope required
- `404` — Agent not found

---

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