Use the AppDynamics REST API

On this page:

Related pages:

Use Curl to Access AppDynamics REST APIs

Introduction

You use the REST API to retrieve information from AppDynamics programmatically.

The AppDynamics REST API is implemented using Representational State Transfer (REST) Services. The data can be returned in either the JavaScript Object Notation (JSON) or the eXtensible Markup Language (XML) format. The default output format is XML.

The URIs in the Monitor APIs are a set of REST services that open access to Monitor data collected by AppDynamics. Each URI can be found by accessing:

http://<Controller_Host>:<Controller_Port>/controller/rest/<REST_URI>

You can find more general information about REST on Wikipedia.

You may find the REST Python Client Extension to be a useful tool.

For information about importing and exporting transaction detection configurations using REST, see Import and Export Transaction Detection Configuration.

REST API ver 2.0

For documentation of REST API ver 2.0, use the new self-documenting Live REST API Tool. In addition to documenting the new APIs, this tool lets you test an operation on your own controller. New and updated REST APIs continue to be added to this tool.

To access the Live REST API Tool:

In the Web browser, append the following to the first segment of the url of your 4.0+ AppDynamics controller after the slash:

api-docs/index.html

For example:

docsdemo:8080/api-docs/index.html

or

docsdemo/api-docs/index.html

When the tool appears, click Show/Hide to see the APIs.

Watch this short video to see how to use the tool:

How To Use the Live REST API Tool

Authentication

To invoke the REST APIs, provide basic HTTP authentication credentials as well as your account information. These are:

Account: the AppDynamics tenant account name
Username: a user in that account
Password: the password for that account

If you have installed an on-premise Controller on a single-tenant platform or if you are using the AppDynamics SaaS Controller, your default account is "customer1". In this case the username to log in with would be:

<your_username>@customer1

If you are using a multi-tenant Controller, you need to log in with a username in your multi-tenant account:

<your_username>@<your_accountname>

Invalid Characters for Usernames

Usernames that contain the following characters are not authenticated for REST API calls:

\ / " [ ] : | < > + = ; , ? * @, ' tab space

If you have already created usernames that contain any of the disallowed characters, such as "user:customer66", create a new username without the disallowed chartacter for the purpose of accessing the REST APIs.

Retrieve all business applications

URI: /controller/rest/applications

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
output	Query	HTTP Request parameter included as part of the URL to change the output format. Valid values are "XML" (default) or "JSON".	No

Example - Retrieve list of all business applications.

URI	Sample object output
/controller/rest/applications	XML
/controller/rest/applications?output=JSON	JSON

Retrieve all Business Transactions in a particular business application

URI: /controller/rest/applications/<application-name|application-id>/business-transactions

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
<application-name \| application-id>	URI	Provide either the application name or application id.	Yes
exclude	Query	If false, the query retrieves only the business transactions that are included for monitoring. If true, the query retrieves only the excluded business transactions. Excluded business transactions are those that have been configured to be excluded from monitoring either from the UI or through the REST interface. The default is false.	No
output	Query	HTTP Request parameter included as part of the URL to change the output format. Valid values are "XML" (default) or "JSON".	No

Retrieve all tiers in a business application

URI: /controller/rest/applications/<application-name|application-id>/tiers

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
<application-name \| application-id>	URI	Provide either the application name or application id.	Yes
output	Query	HTTP Request parameter included as part of the URL to change the output format. Valid values are "XML" (default) or "JSON".	No

Example - Retrieve the list of all tiers for the ACME Book Store.

URI	Sample object output
/controller/rest/applications/ACME Book Store Application/tiers	XML
/controller/rest/applications/ACME Book Store Application/tiers?output=JSON	JSON

Retrieve all Registered Backends in a business application with their Properties

URI: /controller/rest/applications/<application-name | application-id>/backends

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
<application-name \| application-id>	URI	Provide either the application name or application id.	Yes
output	Query	HTTP Request parameter included as part of the URL to change the output format. Valid values are "XML" (default) or "JSON".	No

Example - Retrieve the list of all backends for application 5.

URI
/controller/rest/applications/5/backends
/controller/rest/applications//5/backends?output=JSON

Retrieve machine, agent, and IP information about all nodes in a business application

URI: /controller/rest/applications/<application-name|application-id>/nodes

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
<application-name \| application-id>	URI	Provide either the application name or application id.	Yes
output	Query	HTTP Request parameter included as part of the URL to change the output format. Valid values are "XML" (default) or "JSON".	No

Example - Retrieve machine, agent and IP information about the nodes in application 3

URI	Sample object output
/controller/rest/applications/3/nodes	XML

Retrieve machine, agent, and IP information about a node by node name

URI: /controller/rest/applications/<application-name | application-id>/nodes/<node-name>

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
<application-name \| application-id>	URI	Provide either the application name or application id.	Yes
<node-name>	URI	Provide the node name	Yes
output	Query	HTTP Request parameter included as part of the URL to change the output format. Valid values are "XML" (default) or "JSON".	No

Example - Retrieve information about Node_8001 in application 3.

URI	Sample object output
/controller/rest/applications/3/nodes/Node_8001	XML

Retrieve machine, agent, and IP information about all the nodes in a tier

URI: /controller/rest/applications/<application-name | application-id>/tiers/<tier-name>/nodes

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
<application-name \| application-id>	URI	Provide either the application name or application id.	Yes
<tier-name>	URI	Provide the tier name.	Yes
output	Query	HTTP Request parameter included as part of the URL to change the output format. Valid values are "XML" (default) or "JSON".	No

Example - Retrieve information about the nodes in the E-Commerce tier in the ACME Online Book Store.

URI	Sample object output
/controller/rest/applications/ACME Online Book Store/tiers/E-Commerce/nodes/	XML

