Skip to content

/v2/background-scripts/
Stable

Request

Retrieves all background scripts configured for the tenant.

Returns the tenant's background scripts with optional filtering by name and always_run, and standard pagination.

About Background Scripts Background Scripts let a tenant run custom PowerShell automation on managed devices. This list endpoint is the primary way to review what scripts already exist before creating or reusing one.

Key Fields / Query Parameters

  • name — Filter scripts by name
  • always_run — Filter to only continuously-running (or scheduled) scripts
  • ordering — Field to sort results by
  • limit / offset — Pagination controls

Common Use Cases

  • Auditing all background scripts currently configured for the tenant
  • Finding an existing script to reuse or update rather than duplicating it
  • Reviewing which scripts are set to always_run versus scheduled

Best Practices

  • Check this list before creating a new script to avoid duplicating existing automation
  • Filter by always_run when reviewing continuously-running scripts specifically, since these have the broadest device impact
  • Periodically review script content for scripts no longer in use

Workflow

  1. GET this endpoint to review existing background scripts
  2. GET a specific script by ID to view its full content
  3. Create a new script via POST if none of the existing ones fit
Query
orderingstring

Order the results by a specific field (-field for descending order). Valid fields are 'name', 'created_at', 'updated_at', 'created_by', 'updated_by'.

namestring

Filter the results by name (partial match, case insensitive).

always_runboolean

Filter the results by always_run flag.

limitinteger, [ 1 .. 100 ]

Number of results to return per page.

Default:10
offsetinteger, >= 0

The initial index from which to return the results.

Default:0
cURL
curl -i -X GET \
  'https://develop-api.esper.io/_mock/openapi/v2/background-scripts/?ordering=string&name=string&always_run=true&limit=10&offset=0'

Responses

Success

Bodyapplication/json
contentobject
messagestring
codeinteger
Response
{
  "content": {
    "count": 0,
    "next": "string",
    "previous": "string",
    "results": [ … ]
  },
  "message": "string",
  "code": 0
}