GET /audit-events¶
Amperity maintains records of all user activity that occured in your tenant. For example:
A user makes a configuration change to the Amperity platform
A user creates a sandbox
A user views personally identifiable information (PII)
A workflow was stopped by a user
A user configured a destination
A user created an API key
A user was assigned to a resource group
Use the /audit-events endpoint to return a log of user activity that occurred with your tenant. Each response may contain up to 1000 audit events.
Note
When requesting events for a production tenant, audit events for sandboxes are included in the response. When requesting events from a sandbox, only events from that sandbox are included in the response.
Available HTTP methods¶
Prerequisites¶
Each request to an endpoint in the Amperity API must be authenticated.
Base URL¶
All requests made to the /audit-events endpoint should be directed to the following base URL:
https://{tenant-id}.amperity.com/api/audit-events/
Rate limit¶
A rate limit is the number of requests that may be made to the Amperity API in a given time period.
The Amperity API supports requests to endpoints that do not exceed a rate of 10 requests per second. Response times will vary by endpoint and the complexity of data that is returned by the response. Some requests may take seconds to return.
Requests to the Amperity API that exceed 10 requests per second may return an error response with an HTTP 429 status code.
Requests¶
A request to the /audit-events endpoint is similar to:
curl --request GET \
'https://tenant.amperity.com/api/audit-events \
?limit=10 \
?with_total=true \
?happened_start=2024-04-01 \
?happened_end=2024-04-10' \
--header 'amperity-tenant: tenant' \
--header 'api-version: 2024-04-01' \
--header 'Authorization: Bearer token'
(This example is formatted for readability in a narrow page layout.)
Request parameters¶
The following table describes the parameters that may be used with the /audit-events endpoint.
Parameter |
Description |
|---|---|
api_version |
String. Optional. A supported version of the Amperity API. For example: 2024-04-01. Note You may use the api-version request header instead of the api-version request parameter. |
happened_end |
String. Optional. The end date (exclusive) that defines the end of the time range for which audit events will be returned. For example: “2024-03-01T11:11:11Z”. The values for the end date must be a string, should be in ISO 8601 format, and should be in UTC. |
happened_start |
String. Optional. The start date (inclusive) that defines the beginning of the time range for which audit events will be returned. For example: “2024-04-01T11:11:11Z”. The start date must be a string, should be in ISO 8601 format, and should be in UTC. |
limit |
Integer. Optional. The maximum number of records to include in a single page of results. |
next_token |
String. Optional. An opaque token that is used to paginate results. Omit the next_token property to return the first page. Use the cursor value for next_token that was returned in a response to view the next page of results. For example: ABCd1fghIJk2l3M Note The possible values for next_token are returned within the 200 response. Important The value for next_token cannot be NULL. |
with_total |
Boolean. Optional. Set this value to true to include a total count of all results. Default value: false. Note Obtaining the total count of all results can be an expensive operation when there is a high number of pages in the results set. |
Request examples¶
The following examples show how to send requests to the /audit-events endpoint.
cURL¶
The following example shows how to use cURL to send a request to the /audit-events endpoint.
curl --request GET \
'https://tenant.amperity.com/api/audit-events \
?limit=10 \
&with_total=true \
&happened_start=2024-04-01 \
&happened_end=2024-04-10' \
--header 'amperity-tenant: tenant' \
--header 'api-version: 2024-04-01' \
--header 'Authorization: Bearer token'
(This example is formatted for readability in a narrow page layout.)
Python¶
The following example shows how to use Python to send a request to the /audit-events endpoint. This example converts the JSON response into a CSV file named “audit_events.csv”.
import requests
import json
import csv
# URL for Audit Events endpoint
url = "https://tenant-name.amperity.com/api/audit-events"
# Required headers
headers = {
'accept': 'application/json',
'authorization': 'Bearer token', # add token here
'amperity-tenant': 'tenant-name'
}
# Query parameters for time ranges
payload = {
# 'happened_start': '',
# 'happened_end': ''
}
# Get the response from the endpoint
response = requests.request("GET", url, headers=headers, params=payload)
response_json = response.json()
# Extract headers from the first data entry
headers = list(response_json["data"][0].keys())
# Specify the output CSV file path
csv_file_path = "audit_events.csv"
# Write data to a CSV file
with open(csv_file_path, mode='w', newline='') as file:
writer = csv.DictWriter(file, fieldnames=headers)
writer.writeheader()
for entry in response_json["data"]:
writer.writerow(entry)
print("CSV file generated successfully.")
Responses¶
A response from the /audit-events endpoint will match an HTTP status code. A 200 response will contain the results set. A 4xx response indicates an issue with the configuration of your request. A 5xx response indicates that the endpoint is unavailable.
200 OK¶
A successful request made to the /audit-events endpoint will return a response with up to 1000 audit events, similar to:
{
"data": [
{
"tenant": "socktown",
"principal_name": "Socktown User",
"object_id": "aud-20240409-55140-aBCDEFg1hiK",
"happened_at": "2024-04-09T15:19:00.636Z",
"tenant_family": "family",
"principal_email": "user@socktown.com",
"principal_id": "google-apps|user@socktown.com",
"origin_ip": "111.11.111.1",
"event_id": "ae-Ab1cDeFgHijkLMN2Op3QrS",
"event_type": "amperity.alert.audience/created"
}
],
"total": 102,
"next_token": "PAGE_TOKEN"
}
Response parameters¶
A 200 OK response contains the following parameters.
Parameter |
Description |
|---|---|
data |
A JSON array of values for the current page of results. The array of values includes the following properties:
|
next_token |
The cursor value to use in a subsequent request to return the next page of results. Note When the value for next_token is empty, the last page in the results set has been returned. |
total |
The total count of all results. This property is only returned when with_total is set to true in a request. Note Obtaining the total count of all results can be an expensive operation when there is a high number of pages in the results set. |
Common event types¶
The following table lists the most common event types, grouped by the component or area within Amperity that is most closely associated with the event type.
Note
Many events are prefixed with a dot-delimited string that typically starts with “amperity”. The specific event is located after a slash (“/”). The following table lists the events by the strings immediately before and after the slash.
For example, the following event:
:amperity.plugin.destination/created
is shown in the following table as:
destination/created
If your tenant shows an event that is not listed in this table, its purpose can often be inferred by the string and the event after the trailing slash. You may open a support ticket to request more information about an event that is not shown in this table. Ask your Amperity support representative for more information about the event, and then request also that this reference be updated.
Event grouping |
Description |
|---|---|
AI Assistant |
The following events are associated with the AI Assistant:
|
API keys |
The following events are associated with API keys:
|
BI Connect |
The following events are associated with BI Connect:
|
Credentials |
The following events are associated with credentials:
|
Destinations |
The following events are associated with destinations:
|
Domain tables |
The following events are associated with domain tables:
|
Orchestrations |
The following events are associated with orchestrations and orchestration groups:
|
Policies |
The following events are associated with policies:
Important Occasionally members of your Amperity team will access your tenant. This is always done as a full administrator. In situations where they are helping to troubleshoot an issue, answer a question with more detail, and so on, they will often switch their view to match the policy settings associated with your tenant. For example, if the view is switched to “DataGrid Operator”, that action is logged using the following event type:
|
Privacy rights |
The following events are associated with privacy rights workflows:
|
Queries |
The following events are associated with the Queries page:
|
Resource groups |
The following events are associated with resource groups:
|
Sandboxes |
The following events are associated with sandboxes:
Note These events appear within the sandbox and are followed by the |
Single Sign-on |
The following events are associated with single sign-on (SSO):
|
User activity |
The following events are associated with the the Users section within the Users and Activity page:
|
Users |
The following events are associated with Amperity user accounts that are managed from the Users and Activity page:
|
Workflow alerts |
The following events are associated with workflow alerts:
|
Workflows |
The following events are associated with workflows:
|