Service level objectives API

The Instana API is specified using the OpenAPI v3 format. For more information about the current specification, see GitHub API documentation.

You can use the Instana API to retrieve and configure key data points. Among other things, this API enables automatic reaction to SLO changes, further analysis of identified incidents, and reporting capabilities.

Authentication and authorization

Using API key

The Instana API authenticates requests by using an API key in the HTTP Authorization request header.

Example: The following example uses the REST API with curl to retrieve all the available metrics with possible aggregations with a GET call.

curl --request GET \
  --url https://instana.rocks/api/application-monitoring/catalog/metrics \
  --header 'authorization: apiToken xxxxxxxxxxxxxxxx'

How to obtain an API key

Complete the following steps to obtain an API key:

  1. Sign in to Instana UI
  2. From the navigation sidebar, go to the Settings > Security & Access tab. Under Access Control, select API Tokens, and then click New API Token.
  3. Complete the required fields and enable the required permissions.
  4. Click Save.

The “Configuration of service level indicators” permission is required to be authorized for SLO API access.

Using Instana web session cookies

You can access all Instana APIs directly from a web browser after you have signed in to the Instana UI. Entering the endpoint URL in the browser address field and then press Enter, A GET request is sent to the Instana backend with the existing signed-in user session cookies.

Limitation: Since only GET request can be sent directly from the browser, all other HTTP methods are not feasible unless the browser integrates with other third-party extensions.

SLO APIs permission requirement

In order to access any SLO API using API token, the permission of Configuration of service level indicators is required to the related API token.

SLO configuration APIs

The SLO configuration API is to manage SLO configurations. SLO configuration payload is the description of Instana SLO entity. Instana processes these configurations to generate various metrics and reports after they are created. These configurations can be updated and deleted by this API. After the configuration is deleted, Instana does not process it anymore, and any related SLO artifacts are not accessible. The behavior of the Instana API and web interface is synchronized.

SLO configuration payload, actions and endpoint

The payload represents the JSON body content for the SLO configuration object. The GET/POST/DELETE/PUT actions are to used to fetch, create, remove and update the SLO configuration. Detailed information on those elememts and interactions are documented in the Service Levels Objective(SLO) Configurations API doc.

Examples of SLO configurations

Example 1: Application time-based latency

The following SLO targets a service quality of 96.3818% indicated by the mean latency under 341 ms. The error budget is calculated in minutes over a rolling time window of 7 days. It is being measured from the backend application point of view.

Payload:

{
  "name": "Cupcake Vending Machine performance aggregation over time",
  "target": 0.963818,
  "lastUpdated": 1690357470848,
  "entity": {
    "type": "application",
    "applicationId": "LsEOORPeR0Gnt_kntZbosw",
    "serviceId": null,
    "endpointId": null,
    "boundaryScope": "ALL",
    "includeInternal": false,
    "includeSynthetic": false,
    "tagFilterExpression": null
  },
  "indicator": {
    "type": "timeBased",
    "blueprint": "latency",
    "threshold": 341,
    "aggregation": "MEAN"
  },
  "timeWindow": {
    "type": "rolling",
    "duration": 7,
    "durationUnit": "day"
  },
  "tags": [
    "food",
    "snacks",
    "timeBased",
    "latency",
    "demo"
  ]
}
Example 2: Website event-based availability

The following SLO targets a service quality of 71.38% indicated by the ratio of successful vs erroneous HTTP request beacons. The error budget is calculated in individual events over a rolling time window of 7 days. It is measured from the user point of view.

Payload:

{
  "name": "Cupcake Shop reliability by event count",
  "target": 0.7138,
  "lastUpdated": 1690357470042,
  "entity": {
    "type": "website",
    "websiteId": "h_TxI-AGSZqVd5tVKjDXKw",
    "beaconType": "httpRequest",
    "tagFilterExpression": null
  },
  "indicator": {
    "type": "eventBased",
    "blueprint": "availability",
    "threshold": 0
  },
  "timeWindow": {
    "type": "rolling",
    "duration": 7,
    "durationUnit": "day"
  },
  "tags": [
    "food",
    "snacks",
    "eventBased",
    "availability",
    "demo"
  ]
}

