# Macro Settings Profiles: Arguments Shared Across Devices

> Save macro argument values as a settings profile in MAS Studio, point many emulator or cloud devices at it, and update every device with one edit.

Source: https://automationmacro.com/docs/settings-profiles (Studio, updated 2026-09-04)

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](/docs/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.

| State | Where the values come from | Who a save affects |
|---|---|---|
| Default | the macro's Default profile | every device that follows Default |
| A named profile | that profile | every device that follows it |
| Custom (this device only) | values saved on the device itself | this device only |

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.

> [!NOTE]
> The dialog is the native form MAS renders from `ui.xml`, with the same tabs and fields you see when you click **Run** in the Code Editor.

## 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 <kbd>Enter</kbd>.

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.

> [!TIP]
> Profiles pair well with [device groups](/docs/device-groups). Keep a "Conservative" and an "Aggressive" profile for one farming macro, point most devices at one and a few test devices at the other, and tune either set with a single edit. A [cloud device](/cloud-devices) in the group follows a profile the same way.

## 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](/docs/rest-api) for the request conventions and [API keys](/docs/api-keys) for creating a key. Every lookup is scoped to your account, so a profile you do not own returns 404.

| Method and path | What it does |
|---|---|
| `GET /api/macro-setting-profiles?macro_id=3` | Lists a macro's profiles. Default is always present. `devices_using` is the follower count. |
| `POST /api/macro-setting-profiles` | Creates a profile from `macro_id`, `name` and `args`. |
| `PUT /api/macro-setting-profiles/{id}` | Renames a profile and/or replaces its whole `args` set. |
| `DELETE /api/macro-setting-profiles/{id}` | Deletes a profile. Followers move to Default. |

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

```json
{
  "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.

```bash
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.

```python
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](/docs/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.