Macro Settings Profiles: Arguments Shared Across Devices

A macro settings profile is a named set of argument values for one Python macro. Instead of filling in the same form on fifty device cards, you fill it in once, give it a name, and point devices at it. This page is for anyone who runs one macro on more than one device in Macro Automation Studio (MAS), and for API users who want to manage those values from a script.

What a macro settings profile holds

• A profile belongs to one macro. Profiles exist only for Python macros, because only they take arguments.
• Its values are the fields of the macro’s argument form: the same keys your script reads through src/script_args.py. See UI Builder for how that form is built. If the macro has no ui.xml, MAS reads the argparse definitions in script_args.py instead.
• Names are unique within a macro and at most 100 characters. The saved values must stay under 64 KB.

The Default profile

Every Python macro has a profile named Default. MAS creates it the first time the profile list is opened, in the app or through the API. Default cannot be renamed or deleted, but its values are editable. An empty Default means “use the script’s own defaults”.

New devices you create with a Python macro follow Default automatically. When you switch a device to a different macro, it follows that macro’s Default. When you delete a named profile, every device that followed it moves to Default, so no device is left without values.

Follow a profile, or stay Custom with per-device macro arguments

A device is always in one of three states.

Custom is the older per-device mode. Devices that existed before profiles start in Custom with their saved values and run exactly as before until you pick a profile for them.

Open the settings dialog

1. Click Device Groups in the sidebar and open a group.
2. On a device card, choose a Python macro in the Macro select. Python macros carry a Python tag in the list.
3. Click Macro settings. The button also shows the profile the device follows, or Custom.
4. The dialog opens with a Profile bar above the form.

Create, edit and delete profiles

Save the current values as a new profile

1. Fill in the form.
2. Click New in the Profile bar.
3. Type a name and press Enter.

MAS creates the profile with the current form values and points this device at it. A toast confirms: Profile “name” created with the current values.

Edit a profile

1. Select the profile in Profile.
2. Change any field. MAS saves your edits while you type and again when you close the dialog.

Under the bar, a hint reads “Saving updates N device(s) using this profile”. Every device that follows the profile uses the new values on its next run. A run that is already in progress keeps the values it started with.

Switch a device to another profile

Pick a different profile, or Custom (this device only), in the Profile select. The form reloads with that profile’s values, and the device follows it from then on, even if you change nothing else.

Delete a profile

1. Select the profile.
2. Click the trash button in the Profile bar.
3. Confirm Delete.

The confirmation says it plainly: devices using it will move to Default. The button is always visible; for Default or Custom it opens a dialog that explains why deletion is not possible.

How runs pick their values

Every way of starting a macro resolves the values the same way: Start on a card, Start All in a group, and runs launched by the Scheduler. The server does the resolution and includes the result as effective_script_args on every device it returns, so the app, the Scheduler and API clients always agree.

Manage profiles from the API

All four profile routes accept either a bearer token or an API key in the X-API-KEY header. See REST API for the request conventions and API keys for creating a key. Every lookup is scoped to your account, so a profile you do not own returns 404.

curl -H "X-API-KEY: $MAS_API_KEY" \
  "https://api.automationmacro.com/api/macro-setting-profiles?macro_id=3"

{
  "items": [
    { "id": 1, "macro_id": 3, "name": "Default", "args": {}, "is_default": true, "devices_using": 12 },
    { "id": 4, "macro_id": 3, "name": "Aggressive", "args": { "speed": "fast" }, "is_default": false, "devices_using": 3 }
  ]
}

Replacing args is the fleet-wide edit. The next run on every follower uses the new values.

curl -X PUT "https://api.automationmacro.com/api/macro-setting-profiles/4" \
  -H "X-API-KEY: $MAS_API_KEY" -H "Content-Type: application/json" \
  -d '{"args": {"speed": "slow"}}'

A delete answers with the Default profile its followers now use: { "deleted": true, "repointed_to": 1 }.

Errors to expect: 409 when the name is already used for that macro, 400 when you rename or delete Default or send more than 64 KB of args, and 404 for a profile or macro that is not yours.

To point a device at a profile, send PUT /api/emulator/devices/{id} with {"settings_profile_id": 4}. A value of 0 returns the device to Custom. This device route needs a signed-in bearer token rather than an API key. GET /api/emulator/devices does accept an API key and returns settings_profile_id and effective_script_args for each device.

Read the values in your script

Profiles change where values are stored, not how a script reads them. Each tab of the form is a namespace and each field is an attribute, exactly as on the UI Builder page.

import mas
from src.script_args import args

speed = args.general.speed      # "fast" on devices that follow "Aggressive"
rounds = args.general.rounds

mas.log(f"speed={speed} rounds={rounds}")
for _ in range(rounds):
    match = mas.find_object_retry(1234, total_tries=3, time_sleep=2.0)
    if match:
        mas.click(match.x, match.y)

Troubleshooting

Macro settings button is missing

The button appears only when a Python macro is selected on the card. Block macros have no arguments. Pick a macro marked Python in the Macro select.

This macro has no configurable arguments

The script has neither a ui.xml nor argparse definitions in script_args.py. Open the macro in the Code Editor, click Add Args UI, and build a form with the UI Builder.

A device ignores the profile I edited

The device is in Custom mode, or follows a different profile. Look at the Macro settings button: it names the profile the device follows. Open the dialog and select the profile you want.

Can’t delete this profile

Default cannot be deleted, and Custom is not a profile. Select a named profile before you click the trash button.