Example 3: Synthetic tests event-based availability

The following SLO targets a service quality of 96.99% based on the ratio of non-erroneous vs erroneous synthetic test results. The error budget is calculated in indivudual events over a rolling time window of 7 days. It is being measured from the backend application point of view.

Payload:

    {
      "name": "Cupcake Shop Synthetic Availability",
      "target": 0.9699,
      "lastUpdated": 1742587582774,
      "entity": {
        "type": "synthetic",
        "syntheticTestIds": [
          "lLW0jCW8mZRmdrEZ1cno"
        ],
        "tagFilterExpression": {
          "type": "EXPRESSION",
          "logicalOperator": "AND",
          "elements": []
        }
      },
      "indicator": {
        "type": "eventBased",
        "threshold": 0,
        "operator": null,
        "aggregation": null,
        "badEventsFilter": {
          "type": "TAG_FILTER",
          "name": "call.erroneous",
          "stringValue": null,
          "numberValue": null,
          "booleanValue": true,
          "floatValue": null,
          "key": null,
          "value": null,
          "operator": "EQUALS",
          "entity": "NOT_APPLICABLE"
        },
        "goodEventsFilter": {
          "type": "TAG_FILTER",
          "name": "call.erroneous",
          "stringValue": null,
          "numberValue": null,
          "booleanValue": false,
          "floatValue": null,
          "key": null,
          "value": null,
          "operator": "EQUALS",
          "entity": "NOT_APPLICABLE"
        },
        "blueprint": "availability"
      },
      "timeWindow": {
        "type": "rolling",
        "duration": 1,
        "durationUnit": "week"
      },
      "tags": []
    }

Example 4: Synthetic tests time-based traffic

The following SLO targets a service quality of 90% based on the the total traffic count of synthetic test results. The error budget is calculated in minutes over a fixed time window of 1 day. It is being measured from the SUM of all traffic in the time window.

Payload:

    {
      "name": "Cupcake Shop Synthetic Traffic",
      "target": 0.9,
      "lastUpdated": 1736873398635,
      "entity": {
        "type": "synthetic",
        "syntheticTestIds": [
          "zOj9zRK2142Fjo6SNc4r",
          "0Ir0TqQzEECdc05jiHHu"
        ],
        "tagFilterExpression": {
          "type": "EXPRESSION",
          "logicalOperator": "AND",
          "elements": []
        }
      },
      "indicator": {
        "threshold": 1,
        "operator": ">=",
        "aggregation": "SUM",
        "trafficType": "all",
        "type": "timeBased",
        "blueprint": "traffic"
      },
      "timeWindow": {
        "type": "fixed",
        "duration": 1,
        "durationUnit": "day",
        "startTimestamp": 1736830800000
      },
      "tags": []
    }

Basic APIs to create/get/update/delete SLO configurations

The following basic APIs can create, get, update and delete SLO configuration without UI interactions. The API document can be found at Instana GitHub.

★ Create an SLO configuration

This API call creates a unique new SLO configuration based on the JSON payload that is included in the command.

curl example:

echo -e ' \
{
  "name": "my SLO no 1",
  "target": 0.96,
  "lastUpdated": 1690357470848,
  "entity": {
    "type": "application",
    "applicationId": "LsEOORPeR0Gnt_kntZbosw",
    "serviceId": null,
    "endpointId": null,
    "boundaryScope": "ALL",
    "includeInternal": false,
    "includeSynthetic": false,
    "tagFilterExpression": null
  },
  "indicator": {
    "type": "timeBased",
    "blueprint": "latency",
    "threshold": 341,
    "aggregation": "MEAN"
  },
  "timeWindow": {
    "type": "rolling",
    "duration": 7,
    "durationUnit": "day"
  },
  "tags": [
    "food",
    "snacks",
    "timeBased",
    "latency",
    "demo"
  ]
}
' | curl -X POST -H "Content-Type: application/json" -H 'authorization: apiToken XXXXXXXXXXXXXX' https://instana.rocks/api/settings/slo -d @-
★ GET SLO configuration BY ID

