About the Reporting API

Suggest Edits

Overview

The Reporting API provides programmatic methods to access Mural report data. These reports reveal granular information about your company’s activities.

Key benefits include:

  • Get consistent and reliable access to key reports on a self-serve basis.
  • Conduct regular reviews of configuration settings.
  • Manage member attributes and access to Mural.
  • Understand the engagement and usage of Mural to manage software operational costs.

Report types

The Reporting API has two types of reports: core reports and membership reports.

Core reports

These reports provide information about an organization's account levels, and the association of users at each level, using aggregate metrics.

Each core report is associated with a Mural account level: workspace, room, mural, user, template.

Here’s a list of core reports:

  • Workspace.
  • Room.
  • Mural.
  • Users.
  • Templates.

Membership reports

These reports provide information about users and their membership details for the account levels they are associated with. Membership is defined as the association of a user to their account level.

User types can include Members, Administrators, and Guests. Association types (between users and levels) include admin, owner, member, or guest.

Here’s a list of membership reports:

  • Workspace Memberships
  • Room Memberships
  • Mural Memberships

📘

Need a refresher on Mural's accounts and organizational structure? See this Help Center article: How are Mural accounts organized?

Types of collaborators

  • Members are collaborators that are part of your company domain. They can own and access any content that an admin or mural owner permits them to.

  • Guests are people outside of your company that are invited to collaborate on a project with you. Guests have limited use of Mural. They cannot invite others, create or manage rooms, create, duplicate, or export murals, publish templates, or push murals to a touchscreen device.

  • Admins are collaborators in your company domain who have the authority to administer access to Mural. A company can have company admins and workspace admins.

Reporting API limitations

  • Reporting API data is not real time. Reports 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.

  • Filter and sort options for GET endpoints are not currently available.

  • To ensure a high quality user experience and to prevent abuse and security issues, the Reporting API enforces a rate limit of 1,500 calls per day per customer (roughly 1 call per minute).

Reporting API filters

To narrow the results of each report, you can filter them to better suit your needs. You do this using a filter query parameter. By setting this parameter, you are giving the report something to compare each row of the report against. Every row that matches your parameter is then included in your final report, and every row that doesn’t match is left out.

This section walks you through creating filter query parameters, but you can also use the API reference page for each report to generate these query parameters for you.

Filter syntax

The filter query parameter relies on the following syntax:

filter[column][operator]='expression'

Here’s what each of those elements represents:

  • column: The column of data you want to run through your filter criteria. For example, dateCreated.
  • operator: An optional operator to help bridge the gap between your column’s data and your expression. For example, since, until, equalTo, or lessThan. Valid operators depend on the data type of the column.
  • expression: The criteria you want your data to meet to be included in your report. For example, a specific date. Valid expressions depend on the data type of the column.

Filter examples

Here are some common examples of filters you can use with reports. You’ll find more details about how to filter each report on its dedicated page, but these give a general overview.

Date filters

To generate a report of workspaces that have been deleted after a certain date, use the filter parameter:

filter[dateDeleted][since]='2022-03-01'

And to generate a report of workspaces that have been deleted prior to a certain date, use the filter parameter:

filter[dateDeleted][until]='2022-04-01'

You could combine these two filters for an even more customized report. Here’s what that combined filter parameter looks like:

filter[dateDeleted][since]='2022-03-01'&filter[dateDeleted][until]='2022-04-01'

📘

If no date filter is used, the report returns data from all time by default.

Boolean filters

In cases where your filter criteria is an either or value, you use a boolean value of true or false. To generate a report of murals that have been deleted, use the filter parameter:

filter[deleted]=true

And to generate a report of murals that have not been deleted, use the filter parameter:

filter[deleted]=false

Enumerated filters

Sometimes, you might be filtering using a column that has a set list of possible values. For example, the report column shareLinkMemberPermission can have three possible values: canEdit, viewOnly, or readOnly. Here, choose the value that suits your needs and use that in your parameter.

Here’s what that filter parameter looks like:

filter[shareLinkMemberPermission]='canEdit'

Numeric filters with operators

When dealing with columns that hold numerical data, include an operator that works as an indication of comparison. For example, if you want a report of murals with more than 100 members, 100 is your expression and greaterThan is your operator.

Here’s what that filter parameter looks like:

filter[memberCount][greaterThan]=100

The following operators are supported:

  • lessThan
  • lessThanOrEqualTo
  • greaterThan
  • greaterThanOrEqualTo
  • equals

Numeric filters without operators

You can filter columns of numeric data without using an operator, however there will be an implied operator of equals. For example, the two following expressions have the same filtering result:

filter[memberCount]=100

filter[memberCount][equals]=100

FAQ

Who can use the Reporting API?

Company admins on the Mural Enterprise plan.

How do admins access the Reporting API?

Company admins create API keys using the Mural company dashboard. With an API key, they make HTTP requests to the Reporting API and receive JSON response data.

I'm a company admin. How do I get started?

Eager to jump right in? Here's a quick summary to get up and running immediately.

  1. Log in to Mural.
  2. Go to the company dashboard.
  3. On the left side of the company dashboard, click API Keys.
  4. Click Create API Key.
  5. Select the Reports checkbox.
  1. Click the Create API key button.
  2. Copy the API key and share it with your team.

That's it! You're now ready to start making API calls.

Updated 6 months ago