Skip to content

Tag Management


Use tags in Flywheel to annotate your data, so you can then search on and filter data based on those tags. Creating tags is a 2-step process. First create your new tags at the group level. Next, you can add those tags to containers in Flywheel.

Instruction Steps

Step 1: Create new tags in Groups

Any new tags must be created at the group level. To create new tags:

  1. Sign in to Flywheel.
  2. Click Groups in the left navigation menu.
  3. Select a group.
  4. Click the Tags tab.


  5. Enter a tag name, and click Add.

This tag is now available to add to other containers.


  • Tag names are not case sensitive. Meaning if the tag CONTROL already exists in a group, you cannot add a control tag.
  • You can use the same tag name across multiple groups in Flywheel. When you search, all data associated with that tag name appears.
  • Editing or deleting a tag name will change it throughout Flywheel.

Search for Tagged Data

Basic Search: Enter the tag name in the search bar


  • Search results include any data that is associated with the group where the tag was created.
  • If you added the same tag name to multiple groups, data associated with each group appears in the results.

Advanced Search:

  1. In the Search bar, hit enter.
  2. Click Advanced Search.
  3. In Field, enter tags to bring up a list of all of your tag fields. By default, those fields are group.tags or subject.tags.


    If you added tags using the SDK, you will have additional fields.

  4. Choose an operator. See our Advanced Search documentation for more information.

  5. In Value(s), enter one or more tag names.
  6. Add more Terms or Term Groups.
  7. Once complete, click Run Query.

Step 2: Add tags

In Flywheel you can add tags to sessions and subjects. To do this:

Add Tags to Sessions

  1. Click Projects.
  2. Select a project.
  3. Select the Sessions tab.

    All sessions for that project appear.

  4. Select a session.


  5. In the left panel, click Sessions and go to Tags.

  6. Start typing in a tag name. Available tag names appear in a list.
  7. Continue with each session that you want to tag.

Add Tags to Subjects

  1. Click Projects.
  2. Select a project.
  3. Select the Sessions tab.
  4. (Optional) Click The subject view button to enable Subject View.
  5. Select the subject you want to tag.


  6. In left panel click the Subject tab, and go to Tags.

  7. Start typing a tag name. Available tag names appear in the list.
  8. Continue with each subject you want to tag.

Add tags to Gear runs

When configuring a Gear to run, enter the tag. This tag will be attached to the Gear job itself. Gear tags are useful on jobs because you can use them to search for outputs, perform bulk action on output files, or even trigger another Gear.


Gear tags do not need to be added to the Group. You can add new tags for Gear Jobs in the configuration tab.

To add a tag to a Gear Job:

  1. Navigate to a session, and click the checkbox.
  2. Select an acquisition.

    Batch run Gears

    To run a Gear against multiple sessions or acquisitions at the same time, use batch processing

  3. Click Run Gear.


  4. Select Utility or Analysis.

  5. Choose a gear from the list.
  6. Enter one or more tag in the Job Tags field
  7. Select the Configuration tab to edit any additional settings.
  8. Click Run Gear.

The tag is now associated with the job.

Use the SDK

Use the SDK to add tags in batches. Below is an example of interacting with session tags. See the Flywheel SDK for more information.

# See tags on a session
session = fw.get(session_id)
print(', '.join(session.tags)) 

# Add a tag named Control to a session

# Remove a tag from a session
session.delete_tag('Analysis Required')

# Add a tag to a file 
acq = fw.get('60eda95598612d4e6d5b8da9')
for file in acq.files: