Metadata API Developer Guide

Introduction to Metadata API
Using Metadata API
Deploying and Retrieving Metadata
Deploying and Retrieving Metadata with the Zip File
Slow Deployments
Does a Retrieve Job Have a Status of Pending?
Sample package.xml Manifest Files
Running Tests in a Deployment
Running a Subset of Tests in a Deployment
Run Relevant Apex Tests in a Deployment (Beta)
Run the Same Tests in Sandbox and Production Deployments
Limit on Enqueued Deployments from Apex
Maintaining User References
CRUD-Based Metadata Development
REST Resources
Error Handling
Metadata API Context MCP Tool (Beta)
Reference
Appendices
PDF

Note: This release is in preview. Features described here don’t become generally available until the latest general availability date that Salesforce announces for this release. Before then, and where features are noted as beta, pilot, or developer preview, we can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features.

Slow Deployments

If a file-based Metadata API deployment occurs during server downtime, such as a Salesforce service upgrade, the deployment can take longer than expected. This behavior happens because both component deployment and validation are retried from the beginning after the service is restored. However, if Apex tests were part of the deployment, only tests that weren’t run before the downtime are run.

This behavior affects file-based deployment and retrieval, change sets, some package installs and upgrades, second-generation managed package creation, and deploys and retrieves started from the Salesforce CLI or the Salesforce VS Code extensions. It doesn’t affect CRUD-based metadata operations.

If your instance is due for a planned service upgrade, avoid running deployments during the service upgrade. To check whether your Salesforce instance is due for an upgrade, check Salesforce Trust. Salesforce performs major service upgrades three times per year and other maintenance updates throughout the year.