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

# Get an Agent

> Fetch a single agent by ID from Aria Compute PIN, including GPU details, status, version, and deployment state.

Retrieve detailed information about a specific agent. The response includes GPU inventory, last heartbeat, status, version, deployment state, and the parent node binding.

## Endpoint

**GET** `/v1/agents/:id`

Authorization: Bearer API key required.

## Path parameters

<ParamField path="id" type="string" required>
  Agent identifier, e.g. ag\_7f8e9d0c.
</ParamField>

## Response

<ResponseField name="id" type="string" required>
  Agent identifier.
</ResponseField>

<ResponseField name="name" type="string" required>
  Agent name.
</ResponseField>

<ResponseField name="gpu_count" type="integer">
  Total number of GPUs.
</ResponseField>

<ResponseField name="gpu_mem_gb" type="number">
  Total GPU memory in GB.
</ResponseField>

<ResponseField name="labels" type="array of strings">
  Scheduling labels.
</ResponseField>

<ResponseField name="gpus" type="array">
  Per-GPU details: index, model, mem\_total\_gb, mem\_used\_gb, slots, used\_slots.
</ResponseField>

<ResponseField name="last_heartbeat" type="string (ISO 8601)">
  Last heartbeat timestamp.
</ResponseField>

<ResponseField name="status" type="string">
  Agent status, e.g. online.
</ResponseField>

<ResponseField name="node_id" type="string">
  Parent GPU node identifier.
</ResponseField>

<ResponseField name="version" type="string">
  Agent binary version.
</ResponseField>

<ResponseField name="deploy_state" type="string">
  Deployment state, e.g. deployed or updating.
</ResponseField>

<ResponseField name="last_error" type="string">
  Last deployment or operation error, if any.
</ResponseField>

<ResponseField name="agent_uid" type="string">
  Unique deployment UID on the host.
</ResponseField>

## Example

```bash theme={null}
curl -s http://<pin-host>:8001/v1/agents/ag_7f8e9d0c \
  -H "Authorization: Bearer $ARIA_PIN_KEY"
```

```json theme={null}
{
  "id": "ag_7f8e9d0c",
  "name": "training-agent",
  "gpu_count": 8,
  "gpu_mem_gb": 640,
  "labels": ["training", "a100"],
  "gpus": [
    {
      "index": 0,
      "model": "NVIDIA A100",
      "mem_total_gb": 80,
      "mem_used_gb": 12.5,
      "slots": 1,
      "used_slots": 1
    }
  ],
  "last_heartbeat": "2024-05-10T14:30:00Z",
  "status": "online",
  "node_id": "gn_a1b2c3d4",
  "version": "1.2.0",
  "deploy_state": "deployed",
  "last_error": "",
  "agent_uid": "aria-agent-7f8e9d0c"
}
```

Retrieve detailed information about a specific agent. The response includes GPU inventory, last heartbeat, status, version, deployment state, and the parent node binding.

## Endpoint

**GET** `/v1/agents/:id`

Authorization: Bearer API key required.

## Path parameters

<ParamField path="id" type="string" required>
  Agent identifier, e.g. ag\_7f8e9d0c.
</ParamField>

## Response

<ResponseField name="id" type="string" required>
  Agent identifier.
</ResponseField>

<ResponseField name="name" type="string" required>
  Agent name.
</ResponseField>

<ResponseField name="gpu_count" type="integer">
  Total number of GPUs.
</ResponseField>

<ResponseField name="gpu_mem_gb" type="number">
  Total GPU memory in GB.
</ResponseField>

<ResponseField name="labels" type="array of strings">
  Scheduling labels.
</ResponseField>

<ResponseField name="gpus" type="array">
  Per-GPU details: index, model, mem\_total\_gb, mem\_used\_gb, slots, used\_slots.
</ResponseField>

<ResponseField name="last_heartbeat" type="string (ISO 8601)">
  Last heartbeat timestamp.
</ResponseField>

<ResponseField name="status" type="string">
  Agent status, e.g. online.
</ResponseField>

<ResponseField name="node_id" type="string">
  Parent GPU node identifier.
</ResponseField>

<ResponseField name="version" type="string">
  Agent binary version.
</ResponseField>

<ResponseField name="deploy_state" type="string">
  Deployment state, e.g. deployed or updating.
</ResponseField>

<ResponseField name="last_error" type="string">
  Last deployment or operation error, if any.
</ResponseField>

<ResponseField name="agent_uid" type="string">
  Unique deployment UID on the host.
</ResponseField>

## Example

```bash theme={null}
curl -s http://<pin-host>:8001/v1/agents/ag_7f8e9d0c \
  -H "Authorization: Bearer $ARIA_PIN_KEY"
```

```json theme={null}
{
  "id": "ag_7f8e9d0c",
  "name": "training-agent",
  "gpu_count": 8,
  "gpu_mem_gb": 640,
  "labels": ["training", "a100"],
  "gpus": [
    {
      "index": 0,
      "model": "NVIDIA A100",
      "mem_total_gb": 80,
      "mem_used_gb": 12.5,
      "slots": 1,
      "used_slots": 1
    }
  ],
  "last_heartbeat": "2024-05-10T14:30:00Z",
  "status": "online",
  "node_id": "gn_a1b2c3d4",
  "version": "1.2.0",
  "deploy_state": "deployed",
  "last_error": "",
  "agent_uid": "aria-agent-7f8e9d0c"
}
```


## Related topics

- [Get Agent Turn](/api-reference/agent/turns/get.md)
- [Update an Aria Agent Cloud Agent Definition](/api-reference/agent/agents/update.md)
- [List Agents - GET /v1/agents](/api-reference/agent/agents/list.md)
- [Get Subagent](/api-reference/agent/subagents/get.md)
- [Get Memory Item](/api-reference/agent/memory/get.md)