---
title: "POST /api/fleet/agents/{id}/checkin"
method: POST
path: "/api/fleet/agents/{id}/checkin"
---

# POST /api/fleet/agents/{id}/checkin

`POST /api/fleet/agents/{id}/checkin`

The agent checkin endpoint.
Clients will long-poll this endpoint.
A client may inform fleet-server of it's long-poll timeout in the request body.
The fleet-server will return a response if there is a new action for the agent, or if the polling timeout is reached.
The fleet-server may also use some jitter to offset the polling timeout, if specified a random amount of the jitter value may be subtracted from the polling timeout.
The fleet-sever polling timeout is short-circuited in cases of heavy load where setting up the checkin (ensuring the API key is authed etc) takes longer then the timeout value.
Fleet-server sets the poll timeout to 5m by default (with a 10m write timeout), for these values we assume that elastic-agent's request timeout is set to 10m and the cloud-proxy's timeout is longer than 10m.

## Path parameters

- `id` string, required

## Headers

- `Accept-Encoding` string
- `User-Agent` string, required
- `X-Request-Id` string
- `Elastic-Api-Version` string

## Request body

- CheckinRequest
  - `status` 'online' | 'error' | 'degraded' | 'starting', required — The agent state, inferred from agent control protocol states.
  - `message` string, required — State message, may be overridden or use the error message of a failing component.
  - `ack_token` string — The ack_token form a previous response if the agent has checked in before. Translated to a sequence number in fleet-server in order to retrieve any new actions for the agent from the last checkin.
  - `local_metadata` string, application/json — An embedded JSON object that holds meta-data values. Defined in fleet-server as a `json.RawMessage`, defined as an object in the elastic-agent. elastic-agent will populate the object with information from the binary and host/system environment. fleet-server will update the agent record if a checkin response contains different data from the record.
  - `components` string, application/json — An embedded JSON object that holds component information that the agent is running. Defined in fleet-server as a `json.RawMessage`, defined as an object in the elastic-agent. fleet-server will update the components in an agent record if they differ from this object.
  - `poll_timeout` string, duration — An optional timeout value that informs fleet-server of when a client will time out on it's checkin request. If not specified fleet-server will use the timeout values specified in the config (defaults to 5m polling and a 10m write timeout). The value, if specified is expected to be a string that is parsable by [time.ParseDuration](https://pkg.go.dev/time#ParseDuration). If specified fleet-server will set its poll timeout to `max(1m, poll_timeout-2m)` and its write timeout to `max(2m, poll_timout-1m)`.

## Response `200`

Agent checkin successful. May include actions.

- CheckinResponse
  - `ack_token` string — The acknowlegment token used to indicate action delivery.
  - `action` string, required — The action result. Set to "checkin".
  - `actions` Action[] — A list of actions that the agent must execute.
    - `agent_id` string, required — The agent ID.
    - `created_at` string, required — Time when the action was created.
    - `start_time` string — The earliest execution time for the action. Agent will not execute the action before this time. Used for scheduled actions.
    - `expiration` string — The latest start time for the action. Actions will be dropped by the agent if execution has not started by this time. Used for scheduled actions.
    - `data` unknown, required
    - `id` string, required — The action ID.
    - `traceparent` string — APM traceparent for the action.
    - `type` string, required — The action type.
    - `input_type` string, required — The input type of the action for actions with type `INPUT_ACTION`.
    - `timeout` integer — The timeout value (in seconds) for actions with type `INPUT_ACTION`.
    - `signed` ActionSignature — Optional action signing data.
      - `data` string, base64, required — The base64 encoded, UTF-8 JSON serialized action bytes that are signed.
      - `signature` string, base64, required — The base64 encoded signature.

## Other responses

- `400` — A 400 response for receiving an invalid User-Agent, Elastic-Api-Version header or version number (checkin and enroll endpoints). In the case where an invalid or unsupported Elastic-Api-Version header is requested, the response will contain the default version number. Or any other undefined error encounted by the fleet-server. May be returned by any endpoint except /api/fleet/status.
- `401` — 401 response when the API key is not enabled on any endpoint except /api/fleet/status. Or when there are issues updating an inactive agent on the ack endpoint.
- `404` — 404 response when the agent is not found. May be returned by checkin endpoint. or endpoints that use the agentApiKey auth scheme
- `408` — 408 request timeout.
- `500` — A 500 response for encountering not expected bahavior.
- `503` — 503 response when the server is not available for some reason. Such as if a context is cancelled or the connection (to ES) is refused. May be returned by any endpoint.

---

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