---
type: api
title: Update an agent by ID
description: **Spaces method and path for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/v9/operation/operation-put-fleet-agents-agentid
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/v9/operation/operation-put-fleet-agents-agentid
products:
  - Kibana
---

# Update an agent by ID

- Server: `https://{kibana_url}`

## Paths

- `PUT` `/api/fleet/agents/{agentId}`
- `PUT` `/s/{space_id}/api/fleet/agents/{agentId}`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana/v9/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/kibana/v9/authentication#basicauth)

#### Path Parameters

- `agentId` (string)
  The agent ID

## Description

Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.

Update an agent by ID.<br/><br/>[Required authorization] Route required privileges: fleet-agents-all.

## Request Body

`application/json`

- `tags` ([] string · max: 10) — optional
- `user_provided_metadata` (map string to object) — optional

## Responses

#### `200`

Successful response

`application/json`

- `item` (object)
  - `access_api_key` (string)
  - `access_api_key_id` (string)
  - `active` (boolean)
  - `agent` (object)
    - `id` (string)
    - `type` (string)
    - `version` (string)
  - `audit_unenrolled_reason` (string)
  - `capabilities` ([] string · max: 100)
  - `components` ([] object · max: 10000)
    - `id` (string)
    - `message` (string)
    - `status` (enum)
      Values: `STARTING`, `CONFIGURING`, `HEALTHY`, `DEGRADED`, `FAILED`, `STOPPING`, `STOPPED`
    - `type` (string)
    - `units` ([] object · max: 10000)
      - `id` (string)
      - `message` (string)
      - `payload` (map string to object)
      - `status` (enum)
        Values: `STARTING`, `CONFIGURING`, `HEALTHY`, `DEGRADED`, `FAILED`, `STOPPING`, `STOPPED`
      - `type` (enum)
        Values: `input`, `output`
  - `default_api_key` (string)
  - `default_api_key_history` ([] object · max: 100)
    - `id` (string)
    - `retired_at` (string)
  - `default_api_key_id` (string)
  - `effective_config` (object)
  - `enrolled_at` (string)
  - `health` (map string to object)
  - `id` (string)
  - `identifying_attributes` (map string to string)
  - `last_checkin` (string)
  - `last_checkin_message` (string)
  - `last_checkin_status` (enum)
    Values: `error`, `online`, `degraded`, `updating`, `starting`, `disconnected`
  - `last_known_status` (enum)
    Values: `offline`, `error`, `online`, `inactive`, `enrolling`, `unenrolling`, `unenrolled`, `updating`, `degraded`, `uninstalled`, `orphaned`
  - `local_metadata` (map string to object)
  - `metrics` (object)
    - `cpu_avg` (number)
    - `memory_size_byte_avg` (number)
  - `namespaces` ([] string · max: 100)
  - `non_identifying_attributes` (map string to string)
  - `outputs` (map string to object)
    Map values (object)
    - `api_key_id` (string)
    - `to_retire_api_key_ids` ([] object · max: 100)
      - `id` (string)
      - `retired_at` (string)
    - `type` (string)
  - `packages` ([] string · max: 10000)
  - `pipeline_config` (string · max: 10000)
  - `policy_base_id` (string)
  - `policy_id` (string)
  - `policy_revision` (number) — nullable
  - `sequence_num` (number)
  - `signals` ([] string · max: 50)
  - `sort` ([] object · max: 10)
  - `status` (enum)
    Values: `offline`, `error`, `online`, `inactive`, `enrolling`, `unenrolling`, `unenrolled`, `updating`, `degraded`, `uninstalled`, `orphaned`
  - `tags` ([] string · max: 100)
  - `type` (enum)
    Values: `PERMANENT`, `EPHEMERAL`, `TEMPORARY`, `OPAMP`
  - `unenrolled_at` (string)
  - `unenrollment_started_at` (string)
  - `unhealthy_reason` ([] enum  · max: 3) — nullable
    Values: `input`, `output`, `other`
  - `upgrade` (object)
    - `rollbacks` ([] object · max: 100)
      - `valid_until` (string)
      - `version` (string)
  - `upgrade_attempts` ([] string · max: 10000) — nullable
  - `upgrade_details` (object) — nullable
    - `action_id` (string)
    - `metadata` (object)
      - `download_percent` (number)
      - `download_rate` (number)
      - `error_msg` (string)
      - `failed_state` (enum)
        Values: `UPG_REQUESTED`, `UPG_SCHEDULED`, `UPG_DOWNLOADING`, `UPG_EXTRACTING`, `UPG_REPLACING`, `UPG_RESTARTING`, `UPG_FAILED`, `UPG_WATCHING`, `UPG_ROLLBACK`
      - `reason` (string)
      - `retry_error_msg` (string)
      - `retry_until` (string)
      - `scheduled_at` (string)
    - `state` (enum)
      Values: `UPG_REQUESTED`, `UPG_SCHEDULED`, `UPG_DOWNLOADING`, `UPG_EXTRACTING`, `UPG_REPLACING`, `UPG_RESTARTING`, `UPG_FAILED`, `UPG_WATCHING`, `UPG_ROLLBACK`
    - `target_version` (string)
  - `upgrade_started_at` (string) — nullable
  - `upgraded_at` (string) — nullable
  - `user_provided_metadata` (map string to object)
#### `400`

Bad Request

`application/json`

- `attributes` (object)
- `error` (string)
- `errorType` (string)
- `message` (string)
- `statusCode` (number)
#### `404`

Not Found

## Code Examples

#### Console

```console
PUT /api/fleet/agents/{agentId}
{
  "tags": [
    "production",
    "linux"
  ]
}
```

#### curl

```curl
curl -X PUT "https://{kibana_url}/api/fleet/agents/{agentId}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
  "tags": [
    "production",
    "linux"
  ]
}'
```

## Response Examples

#### Put agent

Updated agent details

```json
{
  "item": {
    "active": true,
    "enrolled_at": "2024-01-01T00:00:00.000Z",
    "id": "agent-id-1",
    "policy_id": "agent-policy-id-1",
    "policy_revision": 1,
    "status": "online",
    "tags": [
      "production",
      "linux"
    ],
    "type": "PERMANENT",
    "updated_at": "2024-01-01T00:00:00.000Z"
  }
}
```

#### Generic error response

Example of a generic error response

```json
{
  "error": "Bad Request",
  "message": "An error message describing what went wrong",
  "statusCode": 400
}
```

#### Not found

No agent was found with the given ID

```json
{
  "error": "Not Found",
  "message": "Agent agent-id-1 not found",
  "statusCode": 404
}
```