> ## 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.

# Report Training Metrics and Status - Node Agent

> Node agents push per-step training metrics and status transitions to the PIN control plane for a job they own, using the agent secret.

Node agents push training telemetry and status transitions to the PIN control plane. Two endpoints cover this: `/v1/agent/metrics` for per-step numeric metrics and `/v1/agent/status` for job status transitions.

<Warning>
  Both endpoints require `X-Agent-Secret`. They are meant for the node agent, not for end users.
</Warning>

## Push metrics

```http theme={null}
POST /v1/agent/metrics
```

### Request body

<ParamField body="agent_id" type="string" required>
  Sending agent identifier.
</ParamField>

<ParamField body="job_id" type="string" required>
  Job the metrics belong to.
</ParamField>

<ParamField body="step" type="integer" required>
  Training step index.
</ParamField>

<ParamField body="loss" type="number">
  Training loss.
</ParamField>

<ParamField body="reward" type="number">
  Reward (RL jobs).
</ParamField>

<ParamField body="throughput" type="number">
  Tokens per second.
</ParamField>

<ParamField body="gpu_util" type="number">
  GPU utilization percent.
</ParamField>

## Push status

```http theme={null}
POST /v1/agent/status
```

### Request body

<ParamField body="agent_id" type="string" required>
  Sending agent identifier.
</ParamField>

<ParamField body="job_id" type="string" required>
  Job identifier.
</ParamField>

<ParamField body="status" type="string" required>
  New status: `running`, `paused`, `completed`, `failed`.
</ParamField>

<ParamField body="error" type="string">
  Error message when `status = failed`.
</ParamField>

## Response

Both endpoints return `{"code": 0, "data": {"ok": true}, "message": ""}` on success.

## Example

```bash theme={null}
curl -X POST https://ariapin.example.com/v1/agent/metrics \
  -H "X-Agent-Secret: $AGENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"ag_01","job_id":"job_0198a","step":250,"loss":0.42,"throughput":1850,"gpu_util":92}'
```


## Related topics

- [Analyze training metrics and detect reward hacking](/api-reference/pin/jobs/analysis.md)
- [Node Agent Control Channel and Interventions](/api-reference/pin/node-agent/control.md)
- [Node Agent Heartbeat](/api-reference/pin/node-agent/heartbeat.md)
- [Restart PIN Training Agent Process](/api-reference/pin/agents/restart.md)
- [Retrieve full training job detail with checkpoints and metrics](/api-reference/pin/jobs/get.md)