Retrieve information about a tier, including the tier ID and number of nodes, in a tier by tier name

URI: /controller/rest/applications/<application-name | application-id>/tiers/<tier-name>

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
<application-name \| application-id>	URI	Provide either the application name or application id.	Yes
<tier-name>	URI	Provide the tier name.	Yes
output	Query	HTTP Request parameter included as part of the URL to change the output format. Valid values are "XML" (default) or "JSON".	No

Example - Retrieve information about the ECommerce tier in the ACME Online Book Store.

URI	Sample object output
/controller/rest/applications/ACME Online Book Store/tiers/ECommerce	XML
/controller/rest/applications/ACME Online Book Store/tiers/ECommerce?output=JSON	JSON

Retrieve metrics

AppDynamics groups the metrics that it collects into following categories:

Backends
End User Experience
Mobile
Service End Points
Overall Application Performance
Business Transaction Performance
Application Infrastructure Performance
Errors
Information Points

To see the structure of the metric hierarchy of a business application in the AppDynamics UI, expand the nodes in the Metric Browser:

1. In the left navigation pane, select the application for which you are retrieving metrics.

2. Click Metric Browser.

3. In left panel expand the nodes in the metric tree.

You can copy the URI for fetching any metric directly from any node in the Metric Browser. This is the easiest way to construct a query to retrieve a particular metric. You can also copy just the metric path portion of the query.

The child elements in the metric path expression are separated by the pipe character (|). The pipe character must not appear at the beginning or end of the metric path expression.

The easiest way to construct a query to retrieve a metric is to select the metric in Metric Browser, copy the REST URL, and paste it into your browser. An alternative is select the metric and copy the metric path, and construct the query by prefacing the metric path with "metric-data?metric-path=".

To Copy the REST URL for a Metric

To copy the REST URL for any metric captured by AppDynamics:

1. Open the Metric Browser as described above.

2. Select the item for which you want to retrieve metrics in the metric tree. You can retrieve the URL at any level of the tree.

3. Right-click the item and select Copy REST URL from the drop-down menu.

4. Paste the URL into your Web browser to run the query.

The copied query in this example is

http://cent-docsdemo-01:8080/controller/rest/applications/ACME%20Book%20Store%20Application/metric-data?metric-path=Overall%20Application%20Performance%7CAverage%20Response%20Time%20%28ms%29&time-range-type=BEFORE_NOW&duration-in-mins=15

The time range in the request is based on the setting of the time range in the Metric Browser when you copied the URL. You can edit a copied query to change the time range and duration. See Retrieve metrics for a time range for more information.

To Copy the Metric-Path Parameter

You also copy only the metric path for a specific metric.

To copy a metric path:

1. Open the Metric Browser as described above.

2. Select the item for which you want to retrieve metrics in the metric tree. You can retrieve the metric path at any level of the tree.

3. Right-click the item and select Copy Full Path from the drop-down menu.

4. Use the metric path to construct your query.

The copied data in this example is s

Overall Application Performance|Average Response Time (ms)

Structure of Returned Metrics

The data is returned in a tree structure. If a child element is a container item, its <type> tag is set to "folder". Otherwise the <type> tag for the child element is set to "leaf".

A folder <type> tag indicates that the metric has child elements. The API retrieves the first generation of child elements. You can expand only the children of the folder type.

Values of Returned Metrics

Results are returned in a metricValues structure that contains the following fields:

current
Value for the current minute. Used only when the time rollup type used by the Controller is current.
count
Number of times the agent collected the metric over the selected time period.
max
min
The "min" and "max" values are the minimum and maximum values reported across the selected time period. These are not used for all metric types.
occurrences
Number of data samples taken by the Controller to calculate the standard deviation.
standardDeviation
Intermediate values calculated by the Controller during time rollup used to calculate standard deviation.
startTimeInMillis
The startTimeInMillis is the start time of the time range to which the result metric data applies, in UNIX epoch time.
sum
Total accumulated value for the metric over the selected time period.
useRange
Used internally by the Controller to process the metric.
value
The "value" value is one of the following for all metric values reported across the configured evaluation time length:
- arithmetic average, if the metric time rollup type is average
- sum, if the metric time rollup type is sum
- latest, if the metric time rollup type is current

The Controller uses this standard formula to calculate the standard deviation:

std dev = sqrt [(B - A^2/N)/N]
where
  A is the sum of the data values. 
  B is the sum of the squared data values.
  N is the number of data values.

By default, the values of the returned metrics are rolled up into a single data point (rollup=true). To get separate results for all the values within the specified time range, set the rollup parameter to false in the query.

The returned metricValues structure typically looks like this:

Sample XML output with rollup=true

<metricValues>
    <metric-value>
        <startTimeInMillis>1411678680000</startTimeInMillis>
        <value>14</value>
        <min>0</min>
        <max>0</max>
        <current>6</current>
        <sum>205</sum>
        <count>30</count>
        <standardDeviation>0.0</standardDeviation>
        <occurrences>0</occurrences>
        <useRange>false</useRange>
    </metric-value>
</metricValues>

Sample XML output with rollup=false

<metricValues>
    <metric-value>
        <startTimeInMillis>1411678680000</startTimeInMillis>
        <value>28</value>
        <min>0</min>
        <max>0</max>
        <current>13</current>
        <sum>28</sum>
        <count>2</count>
        <standardDeviation>0.0</standardDeviation>
        <occurrences>0</occurrences>
        <useRange>false</useRange>
    </metric-value>
    <metric-value>
        <startTimeInMillis>1411678740000</startTimeInMillis>
        <value>17</value>
        <min>0</min>
        <max>0</max>
        <current>9</current>
        <sum>17</sum>
        <count>2</count>
        <standardDeviation>0.0</standardDeviation>
        <occurrences>0</occurrences>
        <useRange>false</useRange>
    </metric-value>
    <metric-value>
    . . . 
    . . . 

