Instana Business Monitoring API
The Business Monitoring API from Instana — 5 operation(s) for business monitoring.
OpenAPI Specification
openapi: 3.0.1
info:
contact:
email: support@instana.com
name: © Instana
url: http://instana.com
termsOfService: https://www.instana.com/terms-of-use/
title: Instana REST API documentation Business Monitoring API
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: Business Monitoring
paths:
/api/business-monitoring/activities:
post:
operationId: getActivities
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GetActivities'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CursorPaginatedBusinessActivityItem'
description: OK
security:
- ApiKeyAuth:
- Default
summary: Get Business Activities
tags:
- Business Monitoring
x-ibm-ahub-byok: true
/api/business-monitoring/activities/csv:
post:
operationId: getActivitiesCsv
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GetActivities'
responses:
'200':
content:
text/csv:
schema:
$ref: '#/components/schemas/BusinessActivity'
description: OK
security:
- ApiKeyAuth:
- Default
summary: Download Business Activities
tags:
- Business Monitoring
x-ibm-ahub-byok: true
/api/business-monitoring/business-perspectives:
get:
operationId: getBusinessPerspectives
responses:
'200':
content:
application/json:
example:
- id: gBwNFIbjS6Ozwt0a12regg
label: biz-perspective
name: biz-perspective
description: This is an example business perspective
rbacTags:
- id: 0xHKaxfaS161Al6Qc23g4w
displayName: team 1
tagFilterExpression:
type: EXPRESSION
logicalOperator: AND
elements:
- type: EXPRESSION
logicalOperator: AND
elements:
- type: EXPRESSION
logicalOperator: OR
elements:
- type: TAG_FILTER
name: service.name
stringValue: my-service-1
numberValue: null
booleanValue: null
key: null
value: my-service-1
operator: EQUALS
entity: DESTINATION
- type: TAG_FILTER
name: service.name
stringValue: my-service-2
numberValue: null
booleanValue: null
key: null
value: my-service-2
operator: EQUALS
entity: DESTINATION
schema:
$ref: '#/components/schemas/BusinessPerspectiveConfig'
description: OK
security:
- ApiKeyAuth:
- Default
summary: Get all business perspectives
tags:
- Business Monitoring
x-ibm-ahub-byok: true
post:
operationId: createBusinessPerspective
requestBody:
content:
application/json:
example:
label: biz-perspective
name: biz-perspective
description: This is an example business perspective
rbacTags:
- id: 0xHKaxfaS161Al6Qc23g4w
displayName: team 1
tagFilterExpression:
type: EXPRESSION
logicalOperator: AND
elements:
- type: EXPRESSION
logicalOperator: AND
elements:
- type: EXPRESSION
logicalOperator: OR
elements:
- type: TAG_FILTER
name: service.name
stringValue: my-service-1
numberValue: null
booleanValue: null
key: null
value: my-service-1
operator: EQUALS
entity: DESTINATION
- type: TAG_FILTER
name: service.name
stringValue: my-service-2
numberValue: null
booleanValue: null
key: null
value: my-service-2
operator: EQUALS
entity: DESTINATION
schema:
$ref: '#/components/schemas/NewBusinessPerspectiveConfig'
required: true
responses:
'200':
content:
application/json:
example:
id: gBwNFIbjS6Ozwt0a12regg
label: biz-perspective
name: biz-perspective
description: This is an example business perspective
rbacTags:
- id: 0xHKaxfaS161Al6Qc23g4w
displayName: team 1
tagFilterExpression:
type: EXPRESSION
logicalOperator: AND
elements:
- type: EXPRESSION
logicalOperator: AND
elements:
- type: EXPRESSION
logicalOperator: OR
elements:
- type: TAG_FILTER
name: service.name
stringValue: my-service-1
numberValue: null
booleanValue: null
key: null
value: my-service-1
operator: EQUALS
entity: DESTINATION
- type: TAG_FILTER
name: service.name
stringValue: my-service-2
numberValue: null
booleanValue: null
key: null
value: my-service-2
operator: EQUALS
entity: DESTINATION
schema:
$ref: '#/components/schemas/BusinessPerspectiveConfig'
description: OK
security:
- ApiKeyAuth:
- Default
summary: Create business perspective
tags:
- Business Monitoring
x-ibm-ahub-byok: true
/api/business-monitoring/business-perspectives/{id}:
delete:
operationId: deleteBusinessPerspective
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
default:
content:
application/json: {}
description: default response
security:
- ApiKeyAuth:
- Default
summary: Delete business perspective
tags:
- Business Monitoring
x-ibm-ahub-byok: true
get:
operationId: getBusinessPerspective
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
example:
id: gBwNFIbjS6Ozwt0a12regg
label: biz-perspective
name: biz-perspective
description: This is an example business perspective
rbacTags:
- id: 0xHKaxfaS161Al6Qc23g4w
displayName: team 1
tagFilterExpression:
type: EXPRESSION
logicalOperator: AND
elements:
- type: EXPRESSION
logicalOperator: AND
elements:
- type: EXPRESSION
logicalOperator: OR
elements:
- type: TAG_FILTER
name: service.name
stringValue: my-service-1
numberValue: null
booleanValue: null
key: null
value: my-service-1
operator: EQUALS
entity: DESTINATION
- type: TAG_FILTER
name: service.name
stringValue: my-service-2
numberValue: null
booleanValue: null
key: null
value: my-service-2
operator: EQUALS
entity: DESTINATION
schema:
$ref: '#/components/schemas/BusinessPerspectiveConfig'
description: OK
security:
- ApiKeyAuth:
- Default
summary: Get business perspective
tags:
- Business Monitoring
x-ibm-ahub-byok: true
put:
operationId: updateBusinessPerspective
parameters:
- in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
label: biz-perspective
name: biz-perspective
rbacTags:
- id: 0xHKaxfaS161Al6Qc23g4w
displayName: team 1
tagFilterExpression:
type: EXPRESSION
logicalOperator: AND
elements:
- type: EXPRESSION
logicalOperator: AND
elements:
- type: EXPRESSION
logicalOperator: OR
elements:
- type: TAG_FILTER
name: service.name
stringValue: my-service-1
numberValue: null
booleanValue: null
key: null
value: my-service-1
operator: EQUALS
entity: DESTINATION
- type: TAG_FILTER
name: service.name
stringValue: my-service-2
numberValue: null
booleanValue: null
key: null
value: my-service-2
operator: EQUALS
entity: DESTINATION
schema:
$ref: '#/components/schemas/UpdatedBusinessPerspectiveConfig'
required: true
responses:
'200':
content:
application/json:
example:
id: gBwNFIbjS6Ozwt0a12regg
label: biz-perspective
name: biz-perspective
description: This is an example business perspective
rbacTags:
- id: 0xHKaxfaS161Al6Qc23g4w
displayName: team 1
tagFilterExpression:
type: EXPRESSION
logicalOperator: AND
elements:
- type: EXPRESSION
logicalOperator: AND
elements:
- type: EXPRESSION
logicalOperator: OR
elements:
- type: TAG_FILTER
name: service.name
stringValue: my-service-1
numberValue: null
booleanValue: null
key: null
value: my-service-1
operator: EQUALS
entity: DESTINATION
- type: TAG_FILTER
name: service.name
stringValue: my-service-2
numberValue: null
booleanValue: null
key: null
value: my-service-2
operator: EQUALS
entity: DESTINATION
schema:
$ref: '#/components/schemas/BusinessPerspectiveConfig'
description: OK
security:
- ApiKeyAuth:
- Default
summary: Update business perspective
tags:
- Business Monitoring
x-ibm-ahub-byok: true
/api/business-monitoring/catalog:
get:
operationId: getBusinessTagCatalog
parameters:
- in: query
name: from
schema:
type: integer
format: int64
- in: query
name: useCase
schema:
type: string
enum:
- GROUPING
- FILTERING
- SERVICE_MAPPING
- SMART_ALERTS
- SMART_ALERTS_LOGS
- SMART_ALERTS_ADAPTIVE_BASELINE
- SMART_ALERTS_CUSTOM_PAYLOAD
- SLI_MANAGEMENT
- APPLICATION_CONFIG
- APPLICATION_CONFIG_BLUEPRINT
- MAINTENANCE_WINDOWS
- BIZOPS_CUSTOM_DASHBOARDS_FILTERING
responses:
'200':
content:
application/json:
example:
tagTree:
- label: Region or Environment
description: null
icon: null
children:
- label: Zone
description: null
icon: null
children:
- label: Agent Zone
tagName: agent.zone
type: TAG
- label: Ec2 Zone
tagName: aws.ec2.zone
type: TAG
- label: Azure Zone
tagName: azure.zone
type: TAG
type: LEVEL
queryable: false
- label: Cloud
description: null
icon: null
children:
- label: Aws Arn
tagName: aws.arn
type: TAG
- label: Ec2 Ipv4
tagName: aws.ec2.ipv4
type: TAG
- label: Ec2 PublicName
tagName: aws.ec2.publicName
type: TAG
- label: Ec2 Tag
tagName: aws.ec2.tag
type: TAG
- label: Ec2 Zone
tagName: aws.ec2.zone
type: TAG
- label: Ecs Cluster Name
tagName: aws.ecs.cluster.name
type: TAG
- label: Azure Zone
tagName: azure.zone
type: TAG
- label: Gce Tag
tagName: gce.tag
type: TAG
- label: Gce Zone
tagName: gce.zone
type: TAG
- label: Cloud Provider
tagName: cloud.provider
type: TAG
type: LEVEL
queryable: false
- label: Host
description: null
icon: null
children:
- label: Http Host
tagName: call.http.host
type: TAG
- label: Host Fqdn
tagName: host.fqdn
type: TAG
- label: Host Ip
tagName: host.ip
type: TAG
- label: Host Name
tagName: host.name
type: TAG
- label: Host Zone
tagName: host.zone
type: TAG
- label: Jboss Node Name
tagName: jboss.node.name
type: TAG
- label: Kubernetes Cluster Name
tagName: kubernetes.cluster.name
type: TAG
- label: Kubernetes Node Name
tagName: kubernetes.node.name
type: TAG
type: LEVEL
queryable: false
type: LEVEL
queryable: false
- label: custom
description: null
icon: null
children:
- label: HTTP
description: null
icon: null
children:
- label: Http Header
tagName: call.http.header
type: TAG
- label: Http Params
tagName: call.http.params
type: TAG
- label: Http PathTemplate
tagName: call.http.pathTemplate
type: TAG
type: LEVEL
queryable: false
- label: Miscellaneous
description: null
icon: null
children:
- label: Agent Tag
tagName: agent.tag
type: TAG
- label: Ec2 Tag
tagName: aws.ec2.tag
type: TAG
- label: Call Tag
tagName: call.tag
type: TAG
type: LEVEL
queryable: false
- label: Platform
description: null
icon: null
children:
- label: Docker Label
tagName: docker.label
type: TAG
- label: Kubernetes Label
tagName: kubernetes.label
type: TAG
- label: Kubernetes Deployment Label
tagName: kubernetes.deployment.label
type: TAG
- label: Kubernetes Pod Label
tagName: kubernetes.pod.label
type: TAG
- label: Openshift Deploymentconfig Label
tagName: openshift.deploymentconfig.label
type: TAG
type: LEVEL
queryable: false
type: LEVEL
queryable: false
tags: []
schema:
$ref: '#/components/schemas/TagCatalog'
description: OK
security:
- ApiKeyAuth:
- Default
summary: Get business tag catalog
tags:
- Business Monitoring
x-ibm-ahub-byok: true
components:
schemas:
BusinessActivity:
type: object
properties:
activityId:
type: string
description: Unique identifier for the activity generated by the source BPM tool
example: ApproveInvoiceTask
nullable: true
activityName:
type: string
description: 'Name of the activity '
example: Approve Invoice
nullable: true
activityStart:
type: integer
format: int64
description: Unix timestamp representing the activity's start time
example: 1680559706000
nullable: true
activityType:
type: string
description: 'Type of the activity '
example: userTask
callId:
type: string
writeOnly: true
endpointIds:
type: array
items:
type: string
processDefinitionId:
type: string
description: The identifier of the process the activity is an instance of.
example: invoice:2:aa2bbbcc-bb04-11ee-9d4e-0242ac110002
nullable: true
processDefinitionName:
type: string
description: The name of the process that the activity is an instance of
example: Invoice Approval
nullable: true
rootProcessInstanceId:
type: string
description: The id of the root process for the activity
example: 486cbb3b-e633-11ee-8707-0242ac110002
nullable: true
required:
- activityType
BusinessPerspectiveConfig:
type: object
properties:
description:
type: string
maxLength: 300
minLength: 0
id:
type: string
maxLength: 128
minLength: 1
name:
type: string
maxLength: 100
minLength: 0
tagFilterExpression:
$ref: '#/components/schemas/TagFilterExpressionElement'
required:
- id
TagCatalog:
type: object
properties:
tagTree:
type: array
description: 'The name of the tag dataset (tagTree) which can contain one or more tags as its attributes or children. Eg: `Call`.
Consider this as the root of the tree where it has tags as attributes or children.
'
items:
$ref: '#/components/schemas/TagTreeLevel'
tags:
type: array
description: 'List of queryable tags available in a tagTree. Eg: `call.erroneous`.
Consider these tags as attributes of a tagTree. Eg: `Call` tagTree has have `Erroneous`, `Call name`, `Latency` etc as attributes.
'
items:
$ref: '#/components/schemas/Tag'
required:
- tagTree
- tags
Pagination:
type: object
properties:
page:
type: integer
format: int32
description: Page number for a specific page in the results. For example, if you'd like to retrieve the 5th page out of 10 pages, the value would be 5.
minimum: 1
pageSize:
type: integer
format: int32
description: 'Set the number of items you want to return with one query. Eg: if you want to retrieve 10 items, the value would be 10.'
maximum: 200
minimum: 1
Order:
type: object
description: 'Specifies the ordering of the results.
It contains fields that define the sorting criteria, the collation for sorting, and the direction in which the results should be ordered.
'
properties:
by:
type: string
description: If the granularity is set to `1` you can use the metric name eg. `latency.p95` to order by that value.
collation:
type: string
description: Language code used for sorting. Ignored for infrastructure queries.
direction:
type: string
description: The order in which results will be sorted, either `ASC` for ascending or `DESC` for descending.
enum:
- ASC
- DESC
required:
- by
- direction
IngestionOffsetCursor:
type: object
description: Cursor to use between successive queries
NewBusinessPerspectiveConfig:
type: object
properties:
description:
type: string
maxLength: 300
minLength: 0
name:
type: string
maxLength: 100
minLength: 0
tagFilterExpression:
$ref: '#/components/schemas/TagFilterExpressionElement'
Tag:
type: object
description: 'List of queryable tags available in a tagTree. Eg: `call.erroneous`.
Consider these tags as attributes of a tagTree. Eg: `Call` tagTree has have `Erroneous`, `Call name`, `Latency` etc as attributes.
'
properties:
aliases:
type: array
description: 'List of other names that can refer to this tag
'
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/instana/refs/heads/main/openapi/instana-business-monitoring-api-openapi.yml