--- title: List Agent Health issues description: List Agent Health issues across your organization. breadcrumbs: Docs > API > List Agent Health issues --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # List Agent Health issues ## v2 (latest) {% alert level="warning" %} **Note**: This endpoint is in preview and is subject to change. If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help.md). {% /alert %} | Datadog site | API endpoint | | ----------------- | ----------------------------------------------------------- | | app.datadoghq.com | GET https://api.datadoghq.com/api/v2/agenthealth/issues | | us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/agenthealth/issues | | us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/agenthealth/issues | | app.datadoghq.eu | GET https://api.datadoghq.eu/api/v2/agenthealth/issues | | ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/agenthealth/issues | | ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/agenthealth/issues | | uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/api/v2/agenthealth/issues | | app.ddog-gov.com | GET https://api.ddog-gov.com/api/v2/agenthealth/issues | | us2.ddog-gov.com | GET https://api.us2.ddog-gov.com/api/v2/agenthealth/issues | ### Overview List Agent Health issues across your organization. Only open issues are returned. Returns `403` if you lack the `hosts_read` permission. Results use a stable order: severity rank (`high`, `medium`, `low`, then other values), then `first_seen_at` descending with missing timestamps last, then issue ID ascending. Use `page[size]` and the zero-based `page[number]` to paginate. Invalid page values return a `400` JSON:API error response. `meta.page.total_filtered_count` is the number of issues matching the filters, and `meta.page.total_count` the number of open issues in the organization. Each filter accepts up to 50 comma-separated exact values of at most 256 characters each, combined with OR within a filter and AND across filters. Blank entries are ignored; an all-blank filter is treated as absent. This endpoint requires the `hosts_read` permission. OAuth apps require the `hosts_read` authorization [scope](https://docs.datadoghq.com/api/latest/scopes.md#agent-health) to access this endpoint. ### Arguments #### Query Strings | Field | Type | Description | | --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | page[size] | integer | The number of issues to return per page, from 1 to 100. Defaults to 25. Default: `25`. | | page[number] | integer | The zero-based page number, from 0 to 1000000. Defaults to 0. Default: `0`. | | filter[severity] | string | Filter by a comma-separated list of exact `severity` values, up to 50 values of at most 256 characters each. Values are combined with OR within this filter and AND across filters. Blank entries are ignored; an all-blank filter is treated as absent. | | filter[category] | string | Filter by a comma-separated list of exact `category` values, up to 50 values of at most 256 characters each. Values are combined with OR within this filter and AND across filters. Blank entries are ignored; an all-blank filter is treated as absent. | | filter[issue_type] | string | Filter by a comma-separated list of exact `issue_type` values, up to 50 values of at most 256 characters each. Values are combined with OR within this filter and AND across filters. Blank entries are ignored; an all-blank filter is treated as absent. | | filter[resource_kind] | string | Filter by a comma-separated list of exact `resource_kind` values, up to 50 values of at most 256 characters each. Values are combined with OR within this filter and AND across filters. Blank entries are ignored; an all-blank filter is treated as absent. | | filter[resource_id] | string | Filter by a comma-separated list of exact `resource_id` values, up to 50 values of at most 256 characters each. Values are combined with OR within this filter and AND across filters. Blank entries are ignored; an all-blank filter is treated as absent. | ### Response {% tabs %} {% tab label="200" %} OK {% tabs %} {% tab label="Model" %} A paginated response containing open Agent Health issues. | Parent field | Field | Type | Description | | ------------ | --------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | [object] | The open Agent Health issues on this page. | | data | attributes [*required*] | object | Attributes of an open Agent Health issue. | | attributes | category | string | The category of the issue, such as `configuration`. Omitted when not set. | | attributes | description | string | The description of the issue. Omitted when empty. | | attributes | first_seen_at | date-time | The time the issue was first seen, in RFC 3339 format. Omitted when empty. | | attributes | issue_name [*required*] | string | The human-readable name of the issue. | | attributes | issue_type [*required*] | string | The machine-readable type of the issue. | | attributes | resource_id [*required*] | string | The identifier of the affected resource, interpreted according to `resource_kind`: hostname for `host`, DaemonSet UID for `deployment` (node Agent), cluster UUID for `cluster`, hostname of the host running the Cluster Agent for `cluster_agent`, or OpenTelemetry collector ID for `otel`. | | attributes | resource_kind [*required*] | string | The kind of affected resource. Known values are `host`, `deployment`, `cluster`, `cluster_agent`, and `otel`. | | attributes | resource_type | string | The type of the affected resource. Omitted when empty. | | attributes | severity [*required*] | string | The severity of the issue. Known values are `low`, `medium`, `high`, and `unknown`. | | attributes | state [*required*] | string | The state of the issue. Only issues with state `open` are returned. | | attributes | tags | [string] | Tags associated with the issue. Omitted when empty. | | attributes | title | string | The title of the issue. Omitted when empty. | | attributes | updated_at | date-time | The time the issue was last updated, in RFC 3339 format. Omitted when empty. | | data | id [*required*] | string | The unique identifier of the issue. | | data | type [*required*] | enum | The Agent Health issue resource type. Allowed enum values: `agent_health_issues`. | | | meta [*required*] | object | Pagination metadata for the matching Agent Health issues. | | meta | page [*required*] | object | Pagination counts for the Agent Health issues. | | page | total_count [*required*] | int64 | The total number of open issues in the organization, ignoring filters. | | page | total_filtered_count [*required*] | int64 | The total number of open issues matching the filters, across all pages. | {% /tab %} {% tab label="Example" %} ```json { "data": [ { "attributes": { "category": "configuration", "description": "The Agent configuration file contains an invalid value.", "first_seen_at": "2026-11-01T10:00:00Z", "issue_name": "Invalid Config", "issue_type": "invalid_config", "resource_id": "my-hostname", "resource_kind": "host", "resource_type": "host", "severity": "high", "state": "open", "tags": [ "env:prod" ], "title": "Invalid Agent configuration", "updated_at": "2026-11-09T08:00:00Z" }, "id": "invalid-config:4828e7d6c704c4a3", "type": "agent_health_issues" } ], "meta": { "page": { "total_count": 3, "total_filtered_count": 1 } } } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="400" %} Bad Request {% tabs %} {% tab label="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------- | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | code | string | An application-specific error code. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ { "code": "invalid_request", "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="401" %} Unauthorized {% tabs %} {% tab label="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------- | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | code | string | An application-specific error code. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ { "code": "invalid_request", "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="403" %} Forbidden {% tabs %} {% tab label="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------- | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | code | string | An application-specific error code. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ { "code": "invalid_request", "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="429" %} Too many requests {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% /tabs %} ### Code Example {% tabs %} {% tab label="Curl" %} ```bash # Set your Datadog site and credentials export DD_SITE="datadoghq.com" # Or us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com, ddog-gov.com, us2.ddog-gov.com # Use a Personal Access Token or Service Access Token export DD_BEARER_TOKEN="" curl -X GET "https://api.${DD_SITE}/api/v2/agenthealth/issues" \ -H "Accept: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" ``` {% /tab %} {% /tabs %}