</metricValues>

Sample JSON output with rollup=true

  "metricValues": [  {
    "count": 30,
    "current": 8,
    "max": 0,
    "min": 0,
    "occurrences": 0,
    "standardDeviation": 0,
    "startTimeInMillis": 1411682880000,
    "sum": 145,
    "useRange": false,
    "value": 10
  }]

Sample JSON ouput with rollup=false

 "metricValues":   [
        {
      "count": 2,
      "current": 1,
      "max": 0,
      "min": 0,
      "occurrences": 0,
      "standardDeviation": 0,
      "startTimeInMillis": 1411682760000,
      "sum": 2,
      "useRange": false,
      "value": 2
    },
        {
      "count": 2,
      "current": 1,
      "max": 0,
      "min": 0,
      "occurrences": 0,
      "standardDeviation": 0,
      "startTimeInMillis": 1411682820000,
      "sum": 4,
      "useRange": false,
      "value": 4
    },
    . . . 
    . . .

Retrieve metric hierarchy

URI: /controller/rest/applications/<application-name| application-id>/metrics

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
<application-name \| application-id>	URI	Provide either the application name or application id.	Yes
metrics	Query		Yes
output	Query	HTTP Request parameter included as part of the URL to change the output format. Valid values are "XML" (default) or "JSON".	No

Example - Retrieve the metric hierarchy for the ACME Book Store Application.

URI	Sample object output
/controller/rest/applications/ACME Book Store Application/metrics	XML
/controller/rest/applications/ACME Book Store Application/metrics?output=JSON	JSON

Use Wild cards in Metric-Path Parameter

You can use the asterisk (*) wild card in the metric data to request metric data for all the instances of AppDynamics entity, such as a business transaction name, tier name or node name, in the metric path.

Example - Retrieve the average response time for all the tiers in the application using the wild card character for the tier name.

URI

Sample object output

/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Overall Application Performance|*|Average Response Time (ms)&time-range-type=BEFORE_NOW&duration-in-mins=15

XML

/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Overall Application Performance|*|Average Response Time (ms)&time-range-type=BEFORE_NOW&duration-in-mins=15&output=JSON

JSON

Example - Retrieve the CPU %Busy metric for all the nodes in the ECommerce tier using the wild card character for the node name.

URI

Sample object output

/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Application Infrastructure Performance|ECommerce Server|Individual Nodes|*|Hardware Resources|CPU|%Busy&time-range-type=BEFORE_NOW&duration-in-mins=15

XML

/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Application Infrastructure Performance|ECommerce Server|Individual Nodes|*|Hardware Resources|CPU|%Busy&time-range-type=BEFORE_NOW&duration-in-mins=15=JSON

JSON

Example - Retrieve the CPU %Busy metric for all the nodes in all the tiers using wild card characters for the tier and node names.

URI

Sample object output

/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Application Infrastructure Performance|*|Individual Nodes|*|Hardware Resources|CPU|%Busy&time-range-type=BEFORE_NOW&duration-in-mins=15

XML

/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Application Infrastructure Performance|*|Individual Nodes|*|Hardware Resources|CPU|%Busy&time-range-type=BEFORE_NOW&duration-in-mins=15&output=JSON

JSON

Example - Retrieve the Calls per Minute metric for all the business transactions on the ECommerce tier using the wild card character for the business transaction name

URI

Sample object output

/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Business Transaction Performance|Business Transactions|ECommerce Server|*|Calls per Minute&time-range-type=BEFORE_NOW&duration-in-mins=15

XML

/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Business Transaction Performance|Business Transactions|ECommerce Server|*|Calls per Minute&time-range-type=BEFORE_NOW&duration-in-mins=15&output=JSON

JSON

Retrieve metrics for a time range

You can fetch the data for any specified metrics for any time range.

Note that metric data REST URIs restrict the amount of data that can be returned. The maximum is 200 metrics.

URI: /controller/rest/applications/<application-name>/metric-data

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
<application-name \| application-id>	URI	Provide either the application name or application id.	Yes
metric-path	Query	The metric expression to get the metric data. Use the pipe character to separate the parent and child name elements in the tree. The Pipe delimiter must not appear at the beginning or at the end of the metric expression.	Yes
time-range-type	Query	Possible values are: BEFORE_NOW To use the "BEFORE_NOW" option, you must also specify the "duration-in-mins" parameter. BEFORE_TIME To use the "BEFORE_TIME" option, you must also specify the "duration-in-mins" and "end-time" parameters. AFTER_TIME To use the "AFTER_TIME" option, you must also specify the "duration-in-mins" and "start-time" parameters. BETWEEN_TIMES To use the "BETWEEN_TIMES" option, you must also specify the "start-time" and "end-time" parameters. The "BETWEEN_TIMES" range includes the start- time and excludes the end-time.	Yes
duration-in-mins	Query	Duration (in minutes) to return the metric data.	If time-range-type is BEFORE_NOW, BEFORE_TIME, or AFTER_TIME
start-time	Query	Start time (in milliseconds) from which the metric data is returned in UNIX epoch time.	If time-range-type is AFTER_TIME or BETWEEN_TIMES
end-time	Query	End time (in milliseconds) until which the metric data is returned in UNIX epoch time.	If time-range-type is BEFORE_TIME or BETWEEN_TIMES
rollup	Query	Default is true. If true, value as single data point is returned. If false, all the values within the specified time range are returned.	No
output	Query	HTTP Request parameter included as part of the URL to change the output format. Valid values are "XML" (default) or "JSON".	No

Example - Retrieve the average response time for the past 15 minutes on the ECommerce server.

URI	Sample object output
/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Overall Application Performance\|ECommerce Server\|Average Response Time (ms)&time-range-type=BEFORE_NOW&duration-in-mins=15	XML
/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Overall Application Performance\|ECommerce Server\|Average Response Time (ms)&time-range-type=BEFORE_NOW&duration-in-mins=15&output=JSON	JSON

Example - Retrieve the multiple metrics, for the past 15 minutes, for the ViewCart.sendItems transaction on the ECommerce server.

URI	Sample object output
/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Business Transaction Performance\|Business Transactions\|ECommerce Server\|ViewCart.sendItems\|*&time-range-type=BEFORE_NOW&duration-in-mins=15	XML
/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Business Transaction Performance\|Business Transactions\|ECommerce Server\|ViewCart.sendItems\|*&time-range-type=BEFORE_NOW&duration-in-mins=15	JSON

Example - Retrieve the average cpu used by the All Other Traffic business transaction during the past 15 minutes on the ECommerce server.

Enter "APPDYNAMICS_DEFAULT_TX" for the All Other Traffic" transaction for the tier. See Business Transactions for general information about the All Other Traffic business transaction.

URI	Sample object output
/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Business Transaction Performance\|Business Transactions\|ECommerce Server\|APPDYNAMICS_DEFAULT_TX\|Average CPU Used (ms)&time-range-type=BEFORE_NOW&duration-in-mins=15	XML

Example - Retrieve snapshots for the 15 minutes after Mon, 13 Aug 2012 08:20:41 for the ACME Book Store Application.

URI	Sample object output
/controller/rest/applications/3/request-snapshots?time-range-type=AFTER_TIME&start-time=1344846041495&duration-in-mins=15	XML
/controller/rest/applications/3/request-snapshots?time-range-type=AFTER_TIME&start-time=1344846041495&duration-in-mins=15&output=JSON	JSON

Example - Retrieve snapshots for the 15 minutes before Mon, 13 Aug 2012 08:20:41 for the ACME Book Store Application.

URI	Sample object output
/controller/rest/applications/3/request-snapshots?time-range-type=BEFORE_TIME&end-time=1344846041495&duration-in-mins=15	XML
/controller/rest/applications/3/request-snapshots?time-range-type=BEFORE_TIME&end-time=1344846041495&duration-in-mins=15&output=JSON	JSON

Example - Retrieve snapshots for the time range between Mon, 13 Aug 2012 08:20:41 and Mon, 13 Aug 2012 08:22:21 GMT for the ACME Book Store Application.

URI	Sample object output
/controller/rest/applications/3/request-snapshots?time-range-type=BEFORE_TIME&end-time=1344846041495&duration-in-mins=15	XML
/controller/rest/applications/3/request-snapshots?time-range-type=BEFORE_TIME&end-time=1344846041495&duration-in-mins=15&output=JSON	JSON

Retrieve all health rule violations in a particular business application

URI: /controller/rest/applications/<application-name|application-id>/problems/healthrule-violations

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
<application-name \| application-id>	URI	Provide either the application name or application id.	Yes
time-range-type	Query	Possible values are: BEFORE_NOW To use the "BEFORE_NOW" option, you must also specify the "duration-in-mins" parameter. BEFORE_TIME To use the "BEFORE_TIME" option, you must also specify the "duration-in-mins" and "end-time" parameters. AFTER_TIME To use the "AFTER_TIME" option, you must also specify the "duration-in-mins" and "start-time" parameters. BETWEEN_TIMES To use the "BETWEEN_TIMES" option, you must also specify the "start-time" and "end-time" parameters. The "BETWEEN_TIMES" range includes the start- time and excludes the end-time.	Yes
duration-in-mins	Query	Duration (in minutes) to return the metric data.	If time-range-type is BEFORE_NOW, BEFORE_TIME, or AFTER_TIME
start-time	Query	Start time (in milliseconds) from which the metric data is returned.	If time-range-type is AFTER_TIME or BETWEEN_TIMES
end-time	Query	End time (in milliseconds) until which the metric data is returned.	If time-range-type is BEFORE_TIME or BETWEEN_TIMES
output	Query	HTTP Request parameter included as part of the URL to change the output format. Valid values are "XML" (default) or "JSON".	No

Retrieve event data

You can capture data for the event types listed in the event-types parameter.

URI: /controller/rest/applications/<application-name|application-id>/events

Parameter Name	Parameter Type	Value	Mandatory
<application-name \| application-id>	URI	Provide either the application name or application id.	Yes
time-range-type	Query	Possible values are: BEFORE_NOW To use the "BEFORE_NOW" option, you must also specify the "duration-in-mins" parameter. BEFORE_TIME To use the "BEFORE_TIME" option, you must also specify the "duration-in-mins" and "end-time" parameters. AFTER_TIME To use the "AFTER_TIME" option, you must also specify the "duration-in-mins" and "start-time" parameters. BETWEEN_TIMES To use the "BETWEEN_TIMES" option, you must also specify the "start-time" and "end-time" parameters. The "BETWEEN_TIMES" range includes the start- time and excludes the end-time.	Yes
duration-in-mins	Query	Specify the duration (in minutes) to return the metric data.	If time-range-type is BEFORE_NOW, BEFORE_TIME, or AFTER_TIME
start-time	Query	Specify the start time (in milliseconds) from which the metric data is returned.	If time-range-type is AFTER_TIME or BETWEEN_TIMES
end-time	Query	Specify the end time (in milliseconds) until which the metric data is returned.	If time-range-type is BEFORE_TIME or BETWEEN_TIMES
event-types	Query	Specify the comma-separated list of event types for which you want to retrieve event information. See the Events Reference for the valid event types.	Yes
severities	Query	Specify the comma-separated list of severities for which you want to retrieve event information. The severities are: INFO WARN ERROR	Yes
output	Query	HTTP Request parameter included as part of the URL to change the output format. Valid values are "XML" (default) or "JSON".	No

Example - Retrieve the list of events of type "APPLICATION_ERROR" or "DIAGNOSTIC_SESSION" of any severity that occurred in the specified time range.

URI	Sample object output
/controller/rest/applications/ACME%20Book%20Store%20Application/events?time-range-type=BEFORE_NOW&duration-in-mins=30&event-types=%20APPLICATION_ERROR,DIAGNOSTIC_SESSION&severities=INFO,WARN,ERROR&output=XML	XML
/controller/rest/applications/ACME%20Book%20Store%20Application/events?time-range-type=BEFORE_NOW&duration-in-mins=30&event-types=%20APPLICATION_ERROR,DIAGNOSTIC_SESSION&severities=INFO,WARN,ERROR&output=JSON	JSON

Create Events

You can create APPLICATION_DEPLOYMENT and CUSTOM events.

Application Deployment Event Integration

The AppDynamics REST API lets you integrate events of type "APPLICATION_DEPLOYMENT" with other systems.

For example, suppose you want to create an event automatically in your AppDynamics monitored system for every new release. To integrate these systems, use the following REST API to create an event of type "APPLICATION_DEPLOYMENT" in your managed environment.

This is a POST request. You should receive the event ID after successful invocation of the request.

URI: /controller/rest/applications/<application-name|application-id>/events

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
<application-name \| application-id>	URI	Provide either application name or application id.	Yes
summary	Query	Provide the summary for the event.	Yes
comment	Query	Provide the comments (if any) for the event.	No
eventtype	Query	APPLICATION_DEPLOYMENT	Yes
severity	Query	Provide a severity level. Allowed values "INFO" "WARN" "ERROR" In the UI, these become "Info", "Warning", and "Critical"	Yes

Create a Custom Event

The AppDynamics REST API lets you create a custom event.

This is a POST request. You should receive the event ID after successful invocation of the request.

URI: /controller/rest/applications/<application-name|application-id>/events

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
<application-name \| application-id>	URI	Provide either application name or application id.	Yes
summary	Query	Provide a summary describing the event.	Yes
comment	Query	Provide a comment for the event.	No
severity	Query	Provide a severity level. Allowed values "INFO" "WARN" "ERROR" In the UI, these become "Info", "Warning", and "Critical"	Yes
eventtype	Query	CUSTOM	Yes
customeventtype	Query	Provide a name for the "type"; for example, the source, like "nagios"	No
node	Query	Provide the affected node name	No
tier	Query	Provide the affected tier name	Yes, if node and bt are specified
bt	Query	Provide the affected business transaction name	No
propertynames	Query	Provide a property name as a pair, i.e., the "key"	No, but if one element of the pair is defined, the other must be defined also
propertyvalues	Query	Provide the property value as a pair, i.e., the "value"	No, but if one element of the pair is defined, the other must be defined also

Example

/controller/rest/applications/<application-name|application-id>/events?eventtype=CUSTOM&customeventtype=nagios&summary=test1&propertynames=key1&propertynames=key2&propertyvalues=value1&propertyvalues=value2

Note the pattern for custom properties: propertynames and propertyvalues get matched up by order position, so to set N property values, you need N occurrences of propertynames and N occurrences of propertyvalues.

Create Custom URLS for Notifications

This is an HTTP POST operation.

Single tenants in a multi-tenant controller instance can specify a custom "vanity" URL for notification purposes, so that instead of a URL like "paid8.appdynamics.com" the host is displayed as something like "mycompany.appdynamics.com" in the notification.

URI: /controller/rest/accounts/<customer-name>/update-controller-url

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
<customer-name>	URI	Provide the customer account name	Yes

Body (Application/JSON)

{
"controllerURL": "http://<my-custom-hostname:port>"
}

Create and Delete Action Suppressions

By default any response is in JSON, although XML can be requested by using the following header:

Name : Accept

Value : application/vnd.appd.cntrl+xml;v=1

Retrieve All Existing Action Suppressions

This is a GET request. You should get a list of all existing action suppressions.

URI: /controller/api/accounts/<account-id>/applications/<application-id>/actionsuppressions

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
<account-id>	URI	The account id	Yes
<application-id>	URI	The application id	Yes

Example request to get all action suppressions:

/controller/api/accounts/2/applications/9/actionsuppressions

Example response:

Status : 200 ok
Output Data :
{"actionSuppressions": [{"id": "15","name": "App-ASW","timeRange": {"startTimeMillis": "2014-10-25T04:16:30+0000","endTimeMillis": "2014-10-25T06:16:30+0000"},"affects": {"type": "APP"}},{"id": "16","name": "Node-ASW","timeRange": {"startTimeMillis": "2014-10-25T04:16:57+0000","endTimeMillis": "2014-10-25T05:16:57+0000"},"healthRuleIds": [60,61],"affects": {"type": "NODE","nodeAffectedEntities": {"type": "SPECIFIC","nodeType": "ALL","nodes": [17,18]}}}],"actions": [{"href": "http://ec2-54-80-163-175.compute-1.amazonaws.com:8090/controller/api/accounts/2/applications/9/actionsuppressions/%7Bactionsuppressions.id%7D/%7Bactions.name%7D","method": ["POST","DELETE"],"name": "enabled"}],"links": [{"href": "http://ec2-54-80-163-175.compute-1.amazonaws.com:8090/controller/api/accounts/2/applications/9/actionsuppressions/%7Bactionsuppressions.id%7D","name": "actionsuppressions"}]}

Retrieve a Specific Action Suppression by ID

This is a GET request. You should get the action suppression of the ID you request.

URI: /controller/api/accounts/<account-id>/applications/<application-id>/actionsuppressions/<actionsuppression-id>

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
<account-id>	URI	The account id	Yes
<application-id>	URI	The application id	Yes
<actionsuppressions-id>	URI	The action suppression id	Yes

Example request:

/controller/api/accounts/2/applications/9/actionsuppressions/15

Example response:

Status : 200 ok
Output Data :
{"id": "15","name": "App-ASW","timeRange": {"startTimeMillis": "2014-10-25T04:16:30+0000","endTimeMillis": "2014-10-25T06:16:30+0000"},"affects": {"type": "APP"}}

Create a New Action Suppression

This is a POST request. You should only get a 201 - created.

URI: /controller/api/accounts/<account-id>/applications/<application-id>/actionsuppressions

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
<account-id>	URI	The account id	Yes
<application-id>	URI	The application id	Yes
name	body key	The name of the action suppression window	Yes
timeRange	body key	The start and end time of the window Includes: startTimeMillis, eg 2014-10-25T04:16:57+0000 endTimeMillis, eg 2014-10-25T05:16:57+0000	Yes
healthRuleIds	body key	The ids of the affected health rules. If not provided, all rules affected	No
affects	body key	Type of entity and corresponding ids (see below)	Yes

Content of "affects"

Scope	Type	Value	Example
Application	APP	Covers the entire application	"affects": {"type": "APP"}
Business Transaction	BT	Covers one or more Business Transactions
		All Business Transactions	"affects": {"type": "BT","btAffectedEntities": {"type": "ALL"}}
		Business Transactions from specific tiers	"affects": {"type": "BT","btAffectedEntities": {"type": "WITHIN_TIERS","tiers": [11,12]}} where 11,12 are Tier Ids
		Specific Business Transactions by id	"affects": {"type": "BT","btAffectedEntities": {"type": "SPECIFIC","bts": [1,2]}} where 1,2 are BT Ids
		Business Transactions that match criteria	"affects": {"type": "BT","btAffectedEntities": {"type": "CRITERIA","matchesOperator": "CONTAINS","matchesValue": "pojo"}} where "matchesOperator" can be: CONTAINS EQUALS STARTS ENDS REGEX_VALUE
Tier	TIER	Covers one or more tiers
		All tiers	"affects": {"type": "TIER","tierAffectedEntities": {"type": "ALL"}}
		Specific tiers	"affects": {"type": "TIER","tierAffectedEntities": {"type": "SPECIFIC","tiers": [11,12]}} where 11,12 are Tier Ids
Node	NODE	Covers one or more nodes
		All nodes	"affects": {"type": "NODE","nodeAffectedEntities": {"type": "ALL","nodeType": "ALL"}}
		Nodes belonging to specific tiers	"affects": {"type": "NODE","nodeAffectedEntities": {"type": "WITHIN_TIERS","nodeType": "ALL","tiers": [11,12]}} where 11,12 are Tier Ids
		Specific nodes	"affects": {"type": "NODE","nodeAffectedEntities": {"type": "SPECIFIC","nodeType": "ALL","nodes": [9,10]}} where 9,10 are Node Ids
		Nodes that match criteria	"affects": {"type": "NODE","nodeAffectedEntities": {"type": "NAME_CRITERIA","nodeType": "ALL","nameMatchesOperator": "EQUALS","nameMatchesValue": "Node"}} - String match "affects": {"type": "NODE","nodeAffectedEntities": {"type": "PROPERTY_CRITERIA","nodeType": "ALL","metaInfoProperties": [{"name": "ProcessID","value": "12343"}]}} - Meta Info Properties match where "matchesOperator" can be: CONTAINS EQUALS STARTS ENDS REGEX_VALUE
Machine	MACHINE	Covers one or more machines	"affects": {"type": "MACHINE","machineAffectedEntities": {"type": "SPECIFIC","machines": [4,5]}} where 4,5 are Machine Ids

Example request:

 /controller/api/accounts/2/applications/9/actionsuppressions

Header

Name - Content-Type

Value - application/vnd.appd.cntrl+json;v=1

Body

{"name": "App-ASW_2","timeRange": {"startTimeMillis": "2014-10-25T04:16:30+0000","endTimeMillis": "2014-10-25T06:16:30+0000"},"affects": {"type": "APP"}}

or

{"name": "Node-ASW_1","timeRange": {"startTimeMillis": "2014-10-25T04:16:57+0000","endTimeMillis": "2014-10-25T05:16:57+0000"},"healthRuleIds": [60,61],"affects": {"type": "NODE","nodeAffectedEntities": {"type": "SPECIFIC","nodeType": "ALL","nodes": [17,18]}}}

Delete a Specific Action Suppression by ID

This is a DELETE request. You should only get a 204 - No Content

URI: /controller/api/accounts/<account-id>/applications/<application-id>/actionsuppressions/<actionsuppression-id>

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
<account-id>	URI	The account id	Yes
<application-id>	URI	The application id	Yes
<actionsuppression-id>	URI	The id of the action suppression to be deleted	Yes

Retrieve transaction snapshots for a Business Transaction for a time range

URI: /controller/rest/applications/<application-id>/request-snapshots

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
<application-id>	URI	Provide either the application name or application id.	Yes
time-range-type	Query	Possible values are: BEFORE_NOW To use the "BEFORE_NOW" option, you must also specify the "duration-in-mins" parameter. BEFORE_TIME To use the "BEFORE_TIME" option, you must also specify the "duration-in-mins" and "end-time" parameters. AFTER_TIME To use the "AFTER_TIME" option, you must also specify the "duration-in-mins" and "start-time" parameters. BETWEEN_TIMES To use the "BETWEEN_TIMES" option, you must also specify the "start-time" and "end-time" parameters. The "BETWEEN_TIMES" range includes the start- time and excludes the end-time.	Yes
duration-in-mins	Query	Duration (in minutes) to return the data.	If time-range-type is BEFORE_NOW, BEFORE_TIME, or AFTER_TIME
start-time	Query	Start time (in milliseconds) from which the data is returned.	If time-range-type is AFTER_TIME or BETWEEN_TIMES
end-time	Query	End time (in milliseconds) until which the data is returned.	If time-range-type is BEFORE_TIMEor BETWEEN_TIMES
guids	Query	Array of comma-separated guids for the transaction snapshots. If not specified, retrieves all snapshots in the specified time range.	No
archived	Query	True to retrieve archived snapshots. Default is false.	No
deep-dive-policy	Query	Array of comma-separated snapshot policy filters to apply. Valid values are: SLA_FAILURE TIME_SAMPLING ERROR_SAMPLING OCCURRENCE_SAMPLING ON_DEMAND HOTSPOT HOTSPOT_LEARN APPLICATION_STARTUP SLOW_DIAGNOSTIC_SESSION ERROR_DIAGNOSTIC_SESSION POLICY_FAILURE_DIAGNOSTIC_SESSION DIAGNOSTIC_SESSION INFLIGHT_SLOW_SESSION	No
application-component-ids	Query	Array of comma-separated tier IDs to filter. Default is all the tiers in the application.	No
application-component-node-ids	Query	Array of comma-separated node ID filters. Default is all the nodes in the application	No
business-transaction-ids	Query	Array of comma-separated business transaction ID filters. Default is all the business transactions in the application.	No
user-experience	Query	Array of comma-separated user experiences filters. Valid values are: NORMAL SLOW VERY_SLOW STALL ERROR	No
first-in-chain	Query	If true, retrieve only the first request from the chain. Default is false.	No
need-props	Query	If true, the values of the following snapshot properties are included in the output. These values correspond to the values of the data-collector-type parameter. If false, these values are empty in the REST output. The default is false. New in 3.7.11. errorDetails errorIDs httpParameters businessData cookies httpHeaders sessionKeys responseHeaders logMessages transactionProperties transactionEvents dotnetProperty	No
need-exit-calls	Query	If true, exit calls are included in the result. Default is false.	No
execution-time-in-milis	Query	If set, retrieves only data for requests with execution times greater than this value.	No
session-id	Query	If set, retrieves data only for this session id.	No
user-principal-id	Query	If set, retrieves data only for this user login.	No
error-ids	Query	Array of comma-separated error codes to filter by. Default is to retrieve all error codes.	No
starting-request-id, ending-request-id	Query	If set, retrieves data only for this range of request IDs.	No
error-occurred	Query	If true, retrieves only error requests. Default is false.	No
diagnostic-snapshot	Query	If true, retrieves only diagnostic snapshots. Default is false.	No
bad-request	Query	If true, retrieves only slow and error requests. Default is false.	No
diagnostic-session-guid	Query	Array of comma-separated diagnostic session guids to filter.	No
data-collector-name	Query	Used with data-collector-value to filter snapshot collection based on the value of a data collector. New in 3.6.1.	No
data-collector-value	Query	Used with data-collector-name to filter snapshot collection based on the value of a data collector. New in 3.6.1.	If data-collector-name is set.
data-collector-type	Query	Used with data-collector-name and data-collector-value to filter snapshot collection based on the value of a data collector. New in 3.6.1. Some of the values contain spaces. All are case-sensitive and where indicated the spaces are required. Valid values are: Error IDs Stack Traces Error Detail Http Parameter Business Data (This type is a method invocation data collector.) Cookie Http Header Session Key Response Header Log Message Transaction Property Transaction Event Dotnet Property isProtoBuf EUM Request GUID
output	Query	HTTP Request parameter included as part of the URL to change the output format. Valid values are "XML" (default) or "JSON".	No

Example - Retrieve list of transaction snapshots for the ACME Book Store.

URI	Sample object output
/controller/rest/applications/AcmeOnlineBookStore/request-snapshots?time-range-type=BEFORE_NOW&duration-in-mins=2	XML
/controller/rest/applications/AcmeOnlineBookStore/request-snapshots?time-range-type=BEFORE_NOW&duration-in-mins=2&output=JSON	JSON

Example - Retrieve list of transaction snapshots including the snapshot fields that are associated with an Http Parameter data collector.

URI	Sample object output
controller/rest/applications/2/request-snapshots?time-range-type=BEFORE_NOW&duration-in-mins=120&data-collector-type=Http%20Parameter&data-collector-name=param1&data-collector-value=%5B100%5D&need-props=true]	XML
controller/rest/applications/2/request-snapshots?time-range-type=BEFORE_NOW&duration-in-mins=120&data-collector-type=Http%20Parameter&data-collector-name=param1&data-collector-value=%5B100%5D&need-props=true&output=JSON]	JSON

