Audit Trail API
The Audit Trail API allows you to list all added, updated, and deleted metadata in the catalog; this includes users, contacts, groups/permission sets, and data access requests.
Following are some examples, detailing how these APIs could be used (the requests used are detailed in the "Using the API" section):
Data catalog items audit trail:
Example 1: I want to list all changes made on all objects contained in the Catalog, over the last two days.
Example 2: I want to list all changes made by a specific user on all Items in the Catalog, over a given time range.
Example 3: I want to list all changes made on the “Customers” dataset in 2021.
Users and Contacts audit trail:
Data access requests audit trail:
The API technical documentation is provided in this section.
Permissions
The recommended permission scope for the Audit Trail API is Read-only.
Documentation and Tools
The full technical documentation for the Zeenea Audit Trail API can be retrieved by sending a GET request (using any API Platform such as Postman) to the following endpoint:
https://[instance-name].zeenea.app/public-api/management/audit/docs
Authentication
To use the API, you must authenticate using an API key at the following endpoint:
https://[instance-name].zeenea.app/public-api/management/audit
Most of the APIs use the POST method.
Follow these steps to authenticate using your API key:
Create a new API key in Zeenea Administration. For detailed steps, see
Create an API key.
In your HTTP Request headers, add the following value:
"X-API-SECRET": "$APISECRET"
Replace $APISECRET with the API secret that you retrieved when creating the key.
Examples
Example 1: I want to list all changes made on all objects contained in the Catalog, over the last two days.
{
"from": "2021-07-25T00:00:00.000Z",
"to": "2021-07-27T00:00:00.000Z",
"eventType": "Item"
}
Example 2: I want to list all changes made by a specific user on all Items in the Catalog, over a given time range.
{
"from": "2021-04-01T00:00:00.000Z",
"to": "2021-04-30T00:00:00.000Z",
"eventType": "Item",
"originId": "9b27a985-6fa3-4358-898c-462f7c491202"
}
Example 3: I want to list all changes made on the “Customers” dataset in 2021.
{
"from": "2021-01-01T00:00:00.000Z",
"to": "2021-12-31T00:00:00.000Z",
"eventType": "Item",
"resourceId": "c89862e8-1002-4dff-92d6-fd7d5bb57b6c"
}
Important: The item ID can be retrievable with the help of the Exploration APIs or it can be found in the URL of a specific item. As an example, after having accessed an item, its ID was retrieved from its URL:
https://[instance-name].zeenea.app/studio/dataset/c89862e8-1002-4dff-92d6-fd7d5bb57b6c/general
The ID is string like c89862e8-1002-4dff-92d6-fd7d5bb57b6c.
Example 4: I want to list all changes made to users and contacts over the last month.
{
"from": "2021-11-01T00:00:00.000Z",
"to": "2021-11-30T00:00:00.000Z",
"eventType": "User"
}
Example 5: I want to list all changes made to groups/permission sets in 2021.
{
"from": "2021-01-01T00:00:00.000Z",
"to": "2021-12-31T00:00:00.000Z",
"eventType": "PermissionSet"
}
Example 6: I want to list all access requests and their status transitions over the last month.
{
"from": "2024-11-01T00:00:00.000Z",
"to": "2024-11-30T00:00:00.000Z",
"eventType": "DataAccessRequest"
}
Example 7: I want to list all changes made to the data access request policies in 2024.
{
"from": "2024-01-01T00:00:00.000Z",
"to": "2024-12-31T00:00:00.000Z",
"eventType": "Policy"
}
API Responses
Requested data will be returned by the API in the following format:
"data": [
{
"id": "e955bfb3-c316-421a-aa03-04471cc9bcí4",
"timestamp": "2023-12-27T15:14:46.360131498Z",
"eventType" : "Item",
"origin": {
"id" : "55bleO42-680f-4164-8e86-cl211c46a7f4',
"originType": "User"
},
"value": {
"Personal data": "No"
},
"itemld": "7813408d-í3cí-49c5-91fe-ba0ílb0aa312",
"itemName": "First instance",
"itemEventType": "Updateitem"
}
...
]
Note: In case you wish to access more details on a specific item, we recommend using the Exploration APIs.
Note that, when multiple updates are done at the same time, the API will behave differently depending on the type of items:
For objects, the API will return one event per edited value.
For users, contacts, and permission sets: the API will only return one event, listing all updates ran concurrently.
Performance
For each call, the Audit Trail API can return a maximum of 100 events. If the API is to return additional items, the “cursorMark” attribute at the end of the pagination element will not be null. To retrieve those additional items, you will need to use that cursor.
{
(...)
"pagination": {
"cursorMark": "#126:38"
}
}
For example, if I wish to retrieve all changes (on all items in the catalog) made after the cursorMark “#126:38”, the request will look like this:
{
"from": "2021-04-01T00:00:00.000Z",
"to": "2021-04-30T00:00:00.000Z",
"cursorMark": "#126:38"
}
If the API response contains no more events, the cursorMark value will become null.
Limitations
For all "Link" type properties (curators, categories, business terms, data processes, visualizations, and natural keys), the API can only retrieve the updated values.
For example, if a user adds two new curators (C and D) on a Dataset already assigned to curators A and B, the Audit Trail API will only retrieve the last two events, with the following values:
{
(...)
"value": ,
(...)
}
and
{
(...)
"value": ,
(...)
}
The "previousValue" event is currently not returned by the API for these types.
For example, if a user only updates Lines 1 and 4 of a description property, the Audit Trail API will return the following values:
{
(...)
"Line 1": ,
(...)
}
and:
{
(...)
"Line 4": ,
(...)
}
For Custom Items, the Audit Trail API won’t retrieve their IDs, but only their names (which can be edited).
Scanner and API Keys-related events can’t be retrieved for the following reasons:
The API cannot retrieve events that occurred before its roll-out date (December 20th, 2021).