> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getprimo.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Run a script on a target
> Run a script on all devices, on one or more device groups, or on an explicit list of devices — intersected with the given platforms. Pass `{ "scriptId": 12 }` to run a saved script (see `getScripts`), or `{ "contents": "..." }` to send the source inline. An inline run may only target a single device.
The target is resolved once, at trigger time: devices that join a group later are not included. The response returns immediately with every execution `pending`; poll `getScriptRun` for progress.
To run on exactly one device, `runDeviceScript` is the shorter equivalent. To check how many devices would be reached without executing anything, use `previewScriptRunTarget`.
⚠️ **This executes arbitrary code on the targeted devices with elevated privileges, and is not idempotent** — repeating the call runs the script again. Review the script and the target before calling.
**Supported platforms:** macOS, Windows, Linux. Not supported: iOS, Android, ChromeOS.
Executions are reconciled with FleetDM by a background sweep that runs every 15 minutes, so a freshly created run reads back as `pending` until the next sweep. Poll no more often than that.
Key: WriteScope: Company
## OpenAPI
````yaml https://api.getprimo.com/openapi.json post /script-runs
openapi: 3.1.1
info:
title: Public API - BETA
description: Read docs on https://docs.getprimo.com/
version: '1.0'
contact: {}
servers:
- url: https://api.getprimo.com
security:
- apikey: []
tags: []
paths:
/script-runs:
post:
tags:
- Scripts
summary: Run a script on a target
description: >-
Run a script on all devices, on one or more device groups, or on an
explicit list of devices — intersected with the given platforms. Pass `{
"scriptId": 12 }` to run a saved script (see `getScripts`), or `{
"contents": "..." }` to send the source inline. An inline run may only
target a single device.
The target is resolved once, at trigger time: devices that join a group
later are not included. The response returns immediately with every
execution `pending`; poll `getScriptRun` for progress.
To run on exactly one device, `runDeviceScript` is the shorter
equivalent. To check how many devices would be reached without executing
anything, use `previewScriptRunTarget`.
⚠️ **This executes arbitrary code on the targeted devices with elevated
privileges, and is not idempotent** — repeating the call runs the script
again. Review the script and the target before calling.
**Supported platforms:** macOS, Windows, Linux. Not supported: iOS,
Android, ChromeOS.
Executions are reconciled with FleetDM by a background sweep that runs
every 15 minutes, so a freshly created run reads back as `pending` until
the next sweep. Poll no more often than that.
operationId: runScript
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RunScriptBody'
responses:
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/RunScript_Output'
components:
schemas:
RunScriptBody:
type: object
properties:
script:
description: >-
What to run: `{ "scriptId": 12 }` for a script from the catalog, or
`{ "contents": "..." }` to send the source inline. An inline run may
only target a single device.
anyOf:
- type: object
properties:
scriptId:
type: integer
exclusiveMinimum: 0
maximum: 9007199254740991
required:
- scriptId
- type: object
properties:
contents:
type: string
minLength: 1
maxLength: 10000
required:
- contents
target:
description: >-
Which devices to run on, intersected with `platforms`. Resolved once
at trigger time — devices joining a group later are not included.
anyOf:
- type: object
properties:
type:
type: string
const: all
required:
- type
- type: object
properties:
type:
type: string
const: deviceGroups
deviceGroupIds:
minItems: 1
type: array
items:
type: string
required:
- type
- deviceGroupIds
- type: object
properties:
type:
type: string
const: devices
deviceIds:
minItems: 1
type: array
items:
type: string
required:
- type
- deviceIds
platforms:
description: >-
Platforms to run on. The target is intersected with this list, and a
saved script must support them.
minItems: 1
type: array
items:
type: string
enum:
- macos
- windows
- linux
required:
- script
- target
- platforms
RunScript_Output:
type: object
properties:
id:
type: string
script:
type: object
properties:
scriptId:
description: >-
Saved script that was run, or null when the contents were sent
inline.
anyOf:
- type: number
- type: 'null'
name:
description: Script name at the time of the run. Null for an inline run.
anyOf:
- type: string
- type: 'null'
required:
- scriptId
- name
additionalProperties: false
target:
description: The target as submitted.
anyOf:
- type: object
properties:
type:
type: string
const: all
required:
- type
additionalProperties: false
- type: object
properties:
type:
type: string
const: deviceGroups
deviceGroupIds:
minItems: 1
type: array
items:
type: string
required:
- type
- deviceGroupIds
additionalProperties: false
- type: object
properties:
type:
type: string
const: devices
deviceIds:
minItems: 1
type: array
items:
type: string
required:
- type
- deviceIds
additionalProperties: false
platforms:
type: array
items:
type: string
enum:
- macos
- windows
- linux
contents:
type: string
description: Full source of the script as executed.
totalExecutions:
type: number
description: Number of devices the run resolved to.
createdAt:
type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
executions:
type: array
description: >-
One execution per resolved device, all `pending` at creation. Poll
`getScriptRun` or `getScriptRunExecutions` for outcomes.
items:
type: object
properties:
id:
type: string
runId:
description: Identifier of the script run this execution belongs to.
type: string
deviceId:
type: string
status:
description: >-
Outcome on one device. `pending`: queued, the device may be
offline. `success`: ran with exit code 0. `failed`: ran with a
non-zero exit code, or the device was incompatible. `timeout`:
exceeded the execution limit. `cancelled`: cancelled before
running.
type: string
enum:
- pending
- success
- failed
- timeout
- cancelled
output:
description: >-
Combined stdout/stderr once the execution completes. Null
while pending.
anyOf:
- type: string
- type: 'null'
exitCode:
description: >-
Process exit code once the execution completes. Null while
pending.
anyOf:
- type: number
- type: 'null'
runtime:
description: >-
Duration in seconds once the execution completes. Null while
pending.
anyOf:
- type: number
- type: 'null'
createdAt:
type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
updatedAt:
type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
required:
- id
- runId
- deviceId
- status
- output
- exitCode
- runtime
- createdAt
- updatedAt
additionalProperties: false
required:
- id
- script
- target
- platforms
- contents
- totalExecutions
- createdAt
- executions
additionalProperties: false
securitySchemes:
apikey:
scheme: bearer
bearerFormat: API key
type: http
description: >-
Use your Primo API key in the Authorization header as `Bearer
`.
````