Atera Agents

Atera Agent Management

Overview

Atera agents are lightweight software installed on managed endpoints that provide remote monitoring and management capabilities. Agents report system information, health metrics, and enable remote execution of scripts and commands.

Agent Information Fields

Core Fields

Field	Type	Description
AgentID	int	Unique agent identifier
AgentName	string	Agent display name
MachineID	int	Machine reference ID
CustomerID	int	Associated customer ID
CustomerName	string	Customer display name
Online	boolean	Current online status
LastSeenDate	datetime	Last communication timestamp

System Information

Field	Type	Description
MachineName	string	Computer hostname
DomainName	string	AD domain (if joined)
OS	string	Operating system name
OSVersion	string	OS version/build
OSType	string	Windows, Mac, Linux
OSSerialNumber	string	OS serial number
Processor	string	CPU model
Memory	long	Total RAM in bytes

Network Information

Field	Type	Description
IPAddresses	string	Comma-separated IP list
MacAddresses	string	Network adapter MACs
LastIPAddress	string	Most recent IP

Agent Status

Field	Type	Description
AgentVersion	string	Installed agent version
CreatedDate	datetime	When agent was installed
Monitored	boolean	Monitoring enabled
MonitoredStatus	string	Monitoring state
Favorite	boolean	Marked as favorite

Hardware Details

Field	Type	Description
Vendor	string	Hardware manufacturer
VendorSerialNumber	string	Device serial number
VendorModel	string	Device model
VendorBrandModel	string	Full brand/model string

API Patterns

List All Agents (Paginated)

GET /api/v3/agents?page=1&itemsInPage=50
X-API-KEY: {api_key}

Response:

{
  "items": [
    {
      "AgentID": 98765,
      "AgentName": "DESKTOP-ABC123",
      "MachineName": "DESKTOP-ABC123",
      "CustomerID": 12345,
      "CustomerName": "Acme Corporation",
      "Online": true,
      "LastSeenDate": "2024-02-15T14:30:00Z",
      "OS": "Windows 11 Pro",
      "OSType": "Windows",
      "Processor": "Intel Core i7-12700",
      "Memory": 34359738368,
      "IPAddresses": "192.168.1.100,10.0.0.50",
      "AgentVersion": "2.0.1.25",
      "Monitored": true
    }
  ],
  "totalItems": 500,
  "page": 1,
  "itemsInPage": 50,
  "totalPages": 10
}

Get Agent by ID

GET /api/v3/agents/{agentId}
X-API-KEY: {api_key}

Response:

{
  "AgentID": 98765,
  "AgentName": "DESKTOP-ABC123",
  "MachineName": "DESKTOP-ABC123",
  "DomainName": "ACME.LOCAL",
  "CustomerID": 12345,
  "CustomerName": "Acme Corporation",
  "Online": true,
  "LastSeenDate": "2024-02-15T14:30:00Z",
  "OS": "Windows 11 Pro",
  "OSVersion": "10.0.22621",
  "OSType": "Windows",
  "OSSerialNumber": "00330-80000-00000-AA123",
  "Processor": "Intel(R) Core(TM) i7-12700 CPU @ 2.10GHz",
  "Memory": 34359738368,
  "IPAddresses": "192.168.1.100",
  "MacAddresses": "00:1A:2B:3C:4D:5E",
  "Vendor": "Dell Inc.",
  "VendorSerialNumber": "ABC1234567",
  "VendorModel": "OptiPlex 7090",
  "AgentVersion": "2.0.1.25",
  "CreatedDate": "2023-06-15T09:00:00Z",
  "Monitored": true,
  "MonitoredStatus": "Healthy"
}

Get Agents by Customer

GET /api/v3/agents/customer/{customerId}
X-API-KEY: {api_key}

Get Agent by Machine Name

GET /api/v3/agents/machine/{machineName}
X-API-KEY: {api_key}

Delete Agent

DELETE /api/v3/agents/{agentId}
X-API-KEY: {api_key}

Response:

{
  "ActionID": 12345,
  "Success": true
}

PowerShell Execution

Run PowerShell Script

POST /api/v3/agents/{agentId}/powershell
X-API-KEY: {api_key}
Content-Type: application/json

{
  "Script": "Get-Service | Where-Object {$_.Status -eq 'Running'} | Select-Object Name, DisplayName"
}

Response:

{
  "ActionID": 55555,
  "Status": "Queued",
  "Message": "Script queued for execution"
}

PowerShell Best Practices

1. Keep scripts concise - Long-running scripts may timeout
2. Handle errors - Use try/catch blocks
3. Return structured data - Use Select-Object for clean output
4. Avoid interactive commands - No prompts or user input
5. Test locally first - Validate before remote execution

Common PowerShell Commands

Get system information:

Get-ComputerInfo | Select-Object CsName, WindowsVersion, OsArchitecture

Check disk space:

Get-WmiObject Win32_LogicalDisk | Select-Object DeviceID, Size, FreeSpace

List running processes:

Get-Process | Sort-Object WorkingSet -Descending | Select-Object -First 10 Name, WorkingSet

Check Windows updates:

Get-HotFix | Sort-Object InstalledOn -Descending | Select-Object -First 5

Restart a service:

Restart-Service -Name "Spooler" -Force

Agent Online Status

Checking Online Status

The Online field indicates current connectivity:

Status	Description	Action
true	Agent communicating	Commands available
false	Agent not responding	Check network/power

Handling Offline Agents

1. Check LastSeenDate - Determine when agent was last online
2. Verify network - Ensure device has connectivity
3. Check power state - Device may be powered off
4. Review alerts - Look for related alerts
5. Contact user - Verify device status

Offline Thresholds

Duration	Interpretation	Action
< 5 min	Temporary	Normal fluctuation
5-30 min	Short outage	Monitor
30 min - 4 hr	Extended outage	Investigate
> 4 hr	Long-term offline	Contact customer

Agent Lifecycle

Installation

1. Generate installer from Atera portal
2. Download and run on target device
3. Agent registers with Atera cloud
4. Appears in agent list within minutes

Monitoring

• Agent sends heartbeat every few minutes
• Reports system metrics and alerts
• Receives commands from portal/API

Removal

1. Uninstall from device (if accessible)
2. Delete via API or portal
3. Agent record removed from system

Error Handling

Common API Errors

Code	Message	Resolution
400	Invalid agent ID	Verify agent exists
401	Unauthorized	Check API key
403	Forbidden	Verify permissions
404	Agent not found	Confirm agent ID
429	Rate limited	Wait and retry (700 req/min)

PowerShell Execution Errors

Error	Cause	Resolution
Agent offline	Device not connected	Wait for reconnection
Script timeout	Execution too long	Simplify script
Access denied	Insufficient privileges	Check agent permissions
Syntax error	Invalid PowerShell	Validate script locally

Best Practices

1. Monitor agent health - Track online/offline patterns
2. Keep agents updated - Use latest agent version
3. Use meaningful names - Rename agents for clarity
4. Group by customer - Organize for efficient management
5. Review regularly - Remove stale/decommissioned agents
6. Document scripts - Comment PowerShell for reuse
7. Test before bulk execution - Validate on single agent first

Related Skills

• Atera Customers - Customer agent associations
• Atera Alerts - Agent-generated alerts
• Atera Devices - Non-agent monitored devices
• Atera API Patterns - Authentication and pagination