Considerations and requirements
You'll need a Teams or Enterprise license to use this feature
What is the Audit API?
The Audit API is one of three Gearset APIs, along with the Automation API and the Reporting API. It provides the following information:
Standard deployment information (e.g. who ran the deployment, when they did it, and the deployment status).
More granular deployment information, including:
all the objects that were deployed
why they were deployed (PA, change, deletion, etc.)
the modified information
relevant source and target information
the SalesforceFinalDeploymentId.
Salesforce Connections and if they are user owned or Team Shared
The linked work items (Jira, ADO, etc.).
NB: This information is available for every deployment done through Gearset (including CI and C+D).
Making your first Audit API requests
To use the Audit API, you'll need an API access token, which you can generate by following our tutorial: Creating a Gearset API access token. Once you have that, you're ready to start making API requests.
The Audit API is a REST API that returns JSON messages over HTTPS, and we'll be using the Audit API's dynamic documentation to query it.
First, log in with your access token by clicking on the
Authorizebutton:
2. Enter the authorization token that you got earlier, prefixed with the word "token":
3. Go to the Deployment audit section, and click on the Try it out button:
The Audit API currently exposes only one method — Deployment audit.
4. To perform the query, fill in the time frame, enter any optional parameters for JiraTickets/AsanaTasks/AzureDevOpsWorkItems (if required), and click Execute. (NB: the response can be pretty large, so we recommend that you make your time range as small as possible.)
This will send off a request to the Audit API. Once executed, it presents the curl command used (so you can use it elsewhere) and the response. This can be copied or downloaded:
And here in the Response object is some of the deployment data that can be accessed:
An ideal question that can be answered using the Audit API would be: "which deployments in the time frame involved X metadata items?", where X represents some particularly restrictive metadata types that you want to keep a close eye on.
The answers to these questions can then be displayed in a spreadsheet (or an alternative visualization/graphing application that takes JSON), as with the following example:
FAQ
Q: Do customers need to be running Pipelines for the Audit API to work?
A: No. Audit API works for the whole Gearset app.
Q: Could this API be used to create a report showing which users deployed most often over a given period (e.g. a year)?
A: Yes, although the Reporting API can do that, too (its Deployment Frequency end-point is built specifically for that purpose).
Q: Can the results be filtered for deployments made to Production orgs? We have a few teams who would like to identify their power users.
A: Yes, TargetMetadataLocationType, found in both the Audit and the Deployment Frequency end-point (Reporting API), defines the target and says whether it's production or another target.