Instana

Instana Custom Dashboards API

You can use these API endpoints to manage custom dashboards. We recommend that you leverage the `Edit as JSON` feature found within our user interface to construct the desired request payloads. Specifically to help you build correct widget configurations and access rules. To identify the correct values for the `relatedId` field of the access rules, we recommend using the `/api/custom-dashboard/shareable-users` and `/api/custom-dashboard/shareable-api-tokens` endpoints. These endpoints return our internal IDs for users and API tokens.

GitHub OpenAPI

Operations 7

GET /api/custom-dashboard Get accessible custom dashboards #
POST /api/custom-dashboard Add custom dashboard #
GET /api/custom-dashboard/shareable-api-tokens Get all API tokens #
GET /api/custom-dashboard/shareable-users Get all users (without invitations) #
DELETE /api/custom-dashboard/{customDashboardId} Remove custom dashboard #
GET /api/custom-dashboard/{customDashboardId} Get custom dashboard #
PUT /api/custom-dashboard/{customDashboardId} Update custom dashboard #

Documentation

📖
Documentation
https://instana.github.io/openapi/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/instana/refs/heads/main/openapi/instana-custom-dashboards-api-openapi.yml

Other Resources

🔗
GitHubOrganization
https://github.com/instana/openapi

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/instana-custom-dashboards-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

instana-custom-dashboards-api-openapi.yml Raw ↑ 
openapi: 3.2.0
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 Custom Dashboards 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?
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: Custom Dashboards
  description: You can use these API endpoints to manage custom dashboards.
