> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariacompute.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node Agent Heartbeat

> GPU node agent reports liveness and refreshed GPU inventory to the PIN controller.

Send a periodic heartbeat so the PIN controller knows the agent is healthy. The heartbeat updates the last-seen timestamp and GPU inventory. If the agent disappears beyond the heartbeat timeout, the controller reclaims and re-enqueues any assigned jobs.

<Warning>
  Node-agent endpoints use an agent registration token bootstrapped during deployment. Pass it as `Authorization: Bearer <agent-token>`.
</Warning>

## Endpoint

**POST** `/v1/agent/heartbeat`

Authentication: `Authorization: Bearer <agent-token>`

## Request body

<ParamField body="agent_id" type="string" required>
  Stable agent ID returned from registration.
</ParamField>

<ParamField body="gpus" type="array">
  Current GPU inventory snapshot.
</ParamField>

<ParamField body="status" type="string">
  Agent status, such as `online`.
</ParamField>

<ParamField body="version" type="string">
  Agent binary version.
</ParamField>

## Response

<ResponseField name="ok" type="boolean">
  Whether the heartbeat was accepted.
</ResponseField>

## Example

```bash theme={null}
curl -X POST http://<pin-host>:8001/v1/agent/heartbeat \
  -H "Authorization: Bearer <agent-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "ag_1234567890",
    "gpus": [
      {"index":0,"model":"A100","mem_total_gb":80.0,"mem_used_gb":10.0,"slots":1,"used_slots":1}
    ],
    "status": "online",
    "version": "1.2.0"
  }'
```

```json theme={null}
{
  "ok": true
}
```


## Related topics

- [Node Agent Register](/api-reference/pin/node-agent/register.md)
- [List and Deploy Node Agents](/api-reference/pin/gpu-nodes/agents.md)
- [Node Agent Control Channel and Interventions](/api-reference/pin/node-agent/control.md)
- [Report Training Metrics and Status - Node Agent](/api-reference/pin/node-agent/metrics.md)
- [Acquire Next Pending Job for Node Agent](/api-reference/pin/node-agent/acquire.md)