This API call returns a unique SLO configuration and the key attributes pairs for it. Requires knowledge of the ID attribute for the particular configuration.

curl example:

curl -H 'authorization: apiToken XXXXXXXXXXXXXX' https://instana.rocks/api/settings/slo/SLOsmbQLI8ORcuhF_L-QquFWQ
★ Update existing SLO configuration

Equivalent to UPDATE, it updates only attributes that are permitted to be updated, of an existing SLO configuration. Requires knowledge of the ID attribute for the particular configuration.

The following fields can be updated (all other fields are not allowed):

  • name
  • target
  • timeWindow.type
  • timeWindow.duration
  • timeWindow.durationUnit
  • tags

curl example:

echo -e ' \
{
      "name": "My SLO no1 updated",
      "target": 90.1,
      "entity": {
        "type": "application",
        "applicationId": "6uWKK5izTFqo0bdioIr1PA",
        "serviceId": null,
        "endpointId": null,
        "boundaryScope": "ALL",
        "includeInternal": false,
        "includeSynthetic": false,
        "tagFilterExpression": {
          "type": "EXPRESSION",
          "logicalOperator": "AND",
          "elements": []
        }
      },
      "indicator": {
        "type": "timeBased",
        "threshold": 1234,
        "aggregation": "P95",
        "blueprint": "latency"
      },
      "timeWindow": {
        "type": "fixed",
        "duration": 1,
        "durationType": "day",
        "startTimestamp": 1681311907374
      },
			"tags": ["tagA", "tagB"]
 }
' | curl -X PUT -H "Content-Type: application/json" -H 'authorization: apiToken XXXXXXXXXXXXXX' https://instana.rocks/api/settings/slo/SLOsmbQLI8ORcuhF_L-QquFWQ
★ GET all SLO configurations

This API call returns all the SLO configurations and the key attributes pairs for each.

curl example:

curl -H 'authorization: apiToken XXXXXXXXXXXXXX' https://instana.rocks/api/settings/slo
★ GET SLO configuration TAGS

This API call returns ALL existing SLO configuration TAGS.

curl example:

curl -H 'authorization: apiToken XXXXXXXXXXXXXX' https://instana.rocks/api/settings/slo/tags
★ DELETE SLO configuration

This API call removes an existing SLO configuration that is uniquely identified by its ID.

curl example:

curl -X DELETE -H 'authorization: apiToken XXXXXXXXXXXXXX' https://instana.rocks/api/settings/slo/SLOsmbQLI8ORcuhF_L-QquFWQ

Service Level report API

The Service Levels Objective(SLO) Report REST API returns all metrics and charts in one single response according to the provided configuration ID and time window.

The following is an example of using the SLO report API to fetch a report between 20225-03-31 13:00 to 16:00:

curl example:

curl -H 'authorization: apiToken XXXXXXXXXXXXXX' https://instana.rocks/api/slo/report/SLO99DvvwekR3G0VDw-1m2KtA?to=1743451200000&from=1743444000000

Example response:

{
  "sli": 0.9895833333333334,
  "slo": 0.99,
  "totalErrorBudget": 14,
  "errorBudgetRemaining": -1,
  "errorBudgetSpent": 15,
  "errorBurnRate": 1,
  "fromTimestamp": 1743444000000,
  "toTimestamp": 1743451200000,
  "violationDistribution": {
    "0": 1,
    "1": 1,
    "2": 1
  },
  "errorChart": {
    "0": 0,
    "1": 0,
    "2": 0
  },
  "errorAccumulationChart": {
    "0": 7,
    "1": 7,
    "2": 7
  },
  "errorBudgetRemainChart": {
    "0": 7,
    "1": 7,
    "2": 7
  },
  "errorBurnRateChart": {
    "0": 0,
    "1": 0,
    "2": 0
  }
}
}

SLO smart alerts API

SLO smart alerts can be managed by Service Levels Alert Configuration APIs. Similar to other smart alert APIs, this collection of APIs can read, create, update, delete, enable, disable, version and revise SLO alerts.

Here is an example of creating a SLO error budget burn smart alert:

  • Request:
