Reviewing Mule API Analytics Event API | MuleSoft Documentation
# Reviewing Mule API Analytics Event API
API Manager gathers analytics data for each Mule API that you manage. You can generate this data in reports and charts, using the Analytics Event API. You can create reports for a specific environment or for multiple APIs, and you can create different reports for the same API.
## Requirements and Restrictions
The Analytics Events API provides a one-month retention policy and a data availability delay of up to 10 minutes. It also enforces a usage limit of 10 requests per minute, with a maximum of 20,000 events per request. Request rates higher than 10 requests per minute are throttled.
The API is designed to create ad-hoc reports. It is not intended as a data export tool.
Before you start using the API to create reports, consider the following requirements and restrictions:
  * Do not allow calls to overlap time intervals.
  * Do not repeat the same request for every API that you have.
  * Although the Analytics Events API enforces a limit of 10 requests per minute, the best practice is 1 request per minute.
  * Do not use the Analytics Events API for data synchronization.
If you need to synchronize data for events with an external system, see Mule API Analytics Event Forwarding.


## Create a Report
You can create a report to find API events, such as policy violations due to rate limiting or IP blacklisting. If the analytics services or Anypoint Platform are temporarily unavailable, Anypoint Platform may submit multiple data points to avoid any telemetry data loss. This might cause the report that you generate to contain duplicate entries.
To create a report:
  1. Navigate to **API Manager** > **Mule Analytics** > **Manage Reports** and click **New**.
  2. In **Create Report** , select a data source, range, and format.
  3. In **Fields** , select **Violated Policy Name**.
  4. Save the report.
A URL for viewing the report is displayed.
  5. Click the URL to view the generated report.


## Run a Report in the Browser
The Analytics Event API displays a starting time from which requested data is available. If no data is available, a warning message appears.
To run a report in a browser, navigate to the **Manage Reports** page and click **Run** for your desired report:
After the report runs, a CSV or JSON file is generated, containing the analytics data you requested.
### View Report Information Using curl
You get the value of `$TOKEN` by running the curl command in this procedure. The command gets the `access_token` JSON property of this response.
The authorization header has the form `Authorization: Bearer {$TOKEN.access_token}`.
The use of the `jq` command-line JSON processor is one possible solution for obtaining the access token value. Download and install this application or one with the same functionality for this procedure.
To view report information programatically:
  1. Open a new terminal window and execute the following command:
```
TOKEN=$(curl -s https://anypoint.mulesoft.com/accounts/login -d "username=<YOUR-USERNAME>&password=<YOUR-PASSWORD>" | jq -r .access_token)
```

This command sends a request to the authentication servers of the Anypoint Platform and, if the request is successful, returns an access token that’s stored in the `$TOKEN` variable. The value of this variable is displayed below:
```
{
 "access_token": "54545454-5454-5454-5454-545454545454",
 "token_type": "Bearer",
 "redirectUrl": "/accounts/#/cs/profile/home"
 }
```

  2. Append the access token to the `Authorization` header in the request of the Analytics Reporting API endpoint for your report:
    1. Copy the endpoint from the **Manage Reports** page in the Mule API Analytics dashboard.
    2. Include the `$TOKEN` variable from the previous step in the next request, as shown in the following example that retrieves analytics for organizations without environments:
```
curl -H "Authorization: Bearer $TOKEN" "https://anypoint.mulesoft.com/analytics/1.0/<ORGANIZATION_ID>/events?format=csv&startDate=2016-01-01&endDate=2016-12-31&fields=Application%20Name.Client%20IP.Resource%20Path" > output.csv
```

  3. If the request is successful, an `output.csv` file is generated in the directory from which you initiated the `curl` request.
This next example queries the Analytics Events API for organizations with environments:


```
curl -H "Authorization: Bearer $TOKEN" "https://anypoint.mulesoft.com:443/analytics/1.0/<ORGANIZATION_ID>/environments/<ENVIRONMENT_ID>/events?format=csv&apiIds=<API_ID>&duration=30d" > output.csv
```

In this example, analytics data is retrieved for the past 30 days from the API with the API ID <API_ID>. The results are generated in a CSV format.
The following example combines two `curl` commands and displays values in the command prompt window:
```
TOKEN=$(curl -s https://anypoint.mulesoft.com/accounts/login -d "username=myusername&password=mypassword" | jq -r .access_token)
curl -H "Authorization: Bearer $TOKEN" "https://anypoint.mulesoft.com/analytics/1.0/42424242-4242-4242-4242-424242424242/events?format=csv&startDate=2016-01-01&endDate=2016-11-10&fields=Application%20Name.Client%20IP.Resource%20Path"
echo;echo
```

The following output is generated with this command:
```
"Application Name","Client IP","Resource Path",Timestamp,"API ID","API Version ID","API Name","API Version Name"
"Las Vegas T-Shirt serviceLas Vegas T-Shirt serviceLas Vegas",83.178.96.0,/,2016-10-03T04:27:02.072Z,61460,63811,"test api contracts",1
"Las Vegas T-Shirt serviceLas Vegas T-Shirt serviceLas Vegas",83.178.96.0,/,2016-10-03T05:03:38.774Z,61460,63811,"test api contracts",1
 ...
```

### Create a Report for Specific Environments
For organizations that have enabled environments, API events queried using the approach described in the topic belongs exclusively to the "Unclassified" environment.
To request events for APIs in a specific environment:
  1. Select the environment in the Environment selector and create the report that you want to run.
