# Overview

MURAL’s audit logs provide a detailed account of your company’s activity, including what actions occurred, who performed them, and how those actions affected other parts of the company. Use the audit logs endpoint to learn more about how your employees use MURAL. Currently, 120 events can be logged by the audit log.

This article breaks down the details of the audit logs, explaining each type of data represented.

**Current audit logs limitations**

  • Audit logs are not real time. Audit log events are made available within 24–48 hours. If you make a request and the time range overlaps with the last 24–48 hours, you may not see all events during this time frame.

  • We do not display all known information in the audit log. Our intention is to provide administrator-level data that informs, promotes exploration, and assists with troubleshooting.

  • To ensure a high quality experience for all users and to prevent abuse and security issues, the MURAL audit log API enforces a rate limit of 1,500 calls per day per customer, roughly translating to around 1 call per minute.

  • We limit the API response to a maximum range of 30 days. If you don’t define a specific time range using the `filter[date][since]` and `filter[date][until]` fields, the API returns events from the past 7 days.

# Audit log entries

Audit logs provide details on actions your company performed. Each log entry is a single action event. Actions are performed by entities and affect other entities.

Audit log entries display in reverse chronological order, with the newest entries shown first.

Each entry describes the action and the entity that performed it. Entries also include affected entities, timestamps, IP addresses, and user email addresses.

Here’s a sample audit log entry for a RENAME_MURAL action:

Each audit log entry contains the following pieces:

  • **action**: The log event, or the activity that happened. Action names are in uppercase, like CREATE_MURAL.

  • **group attribute**: Every action has at least one group attribute based on the entity that took action or was acted upon. Group attributes are clusters of nested JSON.

  • **attribute**: A single attribute contains a string, like an IP address.

  • **entity**: An entity is an object that either _performs_ or is _affected_ by an action. The entity defines each group attribute’s type. Entities are in uppercase, like WORKSPACE.

  • **string**: The data for an attribute. For example, the string for an email attribute is an email address.

# Audit logs details

In this section, we provide more detail for each piece of the audit logs.

  • [Actions](🔗)

  • [Group attributes](🔗)

  • [Single attributes](🔗)

  • [Entities](🔗)

## Actions

Each audit log entry is an action and its related data. The action is the topmost item in our JSON hierarchy.

Some example actions and their definitions:

  • **CREATE_MURAL**: A mural was created.

  • **SUSPEND_USER**: A member (user) account was suspended.

  • **LEAVE_WORKSPACE**: A member left a workspace. _¡Adios!_

### Examples

#### SIGN_IN

A SIGN_IN action is short. It contains an `actor` group attribute (with nested data) and some single attributes (`date`, `id`, `ip`).

In the example below, we see all the details when Mr. Coyote signed in on November 16.

The `actor` group attribute contains the actor’s:

  • `company` name

  • `email` address

  • unique `id`

  • given `name`

At the bottom of the `actor` group attribute is the entity `type` of USER.


Some action types contain many group attributes and are larger entries in the audit log. The INVITE_MEMBER action includes group attributes for the:

  • `actor` who did the inviting

  • `affected` invitee

  • `destination` mural, to which the invitee was invited

In this example, we see Mr. Coyote at ACME invited the member, Ms. Runner, to take part in an ACME mural.

The `actor` (who took the action) is Mr. Coyote. The `affected` party is a USER, “Road Runner.” The `destination`, where the `affected` was invited, is an entity `type` of MURAL.

## Group attributes

Group attributes are the clusters of metadata that define each action. Each group attribute is made up of some (single) attributes and an entity type. Group attributes can be: `actor`, `affected`, `origin`, and `destination`.

Depending on the action, not every type of group attribute is used.

Group attributeDescription
actorThe entity that performed the action.
affectedThe entity that was affected by the action.
destinationThe target location of the affected entity.
originThe source location of the affected entity.

### Example

We can see this `actor` group attribute contains nested single attributes. These attributes give us information about the actor: `email` address, `name`, unique `id`, and so forth.

## Single attributes

While a group attribute is a cluster of data, a single attribute is a variable name containing a string. This table shows the single attributes you can find in the audit logs.

Single attributeDescription
actionThe type of action performed. See the full list of available actions in the [API Reference](🔗).
companyThe company name that the entity belongs to.
emailThe email address of the entity.
dateThe date and time when the action occurred. We format dates like `1985-10-26 01:20:00`.
idA unique identifier. The format of an id varies depending on what it defines, such as an actor, an action, or a room. An actor’s USER id might be `jadams002`, whereas a destination id for a ROOM might be `1598387911389`.
ipThe source IP address of the requesting entity.
nameThe given name of the entity.

## Entities

Group attributes are defined by their entity type. The entity is an object that either _performed_ an action or was _affected_ by an action.

For example, the entity type for a destination might be MURAL, because the _location that was affected_ was … a mural.

Entities are in uppercase, like WORKSPACE.


## Hidden items

You may encounter hidden or masked information when reviewing audit logs. Masked information is indicated by a series of asterisks (****) in place of data.

This indicates that the information belongs to a user that is not part of your company. Certain information between companies is masked to retain corporate privacy.

Let's consider an example of a user (Jenny) from one company (OUR_COMPANY) deleting the mural in a workspace associated with another company (OTHER_COMPANY). The snippet below provides an example of what the audit log API response would look like for an API user at OUR_COMPANY, as the mural ID belonging to OTHER_COMPANY is masked.