Audit framework API

Restriction: This functionality is currently in Beta. During this early access period, clients in the Beta program can learn about, try out, and test this feature, and they can provide feedback about it. This stage allows Medallia to refine the feature's design before its general availability. Be aware that functionality may change before then.

Restriction: This feature or information is available to Medallia employees only and it is not to be shared outside the company.

Use this API to query audit log events for a Medallia Experience Cloud instance via HTTP request to evaluate, assess, and mitigate security risks, and also to find the root cause of configuration issues.

Audit logs are essential for conducting investigations following an incident. For accountability and transparency, Medallia provides comprehensive audit logs that document user activities and system events.

Query audit events asynchronously

The audit query service allows you to query for data in an asynchronous manner. Create a request to query the audit framework with filtering capabilities. Then use the returned job id to check the job's status, cancel or resume it, and retrieve its results once completed.

Audit events

Medallia's audit framework is an engine that collects a variety of security-related events and makes them queryable via this public API.

See the list of events ingested to the audit log from Medallia Experience Cloud below:

USER_LOGIN — {user} attempted to login with {method}.
USER_LOGOUT — {type} user {user} logout.
USER_SWITCH_INTO — user switched into {user}.
USER_SWITCH_BACK — user switched back from {user}.

Permissions module events

GRANT_ROLE_TO_USER — {user} was granted {role}.
REVOKE_ROLE_TO_USER — {user} was revoked {role}.
GRANT_PERMISSION_TO_ROLE — {role} was granted {permission}.
REVOKE_PERMISSION_TO_ROLE — {role} was revoked {permission}.

System connections module events

SYSTEM_CONNECTIONS_CREATE — System connection {id} was created.
SYSTEM_CONNECTIONS_READ — System connection {id} was read.
SYSTEM_CONNECTIONS_DELETE — System connection {id} was deleted.
SYSTEM_CONNECTIONS_UPDATE — System connection {id} was updated.
SYSTEM_CONNECTIONS_LIST — System connection list operation was executed.

PGP-key management module events

TENANT_KEY_CHANGE — The tenant key for company {company} was changed to type {keyType}.

Changelog events

CHANGELOG — A {changeType} was performed on an entity of {type} in the entity {field} by an {initiator} during a {transaction}, {group} and {session}.
- type — The type of entity affected by the change {account, translation}. This value is stored in the extra_fields value of this event.
- field — The field that was affected by the change (or database column) (field:"account.email", field:"translation.transtext"). This value is stored in the extra_fields value of this event.
- changeType — The type of entity change: {deletion, creation, update}. This value is stored in the extra_fields value of this event.
- Initiator — account, component.
  - component — Changes initiated (either directly or indirectly) by the given system component (component:"Express web").
- group — Changes that were done as part of the change group with the given id (group:"6439"). This value is stored in the extra_fields value of this event.
- session — Changes performed in the change session with the given id (session:"current"). This value is stored in the extra_fields value of this event.

Query API events

QUERY_API — A request of {type} was performed against the reporting query api with the following {parameters} and {request_context}.
- type — GET, POST.
- parameters — All the request parameters are stored in the extra_fields of this event.
- request_context — All the request context as headers are stored in the extra_fields of this event.

Restriction: The audit framework keeps events for 120 days unless otherwise noted. Events older than 120 days no longer appear on the audit framework.

Restrictions and limits

The Audit query API can handle up to 10 requests per second and 10,000 requests per day.

Important: The timeout for a request is 600 seconds. The API Gateway discards any request that takes longer than that.

For security reasons, users of this API are only allowed to query events for the company in which they have access and access one at a time. You cannot query more than one company in the same request even if you have access to different instances.

Authentication and authorization

Authentication identifies who is making an API request, and authorization identifies what data the requester may access. OAuth is an industry standard for authorizing limited access to services and data. Applications must obtain a secure token that identifies the application that makes the request. The token is passed to the resource server (API server) with each API request. For more information, see Authenticate APIs with OAuth.

For information about getting a refresh token for the authorization code grant, see section Request OAuth authorization (Authorization code grant).

Restriction: This API only supports authorization code grant, and does not support the client credentials grant.

To use the Audit framework API:

