Instana API
The Instana REST API provides programmatic access to the Instana observability platform, enabling integration with monitoring data, events, alerts, and infrastructure configuration.
OpenAPI Specification
openapi: 3.0.1
info:
contact:
email: [email protected]
name: © Instana
url: 'http://instana.com'
termsOfService: 'https://www.instana.com/terms-of-use/'
title: Instana REST API documentation
version: 1.307.1417
x-ibm-ahub-try: true
x-logo:
altText: instana logo
backgroundColor: '#FAFBFC'
url: header-logo.svg
description: "Searching for answers and best pratices? Check our [IBM Instana Community](https://community.ibm.com/community/user/aiops/communities/community-home?CommunityKey=58f324a3-3104-41be-9510-5b7c413cc48f).\n\n<div style=\"background-color:#e6f0ff; padding: 12px; border-left: 6px solid #0052cc; font-size: 14px; display: flex; align-items: center;\">\n <img src=\"https://img.icons8.com/ios-filled/50/0052cc/info.png\" width=\"18\" height=\"18\" style=\"margin-right: 8px;\" alt=\"info icon\"/>\n <span>\n <b>Our API documentation is moving to</b> \n <a href=\"https://developer.ibm.com/apis/catalog/instana--instana-rest-api/Introduction\" target=\"_blank\">API Hub</a>\n\t — please update your bookmarks now, as the current site will be deprecated after Release-306.\n </span>\n</div>\n\n## Overview\nThe Instana REST API provides programmatic access to the Instana platform. It can be used to retrieve data available through the Instana UI Dashboard -- metrics, events, traces, etc -- and also to automate configuration tasks such as user management.\n\n### Navigating the API documentation\nThe API endpoints are grouped by product area and functionality. This generally maps to how our UI Dashboard is organized, hopefully making it easier to locate which endpoints you'd use to fetch the data you see visualized in our UI. The [UI sections](https://www.ibm.com/docs/en/instana-observability/current?topic=working-user-interface#navigation-menu) include:\n- Websites & Mobile Apps\n- Applications\n- Infrastructure\n- Synthetic Monitoring\n- Events\n- Automation\n- Service Levels\n- Settings\n- etc\n\n### Rate Limiting\nA rate limit is applied to API usage. Up to 5,000 calls per hour can be made. How many remaining calls can be made and when this call limit resets, can inspected via three headers that are part of the responses of the API server.\n\n- **X-RateLimit-Limit:** Shows the maximum number of calls that may be executed per hour.\n- **X-RateLimit-Remaining:** How many calls may still be executed within the current hour.\n- **X-RateLimit-Reset:** Time when the remaining calls will be reset to the limit. For compatibility reasons with other rate limited APIs, this date is not the date in milliseconds, but instead in seconds since 1970-01-01T00:00:00+00:00.\n\n### Further Reading\nWe provide additional documentation for our REST API in our [product documentation](https://www.ibm.com/docs/en/instana-observability/current?topic=apis-web-rest-api). Here you'll also find some common queries for retrieving data and configuring Instana.\n\n## Getting Started with the REST API\n\n### API base URL\nThe base URL for an specific instance of Instana can be determined using the tenant and unit information.\n- `base`: This is the base URL of a tenant unit, e.g. `https://test-example.instana.io`. This is the same URL that is used to access the Instana user interface.\n- `apiToken`: Requests against the Instana API require valid API tokens. An initial API token can be generated via the Instana user interface. Any additional API tokens can be generated via the API itself.\n\n### Curl Example\nHere is an Example to use the REST API with Curl. First lets get all the available metrics with possible aggregations with a GET call.\n\n```bash\ncurl --request GET \\\n --url https://test-instana.instana.io/api/application-monitoring/catalog/metrics \\\n --header 'authorization: apiToken xxxxxxxxxxxxxxxx'\n```\n\nNext we can get every call grouped by the endpoint name that has an error count greater then zero. As a metric we could get the mean error rate for example.\n\n```bash\ncurl --request POST \\\n --url https://test-instana.instana.io/api/application-monitoring/analyze/call-groups \\\n --header 'authorization: apiToken xxxxxxxxxxxxxxxx' \\\n --header 'content-type: application/json' \\\n --data '{\n \"group\":{\n \"groupbyTag\":\"endpoint.name\"\n },\n \"tagFilters\":[\n \t{\n \t\t\"name\":\"call.error.count\",\n \t\t\"value\":\"0\",\n \t\t\"operator\":\"GREATER_THAN\"\n \t}\n ],\n \"metrics\":[\n \t{\n \t\t\"metric\":\"errors\",\n \t\t\"aggregation\":\"MEAN\"\n \t}\n ]\n }'\n```\n\n### Generating REST API clients\n\nThe API is specified using the [OpenAPI v3](https://github.com/OAI/OpenAPI-Specification) (previously known as Swagger) format.\nYou can download the current specification at our [GitHub API documentation](https://instana.github.io/openapi/openapi.yaml).\n\nOpenAPI tries to solve the issue of ever-evolving APIs and clients lagging behind. Please make sure that you always use the latest version of the generator, as a number of improvements are regularly made.\nTo generate a client library for your language, you can use the [OpenAPI client generators](https://github.com/OpenAPITools/openapi-generator).\n\n#### Go\nFor example, to generate a client library for Go to interact with our backend, you can use the following script; mind replacing the values of the `UNIT_NAME` and `TENANT_NAME` environment variables using those for your tenant unit:\n\n```bash\n#!/bin/bash\n\n### This script assumes you have the `java` and `wget` commands on the path\n\nexport UNIT_NAME='myunit' # for example: prod\nexport TENANT_NAME='mytenant' # for example: awesomecompany\n\n//Download the generator to your current working directory:\nwget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/4.3.1/openapi-generator-cli-4.3.1.jar -O openapi-generator-cli.jar --server-variables \"tenant=${TENANT_NAME},unit=${UNIT_NAME}\"\n\n//generate a client library that you can vendor into your repository\njava -jar openapi-generator-cli.jar generate -i https://instana.github.io/openapi/openapi.yaml -g go \\\n -o pkg/instana/openapi \\\n --skip-validate-spec\n\n//(optional) format the Go code according to the Go code standard\ngofmt -s -w pkg/instana/openapi\n```\n\nThe generated clients contain comprehensive READMEs, and you can start right away using the client from the example above:\n\n```go\nimport instana \"./pkg/instana/openapi\"\n\n// readTags will read all available application monitoring tags along with their type and category\nfunc readTags() {\n\tconfiguration := instana.NewConfiguration()\n\tconfiguration.Host = \"tenant-unit.instana.io\"\n\tconfiguration.BasePath = \"https://tenant-unit.instana.io\"\n\n\tclient := instana.NewAPIClient(configuration)\n\tauth := context.WithValue(context.Background(), instana.ContextAPIKey, instana.APIKey{\n\t\tKey: apiKey,\n\t\tPrefix: \"apiToken\",\n\t})\n\n\ttags, _, err := client.ApplicationCatalogApi.GetApplicationTagCatalog(auth)\n\tif err != nil {\n\t\tfmt.Fatalf(\"Error calling the API, aborting.\")\n\t}\n\n\tfor _, tag := range tags {\n\t\tfmt.Printf(\"%s (%s): %s\\n\", tag.Category, tag.Type, tag.Name)\n\t}\n}\n```\n\n#### Java\nFollow the instructions provided in the official documentation from [OpenAPI Tools](https://github.com/OpenAPITools) to download the [openapi-generator-cli.jar](https://github.com/OpenAPITools/openapi-generator?tab=readme-ov-file#13---download-jar).\n\nDepending on your environment, use one of the following java http client implementations which will create a valid client for our OpenAPI specification:\n```\n//Nativ Java HTTP Client\njava -jar openapi-generator-cli.jar generate -i https://instana.github.io/openapi/openapi.yaml -g java -o pkg/instana/openapi --skip-validate-spec -p dateLibrary=java8 --library native\n\n//Spring WebClient\njava -jar openapi-generator-cli.jar generate -i https://instana.github.io/openapi/openapi.yaml -g java -o pkg/instana/openapi --skip-validate-spec -p dateLibrary=java8,hideGenerationTimestamp=true --library webclient\n\n//Spring RestTemplate\njava -jar openapi-generator-cli.jar generate -i https://instana.github.io/openapi/openapi.yaml -g java -o pkg/instana/openapi --skip-validate-spec -p dateLibrary=java8,hideGenerationTimestamp=true --library resttemplate\n\n```\n"
servers:
- description: Instana Backend
url: 'https://{unit}-{tenant}.instana.io'
variables:
tenant:
default: tenant
description: Customer tenant unit
unit:
default: unit
description: Customer tenant name
- description: Instana Self-Hosted Backend
url: 'https://{domain}'
variables:
domain:
default: example.com
description: Customer Self-Hosted domain
tags:
- name: Infrastructure Analyze
description: |-
This endpoint group exposes the functions that are used by the Instana **Analyze Infrastructure** dashboards.
Two of the endpoints provide a [list of entity types](#operation/getAvailablePlugins) and [metrics for an entity type](#operation/getAvailableMetrics).
It is also possible to [search and filter entities](#operation/getEntities) and [aggregate metrics on similar entities](#operation/getEntityGroups).
## Important notes
### Prerequisites
For self-hosted installations, BeeInstana is required for this endpoint group.
See this [documentation for enabling BeeInstana](https://www.ibm.com/docs/en/instana-observability/current?topic=premises-installing-instana-backend-docker#beeinstana-metric-pipeline-beta).
### Timeframe
**timeFrame** As in the Instana dashboards, you can specify the timeframe for metrics retrieval.
```
windowSize to
(ms) (unix-timestamp)
<----------------------|
```
The timeFrame might be adjusted to fit the metric granularity so that there is no partial bucket. For example, if the query timeFrame is 08:02 - 09:02 and the metric granularity is 5 minutes, the timeFrame will be adjusted to 08:05 - 09:00. The adjusted timeFrame will be returned in the response payload. If the query does not have any metric with specified granularity, a default granularity will be used for adjustment.
### Metrics
**metric** refers to the metric name. Query the [list of available metrics](#operation/getAvailableMetrics) for existing metrics on an entity type.
This is to be used when requesting metrics or when ordering by a metric. For **order.by**, `label` may also be used.
### Filtering
As in the Instana dashboards, you can **filter by a tag**. Query the [infrastructure tag catalog](#operation/getInfrastructureCatalogMetrics) to retrieve a list of available tags.
- name: Infrastructure Metrics
description: "This endpoint retrieves the metrics for infrastructure components.\r\n\r\n### Mandatory Parameters\r\n**plugin:** Plugins are entities' for which we collect metrics, for example : \"Host\", \"Cassandra node\", \"Cassandra Connection\".\r\n\r\nThe available plugins are depending on the system you are monitoring. Therefore you will need to [retrieve plugins](#operation/getInfrastructureCatalogPlugins) where we have data for you.\r\n\r\n**query or snapshotIds:** choose between dynamic focus query or [snapshotId](#operation/getSnapshots) (a unique identifier the metrics are assigned to)\r\n\r\nTo make the it easy to get started this endpoint has two modes that can be used for metrics retrieval:\r\n1. Search metrics with a query\r\n You are using the [Dynamic Focus](https://www.ibm.com/docs/en/instana-observability/current?topic=instana-filtering-dynamic-focus) query to filter the result.\r\n To get usable search parameters you can either query the search [catalog endpoint](#operation/getInfrastructureCatalogSearchFields) or use the UI\r\n\r\n1. Search for metrics for snapshotIds\r\n For advanced use cases, pagination for example, its recommended to use fixed snapshotIds.\r\n\r\n**metrics:** Id of the exact metric you want to retrieve, eg. \"cpu.user\", \"clientrequests.read.mean\"\r\n\r\nOnce you have selected the plugin you can define up to five metrics you want to retrieve with the call.\r\nPlease use our [metrics catalog call](#operation/getInfrastructureCatalogMetrics) to get the available metrics for the selected plugin.\r\n\r\n### Optional Parameters\r\n**timeFrame** As in our UI you can specify the timeframe for metrics retrieval.\r\n```\r\n windowSize to\r\n (ms) (unix-timestamp)\r\n<----------------------|\r\n```\r\n\r\n**rollup:** Depending on the selected timeFrame its possible to selected the rollup.\r\n\r\nThe available rollup is depending on two factors:\r\n1. [Retention times](https://www.ibm.com/docs/en/instana-observability/current?topic=policies#data-retention-policy)\r\n\r\n\tFor example if you select a to timestamp that is 3 Weeks in the past the most accurate rollup you can query for would be 1min\r\n1. Size of the selected windowSize\r\n\r\n\tThe limitation is that we only return 600 Data points per call, thus if you select a windowSize of 1hour the most accurate rollup you can query for would be 5s\r\n\r\nValid rollups are:\r\n\r\n| rollup | value |\r\n| ------------- | ------------- |\r\n| 1 second | 1 |\r\n| 5 seconds | 5 |\r\n| 1 minute | 60 |\r\n| 5 minutes | 300 |\r\n| 1 hour | 3600 |\r\n\r\n\r\n### Defaults\r\n**timeframe:**\r\n```\r\n\"timeFrame\": {\r\n\t\"windowSize\": 60000,\r\n\t\"to\": {current timestamp}\r\n}\r\n```\r\n\r\n**rollup**: 1\r\n\r\n### Limits\r\n1000 Calls per Hour\r\n\r\nTo keep the response size reasonable the limit is set to 30 retrieved items. To implement pagination see [1]\r\n\r\nA maximum of 600 data points are returned per metric.\r\n\r\nYou can only retrieve metrics [above](https://docs.instana.io/core_concepts/dynamic_graph/) the selected Dynamic Focus filter. Work around can be found under [2]\r\n\r\nThe following example will return an empty result, because the selected plugin \"host\" is below the dynamic focus filter \"java\" :\r\n```\r\nquery=entity.selfType:java\r\nplugin=host\r\nmetric=cpu.steal\r\n```\r\n### Tips\r\n[1] **Pagination**\r\nSometimes the query you are interested in returns more than 30 items, you have to use the [find snapshots](#operation/getSnapshots) endpoint to get a full list of Ids for your query and then use the [metrics endpoint](#operation/getInfrastructureMetrics) with the returned snapshotIds\r\n\r\n\r\n[2] **Application filter**\r\nYou can work around the aforementioned limitation by querying one of the crosscutting entities like applications, services and endpoints. For the example above you could create an Application with jvm.version isPresent filter. And search Query then for the created application name\r\n```\r\nquery=entity.application.name:\"Java Applications\"\r\n```\r\n"
- name: Infrastructure Resources
- name: Infrastructure Catalog
description: |
The endpoints of this group retrieve all available resources to query infrastructure metrics.
- name: Infrastructure Topology
- name: Logging Analyze
- name: Application Metrics
description: "The endpoints of this group retrieve the metrics for defined applications, discovered services and endpoints.\r\n### Mandatory Parameters\r\n\r\n**metrics** A list of metric objects that define which metric should be returned, with the defined aggregation. Each metrics objects consists of minimum two items:\r\n1. *metric* select a particular metric to get a list of available metrics query the [catalog endpoint](#operation/getApplicationCatalogMetrics).\r\n2. *aggregation* depending on the selected metric different aggregations are available e.g. SUM, MEAN, P95. The aforementioned [catalog endpoint](#operation/getApplicationCatalogMetrics) gives you the metrics with the available aggregations.\r\n\r\n**Note**: The above mentioned list of available metrics with its supported metrics can also be found in the section **Supported Aggregation on Application metrics** below.\r\n\r\n### Optional Parameters\r\n\r\n**metrics** Default you will get an aggregated metric with for the selected timeframe \r\n\r\n* *granularity* \r\n * If it is not set you will get a an aggregated value for the selected timeframe\r\n * If the granularity is set you will get data points with the specified granularity **in seconds**\r\n * The granularity should not be greater than the `windowSize` (important: `windowSize` is expressed in **milliseconds**)\r\n * The granularity should not be set too small relative to the `windowSize` to avoid creating an excessively large number of data points (max 600)\r\n \r\n**pagination** if you use pagination you most probably want to fix the timeFrame for the retrieved metrics\r\n1. *page* select the page number you want to retrieve\r\n2. *pageSize* set the number of applications you want to return with one query\r\n\r\n**order** You can order the returned items alphanumerical by label, either ascending or descending\r\n1. *by* if the granularity is set to 1 you can use the metric name eg. \"latency.p95\" to order by that value\r\n1. *direction* either ascending or descending\r\n\r\n**timeFrame** As in our UI you can specify the timeframe for metrics retrieval.\r\n```\r\n windowSize to\r\n (ms) (unix-timestamp)\r\n<----------------------|\r\n```\r\n\r\nThe timeFrame might be adjusted to fit the metric granularity so that there is no partial bucket. For example, if the query timeFrame is 08:02 - 09:02 and the metric granularity is 5 minutes, the timeFrame will be adjusted to 08:05 - 09:00. The adjusted timeFrame will be returned in the response payload. If the query does not have any metric with granularity, a default granularity will be used for adjustment.\r\n\r\nTo narrow down the result set you have four options to search for an application.\r\n\r\n**nameFilter | applicationId | serviceId | endpointId**\r\n\r\n* *nameFilter:* filter by name with \"contains\" semantic.\r\n\r\n* *applicationId:* search directly for an application by applicationId \r\n\r\n* *serviceId:* search for applications that include a particular service by serviceId\r\n\r\n* *endpointId:* search for applications that include a particular endpoint by endpointId\r\n\r\n### Defaults\r\n\r\n**metrics**\r\n* *granularity:* 1\r\n\r\n**order**\r\n* by application label ascending.\r\n\r\n**timeFrame**\r\n```\r\n\"timeFrame\": {\r\n\t\"windowSize\": 60000,\r\n\t\"to\": {current timestamp}\r\n}\r\n```\r\n**nameFilter | applicationId | serviceId | endpointId**\r\n* no filters are applied in the default call\r\n\r\n\r\n## Supported Aggregation on Application Metrics\r\n\r\n| Metric | Description | Allowed Aggregations |\r\n|------------------|--------------------------------------------------------------------------------------------|----------------------|\r\n| `calls` | Number of received calls | `PER_SECOND`, `SUM` |\r\n| `erroneousCalls` | The number of erroneous calls |`PER_SECOND`, `SUM` |\r\n| `latency` | Latency of received calls in milliseconds | `P25`, `P50`, `P75`, `P90`, `P95`, `P98`, `P99`, `SUM`, `MEAN`, `MAX`, `MIN` |\r\n| `errors` | Error rate of received calls. A value between 0 and 1 | `MEAN` |\r\n| `applications` | The number of Application Perspectives |`DISTINCT_COUNT` |\r\n| `services` | The number of Services |`DISTINCT_COUNT` |\r\n| `endpoints` | The number of Endpoints |`DISTINCT_COUNT` |\r\n| `http.1xx` | Counts the number of occurrences of HTTP status codes where 100 <= status code <= 199 |`PER_SECOND`, `SUM` |\r\n| `http.2xx` | Counts the number of occurrences of HTTP status codes where 200 <= status code <= 299 |`PER_SECOND`, `SUM` |\r\n| `http.3xx` | Counts the number of occurrences of HTTP status codes where 300 <= status code <= 399 |`PER_SECOND`, `SUM` |\r\n| `http.4xx` | Counts the number of occurrences of HTTP status codes where 400 <= status code <= 499 |`PER_SECOND`, `SUM` |\r\n| `http.5xx` | Counts the number of occurrences of HTTP status codes where 500 <= status code <= 599 |`PER_SECOND`, `SUM` |\r\n"
- name: Application Catalog
description: |-
The endpoints of this group retrieve all available resources to query application metrics. It includes:
**Catalog for Application Tags**
Showing a list of tags which is used for building a query in various use cases within Instana, for example, subset of tags which are available for grouping in traces in Unbounded Analytics for Traces.
**Catalog for metrics**
Showing a list of metrics that are available for aggregations. For example, Call count can have 2 types of aggrgations: sum and per second.
- name: Application Resources
description: |-
The API endpoints of this group provides insights into resources created and discovered. It includes:
**Application Perspectives**
Returns a list of predefined application perspectives, offering an organized view of application perspectives within the system.
**Discovered Services Inside Application Perspectives**
Fetches services identified within the context of specific application perspectives.
**Discovered Services and Endpoints**
Provides a detailed list of endpoints associated with services, enabling deeper visibility into service dependencies and interactions.
It also provides a detailed list of services.
These API endpoints collectively serve as a crucial tool for managing and analyzing application-level resource structures.
- name: Application Analyze
description: "The API endpoints of this group expose our analyze functionality.\nIt includes:\n\n**Grouped Metrics**\n\nTwo group endpoints to retrieve metrics for traces and calls. \n\n**List of traces and its detailed information**\n\nYou can also [search and filter all traces](#operation/getTraces) and retrieve [all details](#operation/getTraceDownload) attached to the trace. Furthermore, you can also retrive [all details](#operation/getCallDetails) of a call.\n\n## Parameters\n### Mandatory Parameters (only for group Endpoints):\n**group** It is mandatory to select a tag by which the calls and traces are grouped for the distinct endpoint call\n* *groupByTag* select a tag by which the calls and traces are grouped \n * a full list of available tags can be retrieved from the [application tag catalog](#operation/getApplicationTagCatalog)\n * for the trace endpoint only two tags are reasonable and working: `trace.endpoint.name` and `trace.service.name` which indicate the entry endpoint or service for the trace\n* *groupByTagSecondLevelKey* tags of type KEY_VALUE_PAIR need a second parameter e.g for `kubernetes.deployment.label` you would need provide the label you want to groupBy here.\n\n### Optional Parameters\n**pagination**\n* *offset* set the starting point for the data retrieval\n* *retrievalSize* you set the number of returned values\n* *ingestionTime* if you want to paginate through your result set you are interested in having the data for a fixed time point, the results set has a `cursor` class that has a ingestionTime property that indicates what you have to enter here.\n**order**\n\n**timeFrame** As in our UI you can specify the timeframe for metrics retrieval.\n```\n windowSize to\n (ms) (unix-timestamp)\n<----------------------|\n```\nThe timeFrame might be adjusted to fit the metric granularity so that there is no partial bucket. For example, if the query timeFrame is 08:02 - 09:02 and the metric granularity is 5 minutes, the timeFrame will be adjusted to 08:05 - 09:00. The adjusted timeFrame will be returned in the response payload. If the query does not have any metric with granularity, a default granularity will be used for adjustment.\n\n**tagFilters** As in the UI you able to filter your query by a tag. To get a list of all available tags you can query the [application tag catalog](#operation/getApplicationTagCatalog)\n* *name* The name of the tag as returned by the catalog\n* *value* The filter value of the tag, possible types are:\n * \"STRING\" alphanumerical values, valid operators: \"EQUALS\", \"CONTAINS\", \"NOT_EQUAL\", \"NOT_CONTAIN\", \"NOT_EMPTY\", \"IS_EMPTY\"\n * \"NUMBER\" numerical values, valid operators: \"EQUALS\", \"LESS_THAN\" \"GREATER_THAN\"\n * \"KEY_VALUE_PAIR\" \n* *operator* one of the valid operators for the type of the selected tag\n\n**metrics** A list of metric objects that define which metric should be returned, with the defined aggregation. Each metrics objects consists of minimum two items:\n1. *metric* select a particular metric, available metrics in this context are\n * Latency Mean\n * Error Rate\n * Traces Sum\n2. *aggregation* depending on the selected metric different aggregations are available e.g. SUM, MEAN, P95. The aforementioned [catalog endpoint](#operation/getApplicationCatalogMetrics) gives you the metrics with the available aggregations.\n\n**Note**: The above mentioned list of available metrics with its supported metrics can also be found in [Get grouped call metrics](#operation/getCallGroup) and [Get grouped trace metrics](#operation/getTraceGroups).\n\n3. *granularity* \n * If it is not set you will get a an aggregated value for the selected timeframe\n * If the granularity is set you will get data points with the specified granularity **in seconds**\n * The granularity should not be greater than the `windowSize` (important: `windowSize` is expressed in **milliseconds**)\n * The granularity should not be set too small relative to the `windowSize` to avoid creating an excessively large number of data points (max 600)\n\n### Defaults:\n**timeFrame**\n```\n\"timeFrame\": {\n\t\"windowSize\": 60000,\n\t\"to\": {current timestamp}\n}\n```\n"
- name: Application Settings
description: |-
The API endpoints of this group provides a way to create, read, update, delete (CRUD) for various configuration settings. It includes:
**Application Perspectives Configuration**
Set of APIs which perform CRUD operations for Application Perspectives.
**Endpoint Mapping Configuration**
Set of APIs which perform CRUD operations when user wants to customise the endpoint mapping rules.
**Service Mapping Configuration**
Set of APIs which perform CRUD operations when user wants to customise the service mapping rules.
**Manual Service Mapping Configuration**
Set of **experimental** APIS which perform CRUD operations when user wants to tweak the service mapping rules when automatic service mapping rules gives undesired results.
- name: Application Topology
- name: Website Metrics
- name: Website Catalog
description: |
The endpoints of this group retrieve all available resources to query website metrics.
- name: Website Configuration
- name: Website Analyze
description: "The following four endpoints expose our analyze functionality.\n\n## Mandatory Parameters :\n\n**type** \n\n**group (only for group Endpoints)** It is mandatory to select a tag by which the beacons are grouped for the distinct endpoint call\n* *groupByTag* select a tag by which the beacons are grouped \n * a full list of available tags can be retrieved from the [website tag catalog](#operation/getWebsiteCatalogTags)\n* *groupByTagSecondLevelKey* tags of type KEY_VALUE_PAIR need a second parameter e.g for `beacon.meta` you would need provide the label you want to groupBy here.\n\n\n## Optional Parameters:\n\n**pagination**\n* *offset* set the starting point for the data retrieval\n* *retrievalSize* you set the number of returned values\n* *ingestionTime* if you want to paginate through your result set you are interested in having the data for a fixed time point, the results set has a `cursor` class that has a ingestionTime property that indicates what you have to enter here.\n\n**order**\n\n**timeFrame** As in our UI you can specify the timeframe for metrics retrieval.\n```\n windowSize to\n (ms) (unix-timestamp)\n<----------------------|\n```\n\n**tagFilterExpression** As in the UI you are able to filter your query using tags and operators such as `AND` and `OR`. To get a list of all available tags you can query the [tag catalog](#operation/getWebsiteCatalogTags)\n* *name* The name of the tag as returned by the catalog, e.g `beacon.meta`, `beacon.http.path`\n* *value* The filter value of the tag, possible types are:\n * \"STRING\" alphanumerical values, valid operators: \"EQUALS\", \"CONTAINS\", \"NOT_EQUAL\", \"NOT_CONTAIN\", \"NOT_EMPTY\", \"IS_EMPTY\"\n * \"NUMBER\" numerical values, valid operators: \"EQUALS\", \"LESS_THAN\" \"GREATER_THAN\"\n * \"KEY_VALUE_PAIR\" of you are using meta tags `beacon.meta` you can filter for those by setting `yourMetaTagName=foo` in the value field, valid operators: \"EQUALS\", \"CONTAINS\", \"NOT_EQUAL\", \"NOT_CONTAIN\", \"NOT_EMPTY\", \"IS_EMPTY\"\n* *operator* one of the valid operators for the type of the selected tag\n\n**metrics** A list of metric objects that define which metric should be returned, with the defined aggregation. Each metrics objects consists of minimum two items:\n1. *metric* select a particular metric, available metrics in this context are\n * Latency Mean\n * Error Rate\n2. *aggregation* depending on the selected metric different aggregations are available e.g. SUM, MEAN, P95. The aforementioned [catalog endpoint](#operation/getWebsiteCatalogMetrics) gives you the metrics with the available aggregations.\n3. *granularity* \n * If it is not set you will get a an aggregated value for the selected timeframe\n * If the granularity is set you will get data points with the specified granularity **in seconds**\n * The granularity should not be greater than the `windowSize` (important: `windowSize` is expressed in **milliseconds**)\n * The granularity should not be set too small relative to the `windowSize` to avoid creating an excessively large number of data points (max 600)\n \n\n## Defaults:\n\n**timeFrame**\n```\n\"timeFrame\": {\n\t\"windowSize\": 60000,\n\t\"to\": {current timestamp}\n}\n```\n"
- name: Mobile App Metrics
- name: Mobile App Catalog
- name: Mobile App Configuration
- name: Mobile App Analyze
- name: Events
- name: Event Settings
- name: Application Alert Configuration
description: |-
The API endpoints of this group can be used to manage Application alert configurations.
## Parameters:
- **id:** ID of the application alert config which needs to be updated.
- **name:** Name for the application alert configuration.
- **description:** Description for the application alert configuration.
- **severity:** The severity of the alert when triggered, which is either `5` (Warning), or `10` (Critical).
- **triggering:** Optional flag to indicate whether also an Incident is triggered or not.
- **applications:** Selection of application, services and endpoints in scope.
The selection defines a tree of included or excluded sub entities. The defined `inclusive` flag defines whether this node and his child nodes are included (`inclusive: true`) or excluded (`inclusive: false`) by default. Empty selections or unnecessary selections are not allowed.
#### Example 1: Select an entire Application Perspective
To select the entire application with ID `<appId>` including all its services and endpoints, simply provide the following selection object:
```json
"applications": {
"<appId>": {
"applicationId": "<appId>"
}
}
```
Leaf nodes of the selection tree default to `true` if no `inclusive` value is defined.
#### Example 2: Specific selection of services and endpoints
To select not the entire application with ID `<appId>`, but only the entire serivces Service1 with ID `<service1>` and Service2 with ID `<service2>`, with the exception of endpoint `<endpoint2>` of Service2. And in addition, only Endpoint `<endpoint3>` of Service3 with id `<service3>`, the
# --- truncated at 32 KB (1443 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/instana/refs/heads/main/openapi/instana-openapi.yml