Stay organized with collectionsSave and categorize content based on your preferences.
Holds preserve data indefinitely to meet legal or preservation obligations. Usually holds are placed on one or more users to ensure that the data potentially relevant to a matter cannot be deleted until that matter is no longer active.
If a user who is subject to a hold deletes held data, that data is removed from the user's view, but it is preserved in Vault. As long as the hold is in place, a Vault admin can search and export that data.
Holds have the following components:
A service—the application responsible for the data to be held. The service can be set to mail, Drive, or Groups.
A scope—the entities covered by the hold. The scope can be set to one or more user accounts, or to an organizational unit (OU).
Additional options (optional)—the specific details (search queries or configuration options) used to narrow down the data to be held within the defined scope. Options include:
mail, Groups: search query to narrow down the hold
Drive: include shared drives in the hold
To work with Vault resources, the account must have therequired Vault
privilegesand access to the
matter. To access a matter, the account must have created the matter, have the
matter shared with them, or have theView All Mattersprivilege.
Create a hold for mail on specific user accounts with a search query
The following example shows how a hold named "My First mail Accounts Hold" is created for:
Retrieve user account IDs from theDirectory API.
Note that the HeldAccount can take in account ID or email. If both are given,
email is used and account ID is ignored.
Java
HeldMailQuerymailQuery=newHeldMailQuery().setTerms("to:ceo@company.com");Listaccounts=Lists.newArrayList();accounts.add(newHeldAccount().setAccountId(user1accountId));accounts.add(newHeldAccount().setEmail(user2Email));Holdhold=newHold().setName("My First mail Accounts Hold").setCorpus("MAIL");.setQuery(newCorpusQuery().setMailQuery(mailQuery)).setAccounts(accounts);HoldcreatedHold=client.matters().holds().create(matterId,hold).execute();
Python
defcreate_hold_mail_accounts(service,matter_id,account_id):mail_query={'terms':'to:ceo@company.com'}accounts=[{'accountId':user1_account_id},{'email':user2_email}]wanted_hold={'name':'My First mail Accounts Hold','corpus':'MAIL','query':{'mailQuery':mail_query},'accounts':accounts}returnservice.matters().holds().create(matterId=matter_id,body=wanted_hold).execute()
Create a hold for Drive on an OU and include shared drive content
The following example shows how a hold named "My First Drive OU Hold" is created for:
Service: Drive
Entity: org unit "Finance" (OU ID is captured in orgUnitId)
Additional options: include shared drives that users in this org unit are members of
HeldOrgUnitorgUnit=newHeldOrgUnit().setOrgUnitId(orgUnitId);// Include shared drives content.HeldDriveQuerydriveQuery=newHeldDriveQuery().setIncludeSharedDriveFiles(true);// Create the hold.Holdhold=newHold().setName("My First Drive OU Hold").setCorpus("DRIVE").setQuery(newCorpusQuery().setDriveQuery(driveQuery)).setOrgUnit(orgUnit);HoldcreatedHold=client.matters().holds().create(matterId,hold).execute();returncreatedHold;
Python
defcreate_hold_drive_org(service,matter_id,org_unit_id):drive_query={'includeSharedDriveFiles':True}org_unit={'orgUnitId':org_unit_id}wanted_hold={'name':'My First Drive OU Hold','corpus':'DRIVE','orgUnit':org_unit,'query':{'driveQuery':drive_query}}returnservice.matters().holds().create(matterId=matter_id,body=wanted_hold).execute()
Create a hold for Groups on specific group accounts with a date range
The following example shows how a hold named "My First Group Hold" is created for:
Service: Groups
Entity: group accounts "group1" and "group2"
Additional options: hold only messages with sent dates between "startTime" and "endTime"
StringAPRIL_2_2017_GMT="2017-04-02T00:00:00Z";// See below for format*.Listaccounts=Lists.newArrayList();accounts.add(newHeldAccount().setAccountId(accountId));accounts.add(newHeldAccount().setAccountId(accountId2));HeldGroupsQuerygroupQuery=newHeldGroupsQuery();// Restrict by sent date.groupQuery.setStartTime(APRIL_2_2017_GMT);groupQuery.setEndTime(APRIL_2_2017_GMT);// create the holdHoldhold=newHold().setName("My First Group Hold").setCorpus("GROUPS").setQuery(newCorpusQuery().setGroupsQuery(groupQuery));hold.setAccounts(accounts);HoldcreatedHold=client.matters().holds().create(matterId,hold).execute();
Python
defcreate_hold_groups_date_range(service,matter_id,group_account_id):groups_query={'startTime':'2017-04-02T00:00:00Z',# See below for format*'endTime':'2017-04-02T00:00:00Z'}accounts=[{'accountId':group_account_id}]wanted_hold={'name':'My First Group Hold','corpus':'GROUPS','query':{'groupsQuery':groups_query},'accounts':accounts}returnservice.matters().holds().create(matterId=matter_id,body=wanted_hold).execute()
Timestamp format. Additionally, start/endTimes are converted to GMT and rounded down to the start of the given date.
Query and modify existing holds
The following example shows how to list all of the accounts included in an existing hold:
# If no accounts are on hold, ['accounts'] will raise an error.deflist_held_accounts(service,matter_id,hold_id):returnservice.matters().holds().accounts().list(matterId=matter_id,holdId=hold_id).execute()['accounts']
The following example shows how to add an account to, and remove an account from, an existing hold:
Java
// Add an account by id.client.matters().holds().accounts().create(matterId,holdId,newHeldAccount().setAccountId(accountId)).execute();// Remove an account by id.client.matters().holds().accounts().delete(matterId,holdId,accountId).execute();Stringemail="email@email.com";// Add an account by email.client.matters().holds().accounts().create(matterId,holdId,newHeldAccount().setEmail(email)).execute();
# This can paginate in the same manner as with matters.deflist_holds(service,matter_id):returnservice.matters().holds().list(matterId=matter_id).execute()
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[],[],null,["# Manage Holds\n\nHolds preserve data indefinitely to meet legal or preservation obligations. Usually holds are placed on one or more users to ensure that the data potentially relevant to a matter cannot be deleted until that matter is no longer active.\n\nIf a user who is subject to a hold deletes held data, that data is removed from the user's view, but it is preserved in Vault. As long as the hold is in place, a Vault admin can search and export that data.\n\nHolds have the following components:\n\n- **A service---**the application responsible for the data to be held. The service can be set to mail, Drive, or Groups.\n- **A scope---**the entities covered by the hold. The scope can be set to one or more user accounts, or to an organizational unit (OU).\n- **Additional options (optional)---** the specific details (search queries or configuration options) used to narrow down the data to be held within the defined scope. Options include:\n - mail, Groups: search query to narrow down the hold\n - Drive: include shared drives in the hold\n\nTo work with Vault resources, the account must have the [required Vault\nprivileges](https://support.google.com/vault/answer/2799699) and access to the\nmatter. To access a matter, the account must have created the matter, have the\nmatter shared with them, or have the **View All Matters** privilege.\n| **Note:** A [matter](/workspace/vault/guides/matters) must exist before you can create a hold.\n\nCreate a hold for mail on specific user accounts with a search query\n--------------------------------------------------------------------\n\nThe following example shows how a hold named \"My First mail Accounts Hold\" is created for:\n\n- Service: mail\n- Entity: user accounts \"user1\" and \"user2\"\n- Additional options: search query \"to:ceo@company.com\"\n\nRetrieve user account IDs from the\n[Directory API](/workspace/admin/directory).\nNote that the HeldAccount can take in account ID or email. If both are given,\nemail is used and account ID is ignored. \n\n### Java\n\n```java\nHeldMailQuery mailQuery = new HeldMailQuery().setTerms(\"to:ceo@company.com\");\nList accounts = Lists.newArrayList();\naccounts.add(new HeldAccount().setAccountId(user1accountId));\naccounts.add(new HeldAccount().setEmail(user2Email));\nHold hold = new Hold()\n .setName(\"My First mail Accounts Hold\")\n .setCorpus(\"MAIL\");\n .setQuery(new CorpusQuery().setMailQuery(mailQuery))\n .setAccounts(accounts);\nHold createdHold = client.matters().holds().create(matterId, hold).execute();\n \n```\n\n### Python\n\n```python\ndef create_hold_mail_accounts(service, matter_id, account_id):\n mail_query = {'terms': 'to:ceo@company.com'}\n accounts = [\n {'accountId': user1_account_id},\n {'email': user2_email}\n ]\n wanted_hold = {\n 'name': 'My First mail Accounts Hold',\n 'corpus': 'MAIL',\n 'query': {\n 'mailQuery': mail_query\n },\n 'accounts': accounts\n }\n return service.matters().holds().create(\n matterId=matter_id, body=wanted_hold).execute()\n```\n\nCreate a hold for Drive on an OU and include shared drive content\n-----------------------------------------------------------------\n\nThe following example shows how a hold named \"My First Drive OU Hold\" is created for:\n\n- Service: Drive\n- Entity: org unit \"Finance\" (OU ID is captured in orgUnitId)\n- Additional options: include shared drives that users in this org unit are members of\n\nRetrieve OU IDs from the [Directory API](/workspace/admin/directory). \n\n### Java\n\n```java\nHeldOrgUnit orgUnit = new HeldOrgUnit().setOrgUnitId(orgUnitId);\n// Include shared drives content.\nHeldDriveQuery driveQuery = new HeldDriveQuery().setIncludeSharedDriveFiles(true);\n// Create the hold.\nHold hold = new Hold()\n .setName(\"My First Drive OU Hold\")\n .setCorpus(\"DRIVE\")\n .setQuery(new CorpusQuery().setDriveQuery(driveQuery))\n .setOrgUnit(orgUnit);\nHold createdHold = client.matters().holds().create(matterId, hold).execute();\nreturn createdHold;\n```\n\n### Python\n\n```python\ndef create_hold_drive_org(service, matter_id, org_unit_id):\n drive_query = {'includeSharedDriveFiles': True}\n org_unit = {'orgUnitId': org_unit_id}\n wanted_hold = {\n 'name': 'My First Drive OU Hold',\n 'corpus': 'DRIVE',\n 'orgUnit': org_unit,\n 'query': {\n 'driveQuery': drive_query\n }\n }\n return service.matters().holds().create(\n matterId=matter_id, body=wanted_hold).execute()\n```\n\nCreate a hold for Groups on specific group accounts with a date range\n---------------------------------------------------------------------\n\nThe following example shows how a hold named \"My First Group Hold\" is created for:\n\n- Service: Groups\n- Entity: group accounts \"group1\" and \"group2\"\n- Additional options: hold only messages with sent dates between \"startTime\" and \"endTime\"\n\nRetrieve group account IDs from the\n[Directory API](/workspace/admin/directory). \n\n### Java\n\n```java\nString APRIL_2_2017_GMT = \"2017-04-02T00:00:00Z\"; // See below for format*.\n \nList accounts = Lists.newArrayList();\naccounts.add(new HeldAccount().setAccountId(accountId));\naccounts.add(new HeldAccount().setAccountId(accountId2));\nHeldGroupsQuery groupQuery = new HeldGroupsQuery();\n// Restrict by sent date.\ngroupQuery.setStartTime(APRIL_2_2017_GMT);\ngroupQuery.setEndTime(APRIL_2_2017_GMT);\n// create the hold\nHold hold = new Hold()\n .setName(\"My First Group Hold\")\n .setCorpus(\"GROUPS\")\n .setQuery(new CorpusQuery().setGroupsQuery(groupQuery));\n hold.setAccounts(accounts);\nHold createdHold = client.matters().holds().create(matterId, hold).execute();\n \n```\n\n### Python\n\n```python\ndef create_hold_groups_date_range(service, matter_id, group_account_id):\n groups_query = {\n 'startTime': '2017-04-02T00:00:00Z', # See below for format*\n 'endTime': '2017-04-02T00:00:00Z'\n }\n accounts = [{'accountId': group_account_id}]\n wanted_hold = {\n 'name': 'My First Group Hold',\n 'corpus': 'GROUPS',\n 'query': {\n 'groupsQuery': groups_query\n },\n 'accounts': accounts\n }\n return service.matters().holds().create(\n matterId=matter_id, body=wanted_hold).execute()\n \n```\n\n- [Timestamp format](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto#L99). Additionally, start/endTimes are converted to GMT and rounded down to the start of the given date.\n\nQuery and modify existing holds\n-------------------------------\n\nThe following example shows how to list all of the accounts included in an existing hold: \n\n### Java\n\n```java\nclient.matters().holds().accounts().list(matterId, holdId).execute().getAccounts();\n```\n\n### Python\n\n```python\n# If no accounts are on hold, ['accounts'] will raise an error.\ndef list_held_accounts(service, matter_id, hold_id):\n return service.matters().holds().accounts().list(\n matterId=matter_id, holdId=hold_id).execute()['accounts'] \n```\n\nThe following example shows how to add an account to, and remove an account from, an existing hold: \n\n### Java\n\n```java\n// Add an account by id.\nclient\n .matters()\n .holds()\n .accounts()\n .create(matterId, holdId, new HeldAccount().setAccountId(accountId))\n .execute();\n// Remove an account by id.\nclient.matters().holds().accounts().delete(matterId, holdId, accountId).execute();\n\nString email = \"email@email.com\";\n// Add an account by email.\nclient\n .matters()\n .holds()\n .accounts()\n .create(matterId, holdId, new HeldAccount().setEmail(email))\n .execute();\n```\n\n### Python\n\n```python\n \ndef add_held_account(service, matter_id, hold_id, account_id):\n held_account = {'accountId': account_id}\n return service.matters().holds().accounts().create(\n matterId=matter_id, holdId=hold_id, body=held_account).execute()\n\ndef remove_held_account(service, matter_id, hold_id, account_id):\n return service.matters().holds().accounts().delete(\n matterId=matter_id, holdId=hold_id, accountId=account_id).execute()\n\ndef add_held_account(service, matter_id, hold_id, email):\n held_account = {'email': email}\n return service.matters().holds().accounts().create(\n matterId=matter_id, holdId=hold_id, body=held_account).execute()\n \n```\n\nThe following example shows how to modify the OU on an existing OU hold: \n\n### Java\n\n```java\nHold hold = client.matters().holds().get(matterId, holdId).execute();\nhold.getOrgUnit().setOrgUnitId(newOrgUnitId);\nHold modifiedHold = client.matters().holds().update(matterId, holdId, hold).execute();\nreturn modifiedHold;\n \n```\n\n### Python\n\n```python\ndef update_hold_ou(service, matter_id, hold_id, org_unit_id):\n current_hold = get_hold(matter_id, hold_id)\n current_hold['orgUnit'] = {'orgUnitId': org_unit_id}\n return service.matters().holds().update(\n matterId=matter_id, holdId=hold_id, body=current_hold).execute() \n```\n\nThe following example shows how to list all holds for a matter: \n\n### Java\n\n```java\n \nString matterId = \"Matter Id\";\n\n// List all holds.\nList holdsList = \n client.matters().holds().list(matterId).execute().getHolds();\n\n// Paginate on holds.\nListHoldsResponse response = client\n .matters()\n .holds()\n .list(matterId)\n .setPageSize(10)\n .execute();\n\nString nextPageToken = response.getNextPageToken();\nif (nextPageToken != null) {\n client\n .matters()\n .holds()\n .list(matterId)\n .setPageSize(10)\n .setPageToken(nextPageToken)\n .execute();\n}\n \n```\n\n### Python\n\n```python\n# This can paginate in the same manner as with matters.\ndef list_holds(service, matter_id):\n return service.matters().holds().list(matterId=matter_id).execute()\n \n```\n\n\u003cbr /\u003e"]]