Create and modify AppDynamics users

This is an HTTP POST operation.

The create and modify user URIs are identical except for the user-id parameter, which is not passed for the create operation. The user-id is generated by the create operation.
A response code of 200 indicates success.

URI: /controller/rest/users

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
user-name	Query	user name	Yes
user-id	Query	user id	No for a create; yes for an update
user-display-name	Query	display name	Yes
user-roles	Query	comma-separated list of roles	No
user-password	Query	user password	Yes for create; optional for update
user-email	Query	user email	Yes

Include or exclude a business transaction from monitoring

This is an HTTP POST operation.

To exclude a business transaction from monitoring, set the exclude parameter to true.

To turn on monitoring for a currently excluded business transaction, set the exclude parameter to false.

Send the list of business transactions to be excluded or re-included as xml payload, not as parameters.
A sample business-transaction-list is:

<business-transactions>
    <business-transaction>
        <id>15</id>
    </business-transaction>
    <business-transaction>
        <id>16</id>
    </business-transaction>
</business-transactions>

Make sure the Content-Type header is set to "application/xml".

URI: /controller/rest/applications/<application-name | application-id>/business-transactions

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
<application-name \| application-id>	URI	Provide either the application name or application id.	Yes
exclude	Post	true\|false	Yes

Example - Exclude business transaction 166 from monitoring.

