Custom Fields

Experiences support adding custom fields. Custom fields are similar to tags, but allow specifying both keys and values. This allows you to add flexible metadata to your experiences. These can be used for organizational purposes when launching batches or managing your test suites. For example, you could add a custom field for "version", along with a version number, to experiences. You could then launch a batch containing all experiences where version is greater than 10.

In general, we recommend working with custom fields via experience syncing, as it prevents the need to maintain the fields via manually-run CLI commands.

Custom fields support various types of data:

• text
• numbers, e.g. 2, 4, or 3.283
• timestamps e.g. 2025-10-01T12:24:00Z
• raw JSON e.g. {"hello": "world"}

Types are supported in order to allow for more advanced filtering. For example, numbers and timestamps can be filtered using greater than/less than operators, in addition to the usual equals/not equals. When adding a custom field you will specify the type as well.

Note: JSON fields do not support filtering. These are mainly useful in the context of tests or metrics builds, where you could store arbitrary metadata on the experience and use it at runtime.

Adding Custom Fields to Experiences

You can add custom fields via our CLI or when using experience syncing. We do not support adding custom fields via our webapp yet.

You can add a Custom Field to an experience when creating or editing an experience:

resim experiences update \
    --experience 2fa0453f-749f-4803-bfcc-91690a831c12 \
    --custom-field weather=sunny \
    --custom-field weather=hot \ # a field can have multiple values
    --custom-field age=23 \
    --custom-field "run time=2025-06-01T12:23:45Z" \ # must be a RFC3339 formatted timestamp
    --custom-field 'raw json={"foo": "bar"}'

You will see the Custom Fields listed under the relevant experience in the webapp.

Custom fields can have a type of text, number, timestamp, or JSON. The specific type changes the filtering options available to you in the UI, see the filtering section for more details.

In certain cases, you may want to explicitly mark the type of a custom field, instead of letting the CLI infer it for you. You can do this by using a colon : in the custom field:

resim experiences update \
    --experience 2fa0453f-749f-4803-bfcc-91690a831c12 \
    --custom-field weather:text=cloudy \
    --custom-field version:number=239.1 \
    --custom-field import_time:timestamp=2025-10-05T12:15:00Z

Removing Custom Fields from Experiences

When updating custom fields on an experience, it replaces all existing custom fields. To remove a field, simple leave it out when performing an update:

resim experiences update \
    --experience 2fa0453f-749f-4803-bfcc-91690a831c12 \
    --custom-field weather=sunny \
    --custom-field weather=hot \
    --custom-field age=23 # "run time" and "raw json" fields will be removed

Filtering

You can filter experiences by their custom values on the Experiences page, as well as when launching a batch or creating/editing a Test Suite.

number and timestamp fields support additional filtering options:

Type	Supported filters
text	=, !=
number	=, !=, <, >
timestamp	=, !=, <, >
json	none, json values are not filterable