Reports are stored based on the environment. Therefore, different reports exist in different environments.
  2. Copy from the UI the report URL generated from creating the report.
Note that in addition to the organization ID, the URL also includes `/environment/{Environment ID}`. Anypoint Platform assigns a unique ID to an organization and an environment when they are created. For example, an API ID in the QA environment differs from its ID in the Production environment.
  3. To access events for a specific environment, append the environment ID to the report URL.


### Command Options Reference
You can add the following options to curl commands:
Option | Description  
---|---  
Comma-delimited list of API IDs to include in a query. Omit or specify `all` or `*` to include all APIs. **Type:** string **Required:** no **Example:** `appIds=42,54`  
**apiVersionIds** |  Comma-delimited list of API version IDs to include in query. Omit or specify `all` or `*` to include all API versions. Ignored if no value was specified for API IDs. **Type:** string **Required:** no **Example:** `apiVersionIds=42,54`  
The duration over which the report should return data. Consists of an integer number denoting quantity and a single-letter suffix denoting units. Suffix is one of:
  * `d`: Days
  * `h`: Hours
  * `m`: Minutes
  * `s`: Seconds
### Command Options Reference
You can add the following options to curl commands:
Option | Description  
---|---  
Comma-delimited list of API IDs to include in a query. Omit or specify `all` or `*` to include all APIs. **Type:** string **Required:** no **Example:** `appIds=42,54`  
**apiVersionIds** |  Comma-delimited list of API version IDs to include in query. Omit or specify `all` or `*` to include all API versions. Ignored if no value was specified for API IDs. **Type:** string **Required:** no **Example:** `apiVersionIds=42,54`  
The duration over which the report should return data. Consists of an integer number denoting quantity and a single-letter suffix denoting units. Suffix is one of:
  * `d`: Days
  * `h`: Hours
  * `m`: Minutes
  * `s`: Seconds

To cover a duration of one week, specify `7d` as the duration. To cover half a minute, specify `30s`. **Type:** string **Required:** no **Example:** `duration=45m`  
Fields to include in the report. Required for CSV output and optional for JSON output. The list of fields can be comma- or period-delimited. Use `%20` for spaces. You can use any value in Report Data Fields Reference. Timestamp, API Name, API ID, API Version, API Version ID are always included. **Type:** string **Required:** no **Example:** `fields=Hardware%20Platform.Client%20IP.Resource%20Path`  
Determines the serialization format of the returned data. Either `csv` or `json`. **Type:** string **Required:** yes **Example:** `format=csv`  
**maxResults** |  Maximum number of events to return. Default value is `20000`. **Type:** integer **Required:** no **Example:** `maxResults=3`  
Starting date and time, as described by `http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTimeParser()`[ISO Date Time Parser]. **Type:** date **Required:** no **Example:** `startDate=2016-01-01T08:15:30-05:00`  
Ending date and time, as described by `http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTimeParser()`. **Type:** date **Required:** no **Example:** `endDate=2016-11-10`  
## Report Data Fields Reference
Your report can query data for one or more of the available data fields:
Data Field Name | Description  
---|---  
**Application** |  Client ID associated with the incoming API request.  
**Application Name** |  Name of the application making the API request (only available when a client ID is passed with the request).  
Browser type associated with the incoming API request.  
The city from which the API request originated (inferred by the IP address of the client).  
IP address of the client making the API request.  
The continent from which the API request originated (inferred by the IP address of the client).  
The country from which the API request originated (inferred by the IP address of the client).  
**Hardware Platform** |  The hardware type of the client making the request (such as Mobile, Tablet, Desktop, etc.).  
**Message ID** |  Message ID value.  
The client OS type: Mac OS X, iOS, Windows, Linux.  
**OS Major Version** |  Operating system major version.  
**OS Minor Version** |  Operating system minor version.  
**OS Version** |  Operating system version.  
**Postal Code** |  The postal code from which the API request originated (inferred by the IP address of the client).  
**Request Outcome** |  Indicates whether a request was successful or resulted in a policy violation.  
**Request Size** |  The size (in bytes) of the incoming client request.  
**Resource Path** |  The path of the client request.  
**Response Size** |  The size in bytes of the API response. See note below.  
**Response Time** |  The processing time of the API request.  
**Status Code** |  The HTTP status code of the response.  
The time zone from which the API request originated (inferred by the IP address of the client).  
**User Agent Name** |  The complete user agent string for the incoming client request.  
**User Agent Version** |  The version of the user agent string for the incoming client request.  
The REST verb associated with the API client request (GET, POST, PATCH, etc.).  
**Violated Policy Name** |  The name of the policy violated by the API request (if any).  
In your query, if the `Content-Length` header is:
  * Present: `Response Size` is set to that value.
  * Not present and the payload is a String: Mule API Analytics calculates the length of the String and reports that value.
  * Not present and the payload is not a String: Mule API Analytics reports the response size as -1.
For example, if the output returned is a DataWeave stream and the `Content-Length` header is not present, the Analytics Event API does not report a response size because the value is not a String. However if your application performs a String conversion, the response size is listed.


## Restricting Client IP Data
If you don’t want to forward client IP data, set `anypoint.platform.analytics_include_client_ip=false` in the `wrapper.conf` file of your Mule runtime. To set properties, refer to Configuring Properties.
If you choose not to forward client IP data, geolocalized data such as **City** , **Continent** , **Postal Code** , **Country** , and **Timezone** is also not available.
## See Also
  * Viewing Mule API Analytics
  * jq command-line JSON processor