SandboxInfo | Tooling API | Salesforce Developers

SandboxInfo enqueues a sandbox for creation or refresh. A create operation on SandboxInfo represents creation of a new sandbox, and an update represents refresh of an existing sandbox. For every creation or update, a SandboxProcess is automatically created and is used for monitoring the sandbox copy process.

This object is available in API version 35.0 and later.

Supported SOAP Calls

create(), delete(), query(), retrieve(), update()

Supported REST HTTP Methods

GET, PATCH, POST, DELETE

Fields

Field	Details
ActivationUserGroupId	Type reference Properties Create, Filter, Group, Nillable, Sort, Update Description A reference to the ID of the public group consisting of users who can access the sandbox. The user who created the sandbox is added to the group by default. This field is a relationship field. Restrictions You can specify this value only during sandbox creation and refresh. Available in API version 60.0 and later. Behavior change announcement: Starting in Spring ’25, this field will be required when creating or refreshing a Developer or Developer Pro sandbox. To avoid losing the ability to create or refresh Developer and Developer Pro sandboxes, use API version 60.0 or later. Relationship Name ActivationUserGroup Relationship Type Lookup Refers To Group
ApexClassId	Type reference Properties Create, Filter, Group, Nillable, Sort, Update Description A reference to the ID of an Apex class that runs after each copy of the sandbox. Allows you to perform business logic on the sandbox to prepare it for use. Restrictions You can specify this value only during sandbox creation. The class must extend the `System.SandboxPostCopy` interface. Available in API version 36.0 and later. Relationship Name ApexClass Relationship Type Lookup Refers To ApexClass
AutoActivate	Type boolean Properties Create, Defaulted on create, Filter, Group, Sort, Update Description If `true`, you can activate a sandbox refresh immediately. Restrictions This field only affects behavior for update operations (Sandbox refresh).
CopyArchivedActivities	Type boolean Properties Create, Defaulted on create, Filter, Group, Sort, Update Description If `true`, archived activity data is copied to the sandbox. Restrictions This field is visible only if your organization has purchased an option to copy archived activities for sandbox. To obtain this option, contact Salesforce Customer Support. You can set the value to `true` only for a Full sandbox.
CopyChatter	Type boolean Properties Create, Defaulted on create, Filter, Group, Sort, Update Description If `true`, archived Chatter data is copied to the sandbox. Restrictions You can set the value to `true` only for a Full sandbox.
Description	Type string Properties Create, Filter, Nillable, Sort, Update Description A description of the sandbox, which helps you distinguish it from other sandboxes. Restrictions The description length can’t exceed 1,000 characters.
Features	Type textarea Properties Create, Nillable, Update Description The add-on features to apply when creating or refreshing the sandbox. Currently there’s one valid value: `['SandboxStorage']`: Increases the data storage available for Developer sandboxes from 200 MB to 400 MB and Developer Pro sandboxes from 1 GB to 2 GB. You can’t use this feature with Partial Copy or Full sandboxes.
HistoryDays	Type int Properties Create, Defaulted on create, Filter, Group, Sort, Update Description Represents the number of days of object history to be copied in the sandbox. Valid values: `-1`, which means all available days `0` (default) `10` `20` `30` `60` `90` `120` `150` `180` Restrictions This field affects behavior only for Full sandboxes.
LicenseType	Type picklist Properties Create, Filter, Group, Restricted picklist, Sort, Update Description Represents the sandbox license type. Valid values: `DEVELOPER` `DEVELOPER_PRO` `PARTIAL` `FULL`
SandboxName	Type string Properties Create, Filter, Group, idLookup, Sort, Update Description Name of the sandbox. Restrictions Must be a unique sandbox name. Must be alphanumeric characters. Must be 10 or fewer characters. Can’t be the same as the name of a sandbox that’s pending deletion.
SourceId	Type reference Properties Create, Filter, Group, Nillable, Sort, Update Description A reference to the ID of a SandboxInfo that serves as the source org for a cloned sandbox. Relationship Name Source Relationship Type Lookup Refers To SandboxInfo
TemplateId	Type reference Properties Create, Filter, Group, Nillable, Sort, Update Description A reference to the PartitionLevelScheme that represents the sandbox template associated with this sandbox. A sandbox template lets you select which objects to copy in a sandbox. To use the TemplateId field, you must have the ManageSandboxes user permission. Restrictions Setting a TemplateId value for a Partial Copy sandbox is required. Setting a TemplateId value for a Full sandbox is optional. Setting a TemplateId value for other sandbox types is prohibited, because other sandbox types don’t support sandbox templates. Relationship Name Template Relationship Type Lookup Refers To PartitionLevelScheme

Usage

SandboxInfo and SandboxProcess work together to manage the creation or refresh of a sandbox.

Creating a Sandbox

To enqueue a new sandbox:

Create a SandboxInfo record.
To find the status of a sandbox after it is enqueued, query SandboxProcess for a given SandboxInfoId field to find the latest SandboxProcess record. The value of Completed in Status indicates that the creation process is finished.

Refreshing a Sandbox

To refresh a sandbox:

To start a sandbox refresh, edit the SandboxInfo record.
To find the status of a sandbox after it is enqueued, find the latest SandboxProcess record by querying SandboxProcess for a given SandboxInfoId value. The value of Status indicates the current state of the process.
When the Status field value is Pending Activation, change the value of the RefreshAction field to either ACTIVATE or DISCARD.

Deleting a Sandbox

To delete a sandbox, delete the SandboxInfo record that represents the sandbox. Deleting the SandboxInfo record deletes the sandbox and frees up a license.

Checking Sandbox Progress

Each SandboxProcess record progresses through several stages represented by the StageType and StageNumber on the SandboxProcessStage record. The system updates progress details as the copy proceeds. For every stage, you can view specifics using the Status, StartTime, EndTime, and InfoLastUpdated fields.

If your sandbox status is suspended or stopped for more than 1 hour, contact Salesforce customer support.

While the system can't provide a time-based estimate, you can track your place in the queue or how much work exists and has been completed.

During the In Queue stage, you can check your current place in the queue with the EstimatedTotalWork field.
During the Data Copy and Activation stages, you can check how much work exists and has been completed to estimate copy completion with the EstimatedTotalWork, ActualTotalWork, and CompletedWork fields.

If IsActualWorkFinal = true, then ActualTotalWork is a better representation of the total work required.
If IsActualWorkFinal = false, then EstimatedTotalWork is a better representation of the total work required.

Note