Anypoint Usage API

Usage API

The Usage API enables you to access your usage data stored in the Mulesoft Usage Report Service. This API uses a Domain-Specific Language DSL called Anypoint Metric Query Language (AMQL) to construct flexible queries to access that data.

This queryable data available via this API is self-describing. As different data sets are added to the Mulesoft Usage Report service, descriptions of the available meters (aka data sets) and their columns will be current in the API.

Note that Usage data is generally available with a 3 day delay to allow consolidation.

Get the shape of data

In order to know the full scope of data our system has, you can use our Describe API that provides a guide on what shape of data is stored and available for queries.

Access your data

Once, you get the shape of data stored in Observability Platform, you need to construct a query following Search API specification.

Using our Search API with AMQL, a SQL like syntax you can easily:

• Define what data you want to query and the response data structure
• Define a set of aggregations for either selection or filtration capabilities
• Define a set of filtration conditions to narrow down your search scope

Auth

User must have access to "Usage Viewer" permissions in Anypoint in order to access this API.

Generate a bearer token for Anypoint Platform. For guidance, see How to generate your Authorization Bearer token for Anypoint Platform.

Constructing Query

Following are the main parts of a AMQL query detailed in the describe endpoint

Meter - Data source for meters, meter defines an aggregation on data which can be queried against.

Measurement - Value of a given meter, for example number of api calls.

Dimension - an attribute of a given meter - for example org identifier, environment identifier.

Enriched Dimensions - These are special dimensions which give human readable names for dimension identifiers - enriched dimensions can only be selected and can not be a part of the filter.

Grammar (similar to Salesforce SOQL):

SELECT Dimension, EnrichedDimension, Measurement
FROM Meter
[WHERE filterExpression]
[TimeSeries [P1M,P1D]]

Supported Clauses

SELECT: Select clause specifies the list of fields which are needed from the Meter data source. Fields can be dimension, enriched dimension or a measurement. The Describe endpoint lists the available fields to be selected for a given meter.

Following functions can be applied to the measurement fields when selecting

• DIV(x, y) - divide x by y
• ADD(x, y) - add x with y
• MUL(x,y) - multiply x with y
• SUB(x,y) - subtract x from y

FROM: From clause specifies the meter(data source) to be used for the query. Meters are described in the Describe endpoint.

WHERE: Where clause allows to add filter conditions to the query. A filter can only be applied to dimensions. Following operators are allowed in the filter condition

TIMESERIES: Time series clause lets you group data as in the following supported times series

• P1M - monthly
• P1D - daily

Example

Obtain all registered meters on the Usage API

Make a call to Describe API

curl -X GET https://<endpoint>/metering/usage/api/v1/meters:describe
     -H "Content-Type: application/json"
     -H "Authorization: Bearer ${token}"

Get the columns available for Runtime Flows

From the Describe response we get the name XXXX for the Runtime Flow meter. Then make a call to get the specific columns available for querying

curl -X GET https://<endpoint>/api/v1/meters/runtime_flow_count:describe
     -H "Content-Type: application/json"
     -H "Authorization: Bearer ${token}"

Using the meter name and columns we can use a select query to get the data we want.

Get a monthly summary of Runtime Flows

curl -X POST https://<endpoint>/api/v1/meters:search
     -H "Content-Type: application/json"
     -H "Authorization : Bearer ${token}"
     -d '{
           "query": "{"query":"SELECT mule_flow_count FROM runtime_flow_count WHERE timestamp between 1704067200000 and 1706745599000 TIMESERIES P1M"}"}'

Get a monthly summary of Runtime Network Usage

curl -X POST https://<endpoint>/api/v1/meters:search
     -H "Content-Type: application/json"
     -H "Authorization : Bearer ${token}"
     -d '{
            {"query": "SELECT network_bytes_count  FROM runtime_network_bytes_count WHERE timestamp between 1704067200000 and 1706745599000 TIMESERIES P1M"}"}'

Daily report for a single Business Group

curl -X POST https://<endpoint>/api/v1/meters:search
     -H "Content-Type: application/json"
     -H "Authorization : Bearer ${token}"
     -d '{
           {"query": "SELECT  org_name, env_name, app_name, deployment_model, network_bytes_count  FROM runtime_network_bytes_count WHERE timestamp between 1748736000000 and 1748822399000 and org_id = '02cfcba4-d7ff-4ee0-9e7b-5410660628ac'  TIMESERIES P1D"}"}'

Specific report by month for an app name for every day (list of 31 responses)

curl -X POST https://<endpoint>/api/v1/meters:search
     -H "Content-Type: application/json"
     -H "Authorization : Bearer ${token}"
     -d '{{"query": "SELECT  org_name, env_name, app_name, deployment_model, network_bytes_count  FROM runtime_network_bytes_count WHERE timestamp between 1748736000000 and 1748822399000 and asset_id = '21fa4255-ed8d-4d55-bdb7-6bfe3103c336'  TIMESERIES P1D"}"}'

Special Dimensions

Timestamp - time associated with data, this is in milliseconds from epoch format in UTC timezone.

Query Restrictions

There are some additional restrictions while querying data

• Timestamp filer is mandatory
• Timerseries filter is mandatory
• Queries with daily granularity (time-series P1D) can not have timestamp filter greater than 30 days
• Maximum time range for any other query is 60 days.
• End time for query can not be in the last 3 days.
• Query does not support filters on enriched dimensions.
• Select * is not supported in Usage API.
• Query should contain at least one measurement.
• Column aliases are not supported in Usage API query.
• Usage API only supports following granularity in time series clause
  • P1M - monthly
  • P1D - daily
• Usage API supports following scalar functions on measurement fields
  • DIV(x, y) - divide x by y
  • ADD(x, y) - add x with y
  • MUL(x,y) - multiply x with y
  • SUB(x,y) - subtract x from y