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

GET /audit-events

Prerequisites

Each request to an endpoint in the Amperity API must be authenticated.

  1. Add an API key.

  2. Generate an access token.

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:

event_id

The Amperity internal identifier for the event.

event_type

The type of event.

happened_at

The date and time at which the action occurred. Dates and times are in ISO 8601 format and in UTC.

principal_email

The email address for the user who initiated the action.

principal_id

The authentication identifier for the user who initiated the action. This user may be an API key or a non-human user.

principal_name

The friendly name of the user associated with the activity, if available, otherwise the email address or API key.

object_id

The identifier for the object against which the action occurred.

object_name

Optional. A composed string that describes the object(s) for which the action occurred.

origin_ip

The IP address that is associated with the user who initiated the action.

tenant_family

The name of the tenant family that is associated with the action. When tenant is a sandbox, tenant_family is the tenant ID of the production tenant.

tenant

The tenant ID of the tenant associated with the action. This ID may be for a sandbox.

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:

assistant/send-user-message

A user sent a question to the AI Assistant. The audit event may include the response from the AI assistant.

query.exec/sampled

A set of sample data was provided to the AI Assistant.

Note

More detail about AI Assistant data sharing policies, how the model stores data, and what types of data is sent (or not sent), is available from the AI Assistant Privacy FAQ .

API keys

The following events are associated with API keys:

api-key/created

An API key was created.

api-key/deleted

An API key was deleted.

api-key/issue

An API token issuer was created.

Note

This event is always associated with the following events:

policy/attached

and

policy/attached-to

api-key/updated

An API key was updated.

BI Connect

The following events are associated with BI Connect:

warehouse/user-added

A user was added to BI Connect.

warehouse/user-removed

A user was removed from BI Connect.

warehouse/user-renewed

A user was allowed to continue accessing BI Connect.

Credentials

The following events are associated with credentials:

credential/created

A credential was created.

credential/deleted

A credential was deleted.

credential/updated

A credential was updated.

Destinations

The following events are associated with destinations:

destination/cloned

A user created a destination by copying an existing destination.

destination/created

A user created a destination.

destination/deleted

A user deleted a destination.

destination/updated

A user updated a destination.

Domain tables

The following events are associated with domain tables:

workflow/domain-data-records-deletion-started

A user deleted records from a domain table.

Orchestrations

The following events are associated with orchestrations and orchestration groups:

orchestration/run

A user initiated a manual run for an orchestration.

orchestration.group/run

A user initiated a manual run for an orchestration group.

Policies

The following events are associated with policies:

policy/attached and policy/attached-to

A policy was was attached to an object that was created within Amperity.

For example, when a new API token issuer is created, the policy/attached and policy/attached-to events are logged and are associated with the name of the API issuer token.

policy/created

A policy was created.

policy/deleted

A policy was created.

policy/detached and policy/detached-from

A policy was was detached from an object that exists within Amperity.

policy/updated

A policy was updated.

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:

amperity.auth.token/user-switched-policies

Privacy rights

The following events are associated with privacy rights workflows:

workflow/domain-ccpa-deletion-started

The CCPA delete workflow has started.

Queries

The following events are associated with the Queries page:

query/activated

A query was activated.

query/created

A query was created.

query/deleted

A query was deleted.

query/moved

A query was moved from one folder into another.

query.draft/discarded

A query in a draft state was discarded.

query.folder/created

A folder on the Queries page was created.

query.folder/deleted

A folder on the Queries page was deleted.

Resource groups

The following events are associated with resource groups:

resource-group/assigned

A user was assigned to a resource group.

resource-group/created

A resource group was created.

resource-group/deleted

A resource group was deleted.

resource-group/updated

A resource group was updated.

Sandboxes

The following events are associated with sandboxes:

tenant/created

A sandbox was created.

tenant/deleted

A sandbox was deleted.

tenant/updated

A sandbox was updated.

Note

These events appear within the sandbox and are followed by the policy/attached-to and policy/attached events to allow the user who created the sandbox to access the sandbox as a DataGrid Administrator.

Single Sign-on

The following events are associated with single sign-on (SSO):

group-mapping/created

An SSO group mapping was created.

group-mapping/deleted

An SSO group mapping was deleted.

group-mapping/updated

An SSO group mapping was updated.

User activity

The following events are associated with the the Users section within the Users and Activity page:

audit.user-activity/download

A user downloaded user activity into a CSV file to view offline.

Users

The following events are associated with Amperity user accounts that are managed from the Users and Activity page:

user/created

A user was created.

user/deleted

A user was deleted.

user/sent-password-reset-email

A user was sent an email to they can reset their password.

Workflow alerts

The following events are associated with workflow alerts:

audience/created

An audience for a workflow alert was created.

Note

This event will show only the first time an email addresss or Slack channel is configured to receive workflow alerts for courier groups, scheduled orchestration groups, or campaigns. All subsequent events related to workflow alerts will show the audience/updated event.

audience/updated

The membership of an audience for a workflow alert was updated. This includes adding or removing email addresses and/or Slack channels to or from a workflow alert.

Workflows

The following events are associated with workflows:

workflow/cancel

A workflow resolution was stopped by a user.

workflow/retry

A workflow resolution was opened, after which a specific resolution option was selected, and then the workflow was retried.

workflow/skip

A user opened a workflow resolution, and then skipped the task that caused the workflow failure.