URI
/controller/rest/applications/AcmeOnlineBookStore/business-transactions?exclude=true

This is the way the request appears in the Google Advanced REST Client:

Retrieve all controller global configuration values

These are the values that you set interactively from the Controller Settings screen in the AppDynamics Administration console.

Access requires the "root" password, which was created for the AppDynamics admin user when the controller was installed. See Access the Administration Console.

URI: /configuration

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
output	Query	HTTP Request parameter included as part of the URL to change the output format. Valid values are "XML" (default) or "JSON".	No

Example - Retrieve list of all global configuration values

URI	Sample object output
/controller/rest/configuration	XML
/controller/rest/configuration?output=JSON	JSON

Retrieve a single controller global configuration value

URI: /configuration?name=<controller_setting_name>

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
name	Query	Name of the Controller setting to retrieve	Yes
output	Query	HTTP Request parameter included as part of the URL to change the output format. Valid values are "XML" (default) or "JSON".	No

Example - Retrieve the global metrics buffer size.

URI	Sample object output
/controller/rest/configuration?name=metrics.buffer.size	XML
/controller/rest/configuration?name=metrics.buffer.size&output=JSON	JSON

Configure Global Controller Settings

This is an HTTP POST operation.

URI: /controller/rest/configuration

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
name	Query	name of a controller setting; to see all the names, retrieve all the values as described in Example - Retrieve list of all global configuration values	Yes
value	Query	value to set	Yes

