Requirements
A Teams or Enterprise Automation Platform license.
The Gearset pipelines feature configured with the expanded branching model. This is currently not compatible with Gitflow or Layered Modules pipelines.
Change failure management configured for meaningful CFR and MTTR data. See getting started with change failure management.
If you'd prefer to track these metrics directly in Gearset, please refer to our dashboard documentation here.
What the Reporting API provides?
The Gearset Reporting API returns deployment data for a given pipeline. Each deployment includes its outcome, timestamp, and the Salesforce org it targeted. Where deployments were made from pull requests, each deployment also includes those PRs and their associated feature branches from earlier in the pipeline, with timing data such as when the first commit was made and when the PR was created and merged.
One of the primary use cases for this data is calculating DORA metrics for production deployments. If you're looking to do that, start here to understand the API and its response schema, then follow the guidance here.
What's new in v3?
Explicit failure recording replaces heuristics
In v1 and v2, Gearset inferred failures automatically: hotfixes merged directly to production, revert pull requests, and rollbacks. However, these heuristics were imprecise and could produce misleading CFR and MTTR figures.
In v3, failures are recorded explicitly by your team using Gearset's change failure management feature. A team member marks a production deployment as a bug, sets its severity, and links a fix. Gearset tracks resolution from that explicit signal. This produces accurate, auditable data that reflects what actually happened.
The endpoints and response schema have changed
v3 returns a single unified JSON response per request. There are no separate raw and aggregate endpoints. Field names have also been updated. See the schema reference below.
Performance improvements
If you've used an earlier version of the Reporting API, you'll also notice the following improvements:
Metrics load faster: Metrics no longer require real-time calls to your version control system. All the data needed is stored and maintained on Gearset's side.
Loading metrics no longer affects other Pipelines activity: Previously, for some teams with high pipeline activity, requesting metrics could temporarily slow down or block other pipeline actions, such as opening or promoting pull requests. This is no longer the case.
Querying the API
We've added code samples that showcase how different DORA metrics are calculated that closely match DevOps performance dashboard. You can find them here.
Available Endpoints
There are two endpoints:
The deployments endpoint returns deployment data for a given pipeline, optionally filtered by one or more environments. Each deployment in the response includes its status, timestamp, target org, any reported bugs, and the pull requests that made up the deployment package.
The environments endpoint returns the list of environments configured for a given pipeline, including their IDs and target org details. You can use this to look up the environment ID you need before calling the deployments endpoint.
The deployments endpoint uses the concept of operations with an asynchronous API that allows you to request data to be retrieved at a later time when it is ready. This means retrieving data involves three steps:
Start the operation: POST to
/public/reporting/deploymentswith your inputs. The response returns anOperationStatusId.Poll for completion: GET
/public/operation/{operationId}/statusuntil the operation is no longerRunning.Retrieve the result: GET
/public/operation/{operationId}/resultto get the deployment JSON.
Authentication
You'll need a Gearset API access token. Follow Creating a Gearset API access token if you don't have one. From here, you can explore the API using our dynamic documentation. Select Reporting API v3 from the "Select a definition" dropdown in the top right of the page:
Click Authorize, enter your API access token prefixed with the word token, and click Authorize again to authenticate.
Deployments Example
Step 0 (optional): Look up your environment IDs
Use the environments endpoint to get the static environments configured for a given pipeline, including the IDs and target org details you need to call the deployments endpoint. You'll first need to get the ID of your pipeline. To do so, visit the pipeline in Gearset and copy the ID from the URL bar:
Open the environments endpoint. Click the Try it out button, and enter your pipeline ID from above:
Once that is done, click Execute to see the results:
The response will contain array of environment objects, one per environment in the pipeline. You can use one or more of these IDs to filter the response from the deployments endpoint as explained below.
If you do not pass in environment IDs to the deployments endpoint, it will return results for all environments in that pipeline.
Step 1: Start the operation
Use the deployments endpoint to retrieve the deployments for a given pipeline. Open the deployments endpoint, click the Try it out button and enter:
The date range (UTC) you want to retrieve deployments for. You'll only see results for deployments that occurred between the start and end dates entered.
Your pipeline ID.
Optionally: One or more environment IDs
Once you have provided those inputs, click Execute. This will send a request to the Reporting API v3 to start the operation:
The response will provide a OperationStatusId. Take note of this value as you'll use it to poll of status of your operation.
Step 2: Poll for completion
You'll use the operation status endpoint to check the status of the operation. Click the Try it out button, enter the OperationStatusId from above and click Execute:
Poll this endpoint until Status is no longer Running. To avoid being rate limited, don't poll more frequently than once every five seconds. When the operation completes successfully, the response returns a Status of Succeeded and an OperationResultId property:
Take note of this value as you'll use it to retrieve the results of the operation.
If the operation fails, the response returns a Status of Failed and an Error property describing what went wrong:
Step 3: Retrieve the result
You'll use the operation result endpoint to retrieve the results of the operation. Click the Try it out button, enter the OperationResultId from above and click Execute. The response body will contain the deployments associated with your request:
Key information about the response schema:
The response contains a single top-level array called
Deployments. Each item in that array represents one deployment event.Each deployment object also contains a
DeploymentPullRequestsarray. If the deployment was a result of promoting one or more PRs (including releases), this array will be populated with the feature branch PRs.Each item in that array (
PullRequest) represents an individual PR that was part of the deployment package. Alongside eachPullRequest, you'll find aFeaturePullRequestsarray containing the earliest record of that feature branch in the pipeline. This is the PR as it was first opened in the pipeline and is key data for lead time calculations.Each deployment object also contains a
ReportedBugsarray. This is only populated for production deployments where your team is actively using change failure management. In all other cases, it will be null. Where populated, it holds any bugs your team has explicitly recorded against that deployment, with each bug carrying a severity, the date it was identified, and when it was resolved.
Feedback
If you have questions or feedback on this document or the Reporting API, please get in touch with us via the in-app chat. We would love to hear your suggestions.