paths:
  /api/custom-dashboard:
    get:
      description: 'Get all accessible custom dashboards details.

        For more information on custom dashboards please access the https://developer.ibm.com/apis/catalog/instana--instana-rest-api/Settings#custom-dashboards.'
      operationId: getCustomDashboards
      parameters:
      - description: query
        example: BeeInstana
        in: query
        name: query
        schema:
          type: string
      - description: pageSize
        example: 2
        in: query
        name: pageSize
        schema:
          type: integer
          format: int32
      - description: page
        example: 1
        in: query
        name: page
        schema:
          type: integer
          format: int32
      - description: withTotalHits
        example: false
        in: query
        name: withTotalHits
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              example:
              - id: gBtvG96xRpScauwsclG-KA
                title: BeeInstana - aggregator
                annotations:
                - SHARED
              - id: UtaUyPjGSTOAmPFICSbwqw
                title: BeeInstana - alerting
                annotations:
                - SHARED
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomDashboardPreview'
          description: OK
      security:
      - ApiKeyAuth:
        - Default
      summary: Get accessible custom dashboards
      tags:
      - Custom Dashboards
      x-ibm-ahub-byok: true
    post:
      description: For more information on custom dashboards please access the https://developer.ibm.com/apis/catalog/instana--instana-rest-api/Settings#custom-dashboards.
      operationId: addCustomDashboard
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomDashboard'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDashboard'
          description: OK
        '403':
          description: When attempting to share dashboards without the canCreatePublicCustomDashboards permission.
        '422':
          description: When the custom dashboard payload is invalid.
      security:
      - ApiKeyAuth:
        - Default
      summary: Add custom dashboard
      tags:
      - Custom Dashboards
      x-ibm-ahub-byok: true
  /api/custom-dashboard/shareable-api-tokens:
    get:
      description: 'Get all API tokens that have access to shareable custom dashboards.

        For more information on custom dashboards please access the https://developer.ibm.com/apis/catalog/instana--instana-rest-api/Settings#custom-dashboards.'
      operationId: getShareableApiTokens
      responses:
        '200':
          content:
            application/json:
              example:
              - id: foJfJVpyS5eAQAhfxSRctw
                name: New API Token
              - id: O_OKWG48S2WemaL_e3j_vQ
                name: New API Token
              - id: ATBzggrzTE-aRpUMBLmG9g
                name: New API Token
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DashboardApiToken'
          description: OK
      security:
      - ApiKeyAuth:
        - Default
      - ApiKeyAuth:
        - CreatePublicCustomDashboards
      summary: Get all API tokens
      tags:
      - Custom Dashboards
      x-ibm-ahub-byok: true
  /api/custom-dashboard/shareable-users:
    get:
      description: 'Get all users (without invitations) that have access to shareable custom dashboards.

        For more information on custom dashboards please access the https://developer.ibm.com/apis/catalog/instana--instana-rest-api/Settings#custom-dashboards.'
      operationId: getShareableUsers
      responses:
        '200':
          content:
            application/json:
              example:
              - id: 63721be55108940001ead6fa
                email: JohnMcClane@instana.com
                fullName: John McClane
              - id: 6360a5ad034a430001c500d0
                email: HansGruber@instana.com
                fullName: Hans Gruber
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserBasicResult'
          description: OK
      security:
      - ApiKeyAuth:
        - Default
      - ApiKeyAuth:
        - CreatePublicCustomDashboards
      summary: Get all users (without invitations)
      tags:
      - Custom Dashboards
      x-ibm-ahub-byok: true
  /api/custom-dashboard/{customDashboardId}:
    delete:
      description: For more information on custom dashboards please access the https://developer.ibm.com/apis/catalog/instana--instana-rest-api/Settings#custom-dashboards.
      operationId: deleteCustomDashboard
      parameters:
      - in: path
        name: customDashboardId
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Custom dashboard successfully removed
      security:
      - ApiKeyAuth:
        - Default
      summary: Remove custom dashboard
      tags:
      - Custom Dashboards
      x-ibm-ahub-byok: true
    get:
      description: 'Get all Custom Dashboard Info for specified customDashboardId.

        For more information on custom dashboards please access the https://developer.ibm.com/apis/catalog/instana--instana-rest-api/Settings#custom-dashboards.'
      operationId: getCustomDashboard
      parameters:
      - description: customDashboardId
        example: alHaYV5aSkKku_wcg53teQ
        in: path
        name: customDashboardId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example: "{\n  \"id\": \"alHaYV5aSkKku_wcg53teQ\",\n  \"title\": \"{string}\",\n  \"accessRules\": [\n    {\n      \"accessType\": \"READ_WRITE\",\n      \"relationType\": \"USER\",\n      \"relatedId\": \"5ee8a3e8cd70020001ecb007\"\n    },\n    {\n      \"accessType\": \"READ\",\n      \"relationType\": \"GLOBAL\",\n      \"relatedId\": null\n    }\n  ],\n  \"widgets\": [\n    {\n      \"id\": \"dIxxq0LCdqZomve2\",\n      \"title\": \"SUM of bytes received for a particular container\",\n      \"width\": 2,\n      \"height\": 4,\n      \"x\": 0,\n      \"y\": 0,\n      \"type\": \"bigNumber\",\n      \"config\": {\n        \"formatter\": \"bytes.detailed\",\n        \"comparisonDecreaseColor\": \"greenish\",\n        \"metricConfiguration\": {\n          \"metric\": \"network.rx.bytes\",\n          \"timeShift\": 0,\n          \"tagFilterExpression\": {\n            \"name\": \"docker.containerId\",\n            \"type\": \"TAG_FILTER\",\n            \"value\": \"faaa7f1732d16faa7fc27a0cb49fdf5c07716f3d3be1315e20f24d099657bbe0\",\n            \"entity\": \"NOT_APPLICABLE\",\n            \"operator\": \"EQUALS\"\n          },\n          \"aggregation\": \"SUM\",\n          \"source\": \"INFRASTRUCTURE_METRICS\",\n          \"crossSeriesAggregation\": \"SUM\",\n          \"type\": \"docker\"\n        },\n        \"comparisonIncreaseColor\": \"redish\"\n      }\n    }\n  ],\n  \"writable\": true,\n  \"ownerId\": {string}\n}\n"
              schema:
                $ref: '#/components/schemas/CustomDashboardWithUserSpecificInformation'
          description: OK
      security:
      - ApiKeyAuth:
        - Default
      summary: Get custom dashboard
      tags:
      - Custom Dashboards
      x-ibm-ahub-byok: true
    put:
      description: For more information on custom dashboards please access the https://developer.ibm.com/apis/catalog/instana--instana-rest-api/Settings#custom-dashboards.
      operationId: updateCustomDashboard
      parameters:
      - in: path
        name: customDashboardId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomDashboard'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDashboard'
          description: OK
        '403':
          description: When attempting to share dashboards without the canCreatePublicCustomDashboards permission.
        '422':
          description: When the custom dashboard payload is invalid.
      security:
      - ApiKeyAuth:
        - Default
      summary: Update custom dashboard
      tags:
      - Custom Dashboards
      x-ibm-ahub-byok: true