Mark Nodes as Historical

This is an HTTP POST operation.

Pass as parameters a comma-separated list of one or more node ids of the nodes to be marked as historical. You can specify up to a maximum of 25 node ids to be marked.

AppDynamics stops collecting metrics for a node that is marked as historical.

By default AppDynamics marks as historical (soft deletes) a node that has lost contact with the Controller for the number of hours configured in the node.retention.period controller setting. The default is 500 hours.

Information from a historical node can be retrieved until the node has lost contact with the controller for the number of hours configured in the node.permanent.deletion.period, after which time the historical node is permanently deleted. The default is 720 hours.

URI: /controller/rest/mark-nodes-historical?application-component-node-ids=44,45

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
application-component-node-ids	Query	comma-separated list of node ids	Yes

Example - Mark nodes 44 and 45 as historical.

URI	Sample object output
/controller/rest/mark-nodes-historical?application-component-node-ids=44,45	XML

Retrieve all policy violations in a particular business application

This URI is maintained for compatibility with pre-3.7 versions. Use Retrieve all health rule violations in a particular business application for 3.7 and later.

URI: /controller/rest/applications/<application-name|application-id>/problems/policy-violations

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
<application-name \| application-id>	URI	Provide either the application name or application id.	Yes
time-range-type	Query	Possible values are: BEFORE_NOW To use the "BEFORE_NOW" option, you must also specify the "duration-in-mins" parameter. BEFORE_TIME To use the "BEFORE_TIME" option, you must also specify the "duration-in-mins" and "end-time" parameters. AFTER_TIME To use the "AFTER_TIME" option, you must also specify the "duration-in-mins" and "start-time" parameters. BETWEEN_TIMES To use the "BETWEEN_TIMES" option, you must also specify the "start-time" and "end-time" parameters.	Yes
duration-in-mins	Query	Duration (in minutes) to return the metric data.	If time-range-type is BEFORE_NOW, BEFORE_TIME, or AFTER_TIME
start-time	Query	Start time (in milliseconds) from which the metric data is returned.	If time-range-type is AFTER_TIME or BETWEEN_TIMES
end-time	Query	End time (in milliseconds) until which the metric data is returned.	If time-range-type is BEFORE_TIME or BETWEEN_TIMES
incident-status	Query	If OPEN, retrieve only the policy violations that are open. If RESOLVED, retrieve only the policy violations that are resolved.	No
output	Query	HTTP Request parameter included as part of the URL to change the output format. Valid values are "XML" (default) or "JSON".	No

