run-powershell

Run PowerShell on Atera Agent

Execute a PowerShell script on a specific Atera agent (endpoint) either inline or from the script library.

Prerequisites

• Valid Atera API key configured
• Agent must exist and be online
• User must have script execution permissions
• Either script or script_id must be provided

Steps

1. Validate agent exists and is online

   curl -s -X GET "https://app.atera.com/api/v3/agents/{agent_id}" \
     -H "X-API-KEY: $ATERA_API_KEY" \
     -H "Accept: application/json"
   

   • Check agent exists
   • Verify agent is online
   • Capture device info for output

2. Get script content if using script_id

   curl -s -X GET "https://app.atera.com/api/v3/customscripts/{script_id}" \
     -H "X-API-KEY: $ATERA_API_KEY" \
     -H "Accept: application/json"
   

   • Validate script exists
   • Show script name for confirmation

3. Execute the script

   curl -s -X POST "https://app.atera.com/api/v3/agents/{agent_id}/runpowershell" \
     -H "X-API-KEY: $ATERA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "Script": "<script_content>",
       "RunAs": "<run_as>",
       "Timeout": <timeout>
     }'
   

   • Capture execution ID for status polling

4. Poll for completion

   curl -s -X GET "https://app.atera.com/api/v3/agents/{agent_id}/powershellstatus/{execution_id}" \
     -H "X-API-KEY: $ATERA_API_KEY" \
     -H "Accept: application/json"
   

   • Poll every 5 seconds
   • Respect timeout parameter
   • Capture output when complete

5. Return execution results

   • Execution status
   • Script output (stdout)
   • Error output (stderr)
   • Execution duration

Parameters

Parameter	Type	Required	Default	Description
agent_id	integer	Yes	-	The agent ID to execute on
script	string	No*	-	Inline PowerShell script
script_id	integer	No*	-	Saved script ID from library
run_as	string	No	System	System or LoggedOnUser
timeout	integer	No	300	Timeout in seconds