The application must have an account, see AppID Accounts for details.
The account's role must have permission to access the API. In this case:
1. Primary role — Medallia Audit Log permission or InternalAdmin.
2. Alternative role requirements — If the user does not have one of the above as their primary role, their active role must be granted the ALLOW_AUDIT_LOG_QUERY or DO_ANYTHING capability.
3. Admin Suite configuration —In Admin Suite, the ALLOW_AUDIT_LOG_QUERY capability is equivalent to the Audit Log > Allow Audit Log Query API invocations permission.
  
  For more information about the permissions, see Administrative permissions and Data access permissions.
  
  Note: Requests that do not meet these requirements return a 401 Unauthorized error.
API access is authenticated with OAuth. To use OAuth, the application must first obtain an OAuth access token, by requesting one for the application's client ID and secret. For detailed information, see Authenticating APIs with OAuth.

Each Medallia instance serves as an OAuth authorization server and issues tokens to access the Audit Framework through the API gateway.

There is a default OAuth client created in each Medallia Experience Cloud named medallia_audit_query to use for this purpose. This client is configured with the authorization code grant and through it, Experience Cloud issues an OpenID token to receive both access_token and id_token when requesting the token.

Request/response formats

Requests sent to Medallia Audit Framework API are HTTP GET and HTTP DELETE protocols. The information in the request includes:

A required Content-Type header field describing the content. The acceptable type is: application/json for JSON.

An optional Accept field tells the Audit Framework API how to format the response. The acceptable type is: application/json for JSON.


Parameter	Description	Required	Values
Bearer	Access token	Required	See Authentication and authorization.
Content-Type	Format of request data	Required	application/json.
Accept	Format of response data	Optional	application/json.

No other header fields are expected.
The request URL:
- Always use the base instance for the company's Medallia installation.

Create a request to get audit events

Use this endpoint to query the audit log and find events for a given tenant and a time range.

Requests are HTTP GET protocol. The API accesses resources from a URL that follows this format to create a request to fetch audit events.

https://<api-host>/<service>/<api-version>/<endpoint>

Where:

api-host is the server for your company's Experience Cloud instance.
service is audit-query-service.
api-version is v2.
endpoint is export.

Make query requests with the query parameters shown in the table below. The API supports additional parameters to filter the matching audit events. Each filter specified restricts the amount of data queried and returned (logical AND, not OR).


Parameter	Description	Type	Required	Notes
tenantName	Unique identifier of the tenant to whom the event is associated.	String	Optional	If omitted, the value is automatically retrieved from the access token.
startTime	Absolute start time of the filter period, encoded as a JSON string of an ISO-8601 timestamp.	Datetime	Required	Format is: `yyyy-MM-dd'T'HH:mm:ssZZ` (e.g. 2025-07-23T00:00:00z).
endTime	Absolute end time of the filter period, encoded as a JSON string of an ISO-8601 timestamp.	Datetime	Required	Format is: `yyyy-MM-dd'T'HH:mm:ssZZ` (e.g. 2025-07-23T00:00:00z).
f.category	Filter using the event category name. Use it to filter security events and configuration events.	String	Optional	For example: 'security'.
f.application	Filter using application or product name.	String	Optional	For example: 'express'.
f.username	Filter using the username value in the event.	String	Optional	—
f.attrName	Filter using other event metadata attributes.	String	Optional	Format is: `?f.attrName=x&f.attrVal=123`.
f.attrVal	Filter using other event metadata attribute values.	String	Optional	Format is: `?f.attrName=x&f.attrVal=123`.

Event attributes

Query parameters f.attrName and f.attrVal provide a way to filter events having some extra attributes set in them. To filter by multiple attribute names and values, send comma-separated strings for each parameter. Each attribute name and value should correlate to each other.

For example, the call below filters by both color and tenant name attributes:

GET https://instance.apis.medallia.com/audit-query-service/v2/export?tenantName=tenant-364&startTime=2023-06-23T00:00:00z&endTime=2023-07-01T00:00:00z&f.attrName=color,tenant&f.attrVal=ivory,annabel
Content-Type: application/json

Additionally, use query the parameters listed below to improve query precision:

f.name — Filter by event name (for example: ?f.name=user_login).
f.instanceUrl — Filter by the originating instance URL (for example: ?f.instanceUrl=https://instance/company).

Note: When you do not provide this parameter, the value is sourced from the X-Medallia-Express-URL header injected by the API Gateway.
f.nodeId — Filter by the specific node ID where the event originated (for example: ?f.nodeId=secengdentest-fe1).

Response

When the job is successfully created, the response returns a unique UUID value. Use it to get the results of the job at a later point when the job has transitioned to the COMPLETED state. The response is a JSON object that includes:


Element	Description	Type	Notes
status	Status of the audit query job.	String	Values: PENDING PROCESSING COMPLETED FAILED CANCELED
jobId	UUID of the audit job.	String	—
statusTime	Audit query job timestamp encoded as a JSON string of an ISO-8601 timestamp.	Datetime	Format is: `yyyy-MM-dd'T'HH:mm:ssZZ` (e.g. 2025-07-23T00:00:00z).

Sample request

GET https://instance.apis.medallia.com/audit-query-service/v2/export?f.username=jpatterson&tenantName=123302&startTime=2024-09-16T05:00:00z&endTime=2024-09-16T15:00:00z
Content-Type: application/json

Sample response

{
    "status": "PROCESSING",
    "jobId": "384a79aa-f3e0-4bae-b2b5-8c512b4605bd",
    "statusTime": "2024-10-12T03:07:15.329132Z"
}

Check the status of a job

Use this endpoint to get the current status of a previously scheduled job. Use the previously returned job id value as a path parameter.

Requests are HTTP GET protocol. The API accesses resources from a URL that follows this format to retrieve the status of a job.

https://<api-host>/<service>/<api-version>/<endpoint>/status/<jobId>

Where:

api-host is the server for your company's Experience Cloud instance.
service is audit-query-service.
api-version is v2.
endpoint is export.
jobId identifies the audit query job whose status you are querying.

Response

A valid success response will return the original query parameters and the status of the job.

If the job has completed successfully, the filePath parameter will indicate the path where the results are available.

If the job has erred for any reason, the failureReason parameter will provide additional information related to the exception.


Element	Description	Type	Notes
id	Server generated event identifier.	String	—
jobId	UUID of the audit job.	String	—
params	Original query parameters.	Parameter data object	Example: `"{\"tenant\":\"secengdentest\",\"tenantName\":\"123802\",\"startTime\":{\"dateTime\":{\"date\":{\"year\":2025,\"month\":7,\"day\":24},\"time\":{\"hour\":12,\"minute\":0,\"second\":24,\"nano\":0}},\"offset\":{\"totalSeconds\":0},\"zone\":\"Z\"},\"endTime\":{\"dateTime\":{\"date\":{\"year\":2025,\"month\":7,\"day\":25},\"time\":{\"hour\":23,\"minute\":43,\"second\":26,\"nano\":0}},\"offset\":{\"totalSeconds\":0},\"zone\":\"Z\"},\"limit\":10000}"`
status	Status of the action intended by the user.	String	Shows whether the action intended by the user succeeded. It is useful to monitor failed authentication attempts as suspicious behavior.
filePath	Path where the results are available.	String	—
createdAt	Audit query job timestamp encoded as a JSON string of an ISO-8601 timestamp.	Datetime	Format is: `yyyy-MM-dd'T'HH:mm:ssZZ` (e.g. 2025-07-23T00:00:00z).
completedAt	Completion date timestamp encoded as a JSON string of an ISO-8601 timestamp.	Datetime	Format is: `yyyy-MM-dd'T'HH:mm:ssZZ` (e.g. 2025-07-23T00:00:00z).
failureReason	Additional information related to the exception.	String	—
timestamp	Timestamp encoded as a JSON string of an ISO-8601 timestamp.	Datetime	This element is only returned when the job could not be processed. Format is: `yyyy-MM-dd'T'HH:mm:ssZZ` (e.g. 2025-07-23T00:00:00z).
error	HTTP error code description.	String	This element is only returned when the job could not be processed.
message	Error description.	String	This element is only returned when the job could not be processed.
path	Status check path and query parameters.	String	This element is only returned when the job could not be processed.

Sample request

GET https://instance.apis.medallia.com/audit-query-service/v2/export/status/384a79aa-f3e0-4bae-b2b5-8c512b4605bd
Content-Type: application/json

Sample success response

{
    "id": 1,
    "jobId": "384a79aa-f3e0-4bae-b2b5-8c512b4605bd",
    "params": "{\"tenantName\":\"cubedentest-be\",\"startTime\":{\"dateTime\":{\"date\":{\"year\":2024,\"month\":9,\"day\":21},\"time\":{\"hour\":0,\"minute\":0,\"second\":0,\"nano\":0}},\"offset\":{\"totalSeconds\":0},\"zone\":{\"totalSeconds\":0}},\"endTime\":{\"dateTime\":{\"date\":{\"year\":2024,\"month\":9,\"day\":30},\"time\":{\"hour\":0,\"minute\":0,\"second\":0,\"nano\":0}},\"offset\":{\"totalSeconds\":0},\"zone\":{\"totalSeconds\":0}},\"limit\":10000}",
    "status": "COMPLETED",
    "filePath": "/audit_events_log_data/tenants/cubedentest-be/2024/10/12/events-data-384a79aa-f3e0-4bae-b2b5-8c512b4605bd.json",
    "createdAt": "2024-10-12T03:07:15.329132Z",
    "completedAt": "2024-10-12T03:08:04.501308Z",
    "failureReason": null
}

Sample error response

{
    "timestamp": "2024-10-14T17:18:45.909+00:00",
    "error": "Not Found",
    "message": "Job with id: 384a79aa-f3e0-4bae-b2b5-8c512b4605bd not found",
    "path": "/v2/export/status/384a79aa-f3e0-4bae-b2b5-8c512b4605bd"
}

Get the job results

Use this endpoint to retrieve the results of a COMPLETED or FAILED job.

Requests are HTTP GET protocol. The API accesses resources from a URL that follows this format to retrieve the results of a job.

https://<api-host>/<service>/<api-version>/<endpoint>/result/<jobId>

Where:

api-host is the server for your company's Experience Cloud instance.
service is audit-query-service.
api-version is v2.
endpoint is export.
jobId identifies the audit query job whose status you are querying.

Response

When the job has successfully completed, all matching audit events are returned in the JSON Lines format with UTF-8 encoding, which is nothing but a JSON payload for each matching event delimited by a newline character. Each row represents one matching event in JSON format.


Element	Description	Type	Notes
timestamp	Event timestamp encoded as a JSON string of an ISO-8601 timestamp.	Datetime	Format is: `yyyy-MM-dd'T'HH:mm:ssZZ` (e.g. 2025-07-23T00:00:00z).
dateTime	Audit event timestamp encoded as a JSON string of an ISO-8601 timestamp.	Datetime	Format is: `yyyy-MM-dd'T'HH:mm:ssZZ` (e.g. 2025-07-23T00:00:00z).
eventId	UUID of the audit event identifier.	String	—
actorId	Identifier of the user that triggered the audit event.	String	—
name	Name of the user that triggered the audit event.	String	The name of the event is the identifier of the action itself.
category	Audit event category name.	String	For example: 'security'.
username	Username of the user that triggered the audit event.	String	—
application	Application or product name.	String	For example: 'express'.
tenant	Tenant name.	String	The tenant is usually the name of the company.
tenantName	Tenant identifier.	String	The identifier is the same across instances and products. For example: "100440" for a company is the same when deployed in QA or in a production instance or across applications like Express, Digital, etc.
instanceId	Instance identifier.	String	The identifier is unique per instance. For example: "101432" is the instance containing "100440" This `instanceId` differs between QA and production instances and across applications.
instanceUrl	Instance URL. Use this parameter to search for events from specific Medallia Experience Cloud instances of your company.	String	—
attributes	Fields with additional properties related to the audit event.	Attribute data object	—

Tip: JSON Lines format provides many advantages over plain JSON. For information about this format, see https://jsonlines.org/.

Sample request

GET https://instance.apis.medallia.com/audit-query-service/v2/export/result/384a79aa-f3e0-4bae-b2b5-8c512b4605bd
Content-Type: application/json

Sample response

{"timestamp":"2024-09-26T12:34:15.884Z","dateTime":"2024-09-26T12:34:15.884Z","eventId":"6c66d9fb-ca17-4cac-bd96-f6f025dea9d5","actorId":"","name":"cmd-center-command","category":"security","username":"_oauthClient_sre_client","application":"com.medallia.express","tenant":"","tenantName":"","instanceId":"122047","instanceUrl":"http://instance.medallia.com","attributes":{"request":"ee4be5e3-ed0e-4623-97c7-db189deafce7","cmd":"groovy"}}
{"timestamp":"2024-09-26T13:39:44.284Z","dateTime":"2024-09-26T13:39:44.284Z","eventId":"94c129ff-8c28-4914-82c6-0ac68feab73b","actorId":"","name":"cmd-center-command","category":"security","username":"_oauthClient_sre_client","application":"com.medallia.express","tenant":"","tenantName":"","instanceId":"122047","instanceUrl":"http://instance.medallia.com","attributes":{"request":"9224515a-97c9-4955-93b1-29c7c51da4dc","cmd":"groovy"}}
{"timestamp":"2024-09-27T17:19:30.472Z","dateTime":"2024-09-27T17:19:30.472Z","eventId":"bdea8dae-287d-4255-b59a-3cb6f177f391","actorId":"","name":"cmd-center-command","category":"security","username":"_oauthClient_sre_client","application":"com.medallia.express","tenant":"","tenantName":"","instanceId":"122047","instanceUrl":"http://instance.medallia.com","attributes":{"request":"5a5b3cf6-b8dc-4947-a462-e9304831468d","cmd":"groovy"}}

Cancel an existing job

Existing export jobs can be canceled if they are currently in PROCESSING or PENDING state and not progressing due to any issues. Use this endpoint to cancel jobs.

Requests are HTTP GET protocol. The API accesses resources from a URL that follows this format to cancel an existing job.

https://<api-host>/<service>/<api-version>/<endpoint>/cancel/<jobId>

Where:

api-host is the server for your company's Experience Cloud instance.
service is audit-query-service.
api-version is v2.
endpoint is export.
jobId identifies the audit query job whose status you are querying.

Response


Element	Description	Type	Notes
status	Status of the audit query job.	String	Values: PENDING PROCESSING COMPLETED FAILED CANCELED
jobId	UUID of the audit job.	String	—
statusTime	Audit query job timestamp encoded as a JSON string of an ISO-8601 timestamp.	Datetime	Format is: `yyyy-MM-dd'T'HH:mm:ssZZ` (e.g. 2025-07-23T00:00:00z).
timestamp	Timestamp encoded as a JSON string of an ISO-8601 timestamp.	Datetime	This element is only returned when the job could not be canceled. Format is: `yyyy-MM-dd'T'HH:mm:ssZZ` (e.g. 2025-07-23T00:00:00z).
status	HTTP error code.	String	This element is only returned when the job could not be canceled.
error	HTTP error code description.	String	This element is only returned when the job could not be canceled.
message	Error description.	String	This element is only returned when the job could not be canceled.
path	Status check path and query parameters.	String	This element is only returned when the job could not be canceled.

Sample request

GET https://instance.apis.medallia.com/audit-query-service/v2/export/cancel/52d46e4b-0b57-45d0-9ff1-eb59fbadf0d3
Content-Type: application/json

Sample success response

{
    "status": "CANCELED",
    "jobId": "52d46e4b-0b57-45d0-9ff1-eb59fbadf0d3",
    "statusTime": "2024-10-14T17:51:25.378508Z"
}

Sample error response

{
    "timestamp": "2024-10-09T15:44:40.359+00:00",
    "status": 400,
    "error": "Bad Request",
    "message": "Job with given ID is not pending",
    "path": "/v2/export/cancel/11d39530-4ff1-4ba6-848d-c8378956fb4a"
}

Resume an existing job

Existing export jobs which are not already in PENDING or PROCESSING state can be resumed. Use this endpoint to resume jobs.

Requests are HTTP GET protocol. The API accesses resources from a URL that follows this format to resume an existing job.

https://<api-host>/<service>/<api-version>/<endpoint>/resume/<jobId>

Where:

api-host is the server for your company's Experience Cloud instance.
service is audit-query-service.
api-version is v2.
endpoint is export.
jobId identifies the audit query job whose status you are querying.

Response

This will restart and schedule the job to be run with the same query parameters as the original export job.


Element	Description	Type	Notes
status	Status of the audit query job.	String	Values: PENDING PROCESSING COMPLETED FAILED CANCELED
jobId	UUID of the audit job.	String	—
statusTime	Audit query job timestamp encoded as a JSON string of an ISO-8601 timestamp.	Datetime	Format is: `yyyy-MM-dd'T'HH:mm:ssZZ` (e.g. 2025-07-23T00:00:00z).
timestamp	Timestamp encoded as a JSON string of an ISO-8601 timestamp.	Datetime	This element is only returned when the job could not be canceled. Format is: `yyyy-MM-dd'T'HH:mm:ssZZ` (e.g. 2025-07-23T00:00:00z).
status	HTTP error code.	String	This element is only returned when the job could not be resumed.
error	HTTP error code description.	String	This element is only returned when the job could not be resumed.
message	Error description.	String	This element is only returned when the job could not be resumed.
path	Status check path and query parameters.	String	This element is only returned when the job could not be resumed.

Sample request

GET https://instance.apis.medallia.com/audit-query-service/v2/export/resume/384a79aa-f3e0-4bae-b2b5-8c512b4605bd
Content-Type: application/json

Sample response

{
    "status": "PROCESSING",
    "jobId": "384a79aa-f3e0-4bae-b2b5-8c512b4605bd",
    "statusTime": "2024-10-14T17:51:25.378508Z"
}

Sample error response — Job is not pending, failed, canceled

{
   "timestamp": "2025-01-13T17:00:09.950+00:00",
   "status": 400,
   "error": "Bad Request",
   "message": "Job 384a79aa-f3e0-4bae-b2b5-8c512b4605bd not pending",
   "path": "/v2/export/resume/384a79aa-f3e0-4bae-b2b5-8c512b4605bd"
}

Delete an existing job

Existing export jobs can be deleted if they are currently in PROCESSING or PENDING state and not progressing due to any issues. Use this endpoint to delete jobs.

Requests are HTTP DELETE protocol. The API accesses resources from a URL that follows this format to delete an existing job.

https://<api-host>/<service>/<api-version>/<endpoint>/<jobId>

Where:

api-host is the server for your company's Experience Cloud instance.
service is audit-query-service.
api-version is v2.
endpoint is export.
jobId identifies the audit query job whose status you are querying.

Response

Existing export jobs which are not already in PENDING or PROCESSING state can be deleted.


Element	Description	Type	Notes
status	Status of the audit query job.	String	Values: PENDING PROCESSING COMPLETED FAILED CANCELED
jobId	UUID of the audit job.	String	—
statusTime	Audit query job timestamp encoded as a JSON string of an ISO-8601 timestamp.	Datetime	Format is: `yyyy-MM-dd'T'HH:mm:ssZZ` (e.g. 2025-07-23T00:00:00z).
timestamp	Timestamp encoded as a JSON string of an ISO-8601 timestamp.	Datetime	This element is only returned when the job could not be canceled. Format is: `yyyy-MM-dd'T'HH:mm:ssZZ` (e.g. 2025-07-23T00:00:00z).
status	HTTP error code.	String	This element is only returned when the job could not be deleted.
error	HTTP error code description.	String	This element is only returned when the job could not be deleted.
message	Error description.	String	This element is only returned when the job could not be deleted.
path	Status check path and query parameters.	String	This element is only returned when the job could not be deleted.

Sample request

DELETE https://instance.apis.medallia.com/audit-query-service/v2/export/384a79aa-f3e0-4bae-b2b5-8c512b4605bd
Content-Type: application/json

Sample response

{
    "status": "PROCESSING",
    "jobId": "384a79aa-f3e0-4bae-b2b5-8c512b4605bd",
    "statusTime": "2024-10-14T17:51:25.378508Z"
}

Sample error response — Invalid job id

{
   "timestamp": "2025-01-13T16:40:31.028+00:00",
   "status": 404,
   "error": "Not Found",
   "message": "Job with id: 384a79aa-f3e0-4bae-b2b5-8c512b4605bd not found",
   "path": "/v2/export/384a79aa-f3e0-4bae-b2b5-8c512b4605bd"
}