components:
  schemas:
    AccessRule:
      type: object
      properties:
        accessType:
          type: string
          description: "Specifies the type of access permitted. \n\n`READ`: Only viewing Application Perspective is allowed. \n\n`READ_WRITE`: Both viewing and modifying Application Perspective are permitted. \n\n"
          enum:
          - READ
          - READ_WRITE
        relatedId:
          type: string
          description: "An identifier that connects the access rule to a specific entity.\nFor example, if the `relationType` is `USER`, the corresponding `relatedId` would be a user id. \n\n**Note**: when `relationType` is `GLOBAL`, `relatedId` is `null`.\n"
          maxLength: 64
          minLength: 0
        relationType:
          type: string
          description: "Defines the type of relationship or subject to which the access rule applies. \n\n`USER`: Access is granted to an individual user. \n\n`API_TOKEN`: Access is granted to a specific API token. \n\n`ROLE`: Access is granted based on a user role, applying to any user with that role. \n\n`TEAM`: Access is granted to a team, likely applying to all team members. \n\n`GLOBAL`: Access is granted to every user or service.\n"
          enum:
          - USER
          - API_TOKEN
          - ROLE
          - TEAM
          - GLOBAL
      required:
      - accessType
      - relationType
    UserBasicResult:
      type: object
      properties:
        email:
          type: string
        fullName:
          type: string
        id:
          type: string
      required:
      - email
      - fullName
      - id
    CustomDashboardPreview:
      type: object
      properties:
        annotations:
          type: array
          items:
            type: string
            enum:
            - SHARED
            - WRITABLE
          maxItems: 8
          minItems: 0
          uniqueItems: true
        id:
          type: string
          maxLength: 64
          minLength: 0
        ownerId:
          type: string
        title:
          type: string
      required:
      - annotations
      - id
      - ownerId
      - title
    CustomDashboard:
      type: object
      properties:
        accessRules:
          type: array
          items:
            $ref: '#/components/schemas/AccessRule'
          maxItems: 64
          minItems: 1
        id:
          type: string
        title:
          type: string
        widgets:
          type: array
          items:
            $ref: '#/components/schemas/Widget'
          maxItems: 128
          minItems: 0
          uniqueItems: true
      required:
      - accessRules
      - id
      - title
      - widgets
    Widget:
      type: object
      properties:
        config:
          type: object
        height:
          type: integer
          format: int32
          minimum: 1
        id:
          type: string
          maxLength: 64
          minLength: 0
        title:
          type: string
        type:
          type: string
        width:
          type: integer
          format: int32
          maximum: 12
          minimum: 1
        x:
          type: integer
          format: int32
          maximum: 11
          minimum: 0
        y:
          type: integer
          format: int32
          minimum: 0
      required:
      - config
      - id
      - type
    CustomDashboardWithUserSpecificInformation:
      type: object
      properties:
        accessRules:
          type: array
          items:
            $ref: '#/components/schemas/AccessRule'
          maxItems: 64
          minItems: 1
        id:
          type: string
        ownerId:
          type: string
        title:
          type: string
        widgets:
          type: array
          items:
            $ref: '#/components/schemas/Widget'
          maxItems: 128
          minItems: 0
          uniqueItems: true
        writable:
          type: boolean
      required:
      - accessRules
      - id
      - ownerId
      - title
      - widgets
      - writable
    DashboardApiToken:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      required:
      - id
      - name
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: authorization
      type: apiKey
      description: "## Example\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"
x-tagGroups:
- name: Websites & Mobile Apps
  tags:
  - Website Metrics
  - Website Catalog
  - Website Analyze
  - Website Configuration
  - Mobile App Metrics
  - Mobile App Catalog
  - Mobile App Analyze
  - Mobile App Configuration
  - End User Monitoring
- name: Applications
  tags:
  - Application Metrics
  - Application Resources
  - Application Catalog
  - Application Analyze
  - Application Settings
  - Application Topology
  - Application Alert Configuration
  - Global Application Alert Configuration
- name: Infrastructure
  tags:
  - Infrastructure Analyze
  - Infrastructure Metrics
  - Infrastructure Resources
  - Infrastructure Catalog
  - Infrastructure Topology
- name: Logging
  tags:
  - Logging Analyze
- name: Synthetic Monitoring
  tags:
  - Synthetic Catalog
  - Synthetic Metrics
  - Synthetic Settings
  - Synthetic Test Playback Results
  - Synthetic Alert Configuration
- name: Logs
  tags:
  - Log Alert Configuration
- name: Events
  tags:
  - Events
  - Event Settings
- name: Automation
  tags:
  - Action Catalog
  - Action History
  - Policies
- name: Service Levels
  tags:
  - SLI Settings
  - SLI Report
  - Apdex Settings
  - Apdex Report
  - Service Levels Objective(SLO) Configurations
  - Service Levels Objective(SLO) Report
  - Service Levels Alert Configuration
  - SLO Correction Configurations
  - SLO Correction Windows
- name: AI Management
  tags:
  - AI Management
- name: Settings
  tags:
  - Custom Dashboards
  - User
  - Groups
  - Teams
  - Roles
  - Audit Log
  - API Token
  - Maintenance Configuration
  - Synthetic Calls
  - Session Settings
  - Automation Settings
  - Authentication
- name: Open Beta Features
  tags:
  - Infrastructure Analyze
- name: Closed Beta Features
  tags:
  - Infrastructure Alert Configuration
- name: Instana
  tags:
  - Releases
  - Host Agent
  - Health
  - Usage