echo -e ' \
{
  "alertChannelIds": [],
  "customPayloadFields": [],
  "description": "Consumed >= 80% of the error budget.",
  "name": "Remaining error budget is low",
  "rule": {
    "alertType": "ERROR_BUDGET",
    "metric": "BURNED_PERCENTAGE"
  },
  "severity": 5,
  "sloIds": [
    "SLO2XfFi3h7TiWk56MRbyiAOA",
    "SLOlVgz62GhQO6x0I-qUJnwZg"
  ],
  "threshold": {
    "type": "staticThreshold",
    "value": 0.8,
    "operator": ">=",
    "lastUpdated": 1743534460472
  },
  "timeThreshold": {
    "expiry": 300000,
    "timeWindow": 900000
  },
  "triggering": true
}
' | curl -X PUT -H "Content-Type: application/json" -H 'authorization: apiToken XXXXXXXXXXXXXX' https://instana.rocks/api/events/settings/global-alert-configs/service-levels
  • Response:
{
    "name": "Remaining error budget is low",
    "description": "Consumed >= 80% of the error budget.",
    "severity": 5,
    "burnRateTimeWindows": null,
    "triggering": true,
    "rule": {
        "alertType": "ERROR_BUDGET",
        "metric": "BURNED_PERCENTAGE"
    },
    "threshold": {
        "type": "staticThreshold",
        "operator": ">=",
        "value": 0.8,
        "lastUpdated": 1743534460472
    },
    "sloIds": [
        "SLO2XfFi3h7TiWk56MRbyiAOA",
        "SLOlVgz62GhQO6x0I-qUJnwZg"
    ],
    "alertChannelIds": [],
    "timeThreshold": {
        "expiry": 300000,
        "timeWindow": 900000
    },
    "customPayloadFields": [],
    "id": "o-xuzP6yT1u5UZNthAx6Rg",
    "created": 1743534461234,
    "initialCreated": 1743534461234,
    "readOnly": false,
    "enabled": true
}

Legacy and Lite SLO API

Manage Legacy and Lite SLIs through API

Legacy and Lite SLOs were implemented differently from the preceding SLO. The SLI(Service level indicator) is the essential configuration. The service level objective is part of the custom dashboard setting to display service level outcomes according to the business requirements.

  • SLI Configuration API provides endpoints to create, read, update, and delete Service level indicator (SLI) configurations for the legacy and Lite SLIs configurations.
  • Custom dashboard API are used to manage custom dashboard and SLO widgets.

As an example, the following curl command can be used to create a time-based SLI named My First SLI for an application with the ID appId that has a service with the ID serviceId and is limited to calls where the endpoint-id equals endpointId. The SLI is aggregated for the 90th percentile of the latency metric and a threshold value of 25 ms.

curl --location --request POST "{{base}}/api/settings/v2/sli" \
  --header "Authorization: apiToken {{apiToken}}" \
  --header "Content-Type: application/json" \
  --data '{
    "sliName": "My first SLI",
    "metricConfiguration": {
        "metricName": "latency",
        "metricAggregation": "P90",
        "threshold": 25
    },
    "sliEntity": {
        "sliType": "application",
        "applicationId": "appId",
        "serviceId": "serviceId",
        "endpointId": "endpointId",
        "boundaryScope": "ALL"
    }
  }'

Legacy and Lite SLI reports API

Similar to the SLO report API, SLI Report can be invoked to return Legacy and Lite SLI reports. Different from the SLO report API, the SLO target need to be provided in the request.

Here is an example:

  • Request
https://instana.rocks/api/sli/report/Ca_h3OGvT3iu5Kt6LVsJ7g?slo=0.9&to=1743451200000&from=1743444000000
  • Response
{
  "sli": 0.9166666666666666,
  "slo": 0.9,
  "totalErrorBudget": 12,
  "errorBudgetRemaining": 2,
  "fromTimestamp": 1743444000000,
  "toTimestamp": 1743451200000,
  "violationDistribution": {
    "0": 1,
    "1": 1,
    "2": 1,
    "3": 1,
    "4": 1,
    "5": 1,
    "6": 1,
 ... ...
    "99": 1,
    "100": 0
  }
}