Example - Retrieve the list of all open policy violations in the ACME Book Store for the past 1000 minutes.

URI	Sample object output
/controller/rest/applications/2/problems/policy-violations?time-range-type=BEFORE_NOW&duration-in-mins=1000&incident-status=OPEN	XML
/controller/rest/applications/2/problems/policy-violations?time-range-type=BEFORE_NOW&duration-in-mins=1000&incident-status=OPEN&output=JSON	JSON

Retrieve the controller audit history for a time range

New in 4.1.7 Query time range cannot exceed 24 hours

URI: /controller/ ControllerAuditHistory?startTime=<start-time>&endTime=<end-time>

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
start-time	Query	Start time in the format: "yyyy-MM-dd'T'HH:mm:ss.SSSZ"	Yes
end-time	Query	End time in the format: "yyyy-MM-dd'T'HH:mm:ss.SSSZ"	Yes
time-zone-id	Query	Time zone	No

To control the size of the output, the range between the start-time and end-time cannot exceed twenty-four hours. For periods longer than a day, use multiple queries with consecutive time parameters.

This API produces the same information that is found in the audit.log. See Controller Logs

Example - Retrieve the controller audit logs

URI	Sample object output
controller/ControllerAuditHistory?startTime=2015-11-18T08:50:03.607-0700&endTime=2015-11-18T10:50:03.607-0700&timeZoneId=America%2FSan%20Francisco	JSON