Instana Action History API

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 Action History 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: Action History
paths:
  /api/automation/actioninstances:
    delete:
      description: Deletes the automation action run results from the action run history. The results to delete is filtered by the filter values given in the query parameters. The automation action run result will be deleted only if the action run result was created within the timeframe specified in the `from` and `to` query parameters. This call requires `Deletion of automation action history` permission and, `from` and `to` query parameters.
      operationId: deleteActionInstances
      parameters:
      - description: From date filter in milliseconds (13-digit) to look up the action run results to delete
        example: 1706713140000
        in: query
        name: from
        required: true
        schema:
          type: integer
          format: int64
      - description: To date filter in milliseconds (13-digit) to look up the action run results to delete
        example: 1706713140000
        in: query
        name: to
        required: true
        schema:
          type: integer
          format: int64
      - description: Target snapshot ID to look up the action run results to delete
        example: aCtEoR6NSPqG61QkIkwwCw
        in: query
        name: targetSnapshotId
        schema:
          type: string
      - description: Event ID filter to look up the action run results to delete
        example: bCtEoR6NSPqG61QkIkwwCw
        in: query
        name: eventId
        schema:
          type: string
      - description: Event specification ID filter to look up the action run results to delete
        example: 1706713140000
        in: query
        name: eventSpecificationId
        schema:
          type: string
      - description: Text in action run result name, description and event name to filter the action run results to delete
        example: 1706713140000
        in: query
        name: search
        schema:
          type: string
      - description: Action type filter to look up the action run results to delete
        example: One or more of the following types HTTP, SCRIPT, ANSIBLE, GITHUB, GITLAB, JIRA
        in: query
        name: types
        schema:
          type: array
          items:
            type: string
      - description: Action status filter to look up the action run results to delete
        example: One or more of the following status SUBMITTED, IN_PROGRESS, SUCCESS, FAILED, TIMEOUT
        in: query
        name: actionStatuses
        schema:
          type: array
          items:
            type: string
      - description: List of action IDs  to filter the action run results to delete
        example: cCtEoR6NSPqG61QkIkwwCw
        in: query
        name: actionIds
        schema:
          type: array
          items:
            type: string
      - description: Policy ID filter to look up the action run results to delete
        example: bCtEoR6NSPqG61QkIkwwCw
        in: query
        name: policyId
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                deletedDocumentsCount: '2'
          description: Automation action run results are deleted.
        '400':
          description: '`from` date or `to` date query parameter is missing.'
        '403':
          description: Automation feature is not enabled or Insufficient permissions.
        '500':
          description: The request do not contain a valid user or API Token.
      security:
      - ApiKeyAuth:
        - canDeleteAutomationActionHistory
      summary: Delete automation action run results
      tags:
      - Action History
      x-ibm-ahub-byok: true
    get:
      description: Get the details of automation action run results from action run history. The results are filtered by the filters in the query parameters. The automation action run result will be fetched only if the action run results were created within the timeframe specified by the `windowSize` and `to` query parameters. The `windowSize` parameter is used to compute the from date (`from = to - windowSize`) of the timeframe. The default value for `windowSize` is 10 minutes and the default value for `to` is current system time. When using personal access tokens, the user must have at least `Viewer` access for Automation and the automation action run results returned are also filtered based on the access set in `Limited access` permission settings. This API returns paginated result as specified in query parameters `page` and `pageSize`. The response contains list of automation action run results whose contents corresponds to the `page` query parameter and whose size corresponds to the `pageSize` query parameter.
      operationId: getActionInstances
      parameters:
      - description: Window size filter in milliseconds (to compute the from date) to get the action run result details
        example: 10000
        in: query
        name: windowSize
        schema:
          type: integer
          format: int64
      - description: To date filter in milliseconds (13-digit) to get the action run result details
        example: 1706713140000
        in: query
        name: to
        schema:
          type: integer
          format: int64
      - description: Page to fetch -- used for paging the action run result records
        example: 2
        in: query
        name: page
        schema:
          type: integer
          format: int32
      - description: Number of records to return in each page -- used for paging the action run result records
        example: 50
        in: query
        name: pageSize
        schema:
          type: integer
          format: int32
      - description: Target snapshot ID filter to get the action run result details
        example: nCtEoR6NSPqG61QkIkwwCw
        in: query
        name: targetSnapshotId
        schema:
          type: string
      - description: Event ID filter to get the action run result details
        example: nCtEoR6NSPqG61QkIkwwCw
        in: query
        name: eventId
        schema:
          type: string
      - description: Event specification ID filter to get the action run result details
        example: 1706713140000
        in: query
        name: eventSpecificationId
        schema:
          type: string
      - description: Text in action run result name, description and event name filter to get the action run result details
        example: 1706713140000
        in: query
        name: search
        schema:
          type: string
      - description: Action type filter to get the action run result details
        example: One or more of the following types HTTP, SCRIPT, ANSIBLE, GITHUB, GITLAB, JIRA
        in: query
        name: types
        schema:
          type: array
          items:
            type: string
      - description: Action status filter to get the action run result details
        example: One or more of the following status SUBMITTED, IN_PROGRESS, SUCCESS, FAILED, TIMEOUT
        in: query
        name: actionStatuses
        schema:
          type: array
          items:
            type: string
      - description: Action IDs filter to get the action run result details for only these actions
        in: query
        name: actionIds
        schema:
          type: array
          items:
            type: string
      - description: Policy ID filter to get the action run result details
        example: nCtEoR6NSPqG61QkIkwwCw
        in: query
        name: policyId
        schema:
          type: string
      - description: Action run result column to order the result set.
        example: Name of the action run result column. Default is action run result start date.
        in: query
        name: orderBy
        schema:
          type: string
      - description: Sort order direction.
        example: asc or desc
        in: query
        name: orderDirection
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                items:
                - actionInstanceId: fqiH0HOgR1-4Ygoy5EDycw
                  actionId: d473c1b0-0740-4d08-95fe-31e5d0a9faff
                  actionName: Hello World
                  type: SCRIPT
                  status: SUCCESS
                  createdDate: 1710162882369
                  startDate: 1710162882653
                  endDate: 1710162882826
                  eventId: M3wuBxuaSDyecZJ7ICioiw
                  eventSpecificationId: en0FW6XRWu7aRsD4055dbMLAuSU
                  problemText: Test event
                  hostSnapshotId: 2nIOVtEW-iPbsEIi89-yDqJHi2g
                  targetSnapshotId: jfSmhACY-Oa3a8zfjJxvOxJeDSk
                  metadata: []
                page: 1
                pageSize: 50
                totalHits: 500
              schema:
                $ref: '#/components/schemas/PaginatedResult'
          description: Automation action run result details are returned.
        '403':
          description: Automation feature is not enabled or Insufficient permissions.
      security:
      - ApiKeyAuth:
        - Default
      summary: Get the details of automation action run results from action run history
      tags:
      - Action History
      x-ibm-ahub-byok: true
    post:
      description: Submits the automation action for execution on an agent. The automation action to execute and the agent on which to execute the action must be specified as actionId and hostId. For more details on the request payload see the request sample. This call requires `Execution of automation actions` permission.
      operationId: addActionInstance
      requestBody:
        content:
          application/json:
            example:
              hostId: aHostId
              actionId: d473c1b0-0740-4d08-95fe-31e5d0a9faff
              policyId: 2nIOVtEW-iPbsEIi89-yDqJabc
              inputParameters:
              - name: name
                type: type
                value: value
              eventId: M3wuBxuaSDyecZJ7ICioiw
              async: 'true'
              timeout: '600'
            schema:
              $ref: '#/components/schemas/ActionInstanceRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                actionInstanceId: fqiH0HOgR1-4Ygoy5EDycw
                actionId: d473c1b0-0740-4d08-95fe-31e5d0a9faff
                actionName: Hello World
                type: SCRIPT
                status: SUBMITTED
                createdDate: 1710162882369
                eventId: M3wuBxuaSDyecZJ7ICioiw
                eventSpecificationId: en0FW6XRWu7aRsD4055dbMLAuSU
                problemText: Test event
                hostSnapshotId: 2nIOVtEW-iPbsEIi89-yDqJHi2g
                targetSnapshotId: jfSmhACY-Oa3a8zfjJxvOxJeDSk
                inputParameters: []
                outputParameters: []
                metadata: []
                externalSourceType: ''
                actorId: 5ee5195fbea6150001758c40
                actorName: Stan
                actorType: USER
                eventEntityType: ''
                actionDescription: Simple script action for testing
                policyId: 2nIOVtEW-iPbsEIi89-yDqJabc
              schema:
                $ref: '#/components/schemas/ActionInstance'
          description: Automation action submitted for execution on the agent.
        '400':
          description: The payload in the request body is not valid or the action ID (actionId) in the payload is invalid or the agent host ID (hostId) in the payload is invalid.
        '403':
          description: Automation feature is not enabled or Insufficient permissions.
      security:
      - ApiKeyAuth:
        - canRunAutomationActions
      summary: Run an automation action
      tags:
      - Action History
      x-ibm-ahub-byok: true
  /api/automation/actioninstances/{actionInstanceId}:
    delete:
      description: Deletes the automation action run result specified in the request path from the action run history. The automation action run result will be deleted only if the action run result was created within the timeframe specified in the `from` and `to` query parameters. To get the automation action run result ID and the created time, you can run `/api/automation/actioninstances` and `/api/automation/actioninstances/` REST calls. This call requires `Deletion of automation action history` permission.
      operationId: deleteActionInstance
      parameters:
      - description: Automation action run result ID to delete.
        example: nCtEoR6NSPqG61QkIkwwCw
        in: path
        name: actionInstanceId
        required: true
        schema:
          type: string
      - description: From date filter in milliseconds (13-digit) to look up the action run result ID.
        example: 1706713140000
        in: query
        name: from
        required: true
        schema:
          type: integer
          format: int64
      - description: To date filter in milliseconds (13-digit) to look up the action run result ID.
        example: 1706713190000
        in: query
        name: to
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          content:
            application/json:
              example:
                deletedDocumentsCount: '2'
          description: Automation action run result is deleted.
        '400':
          description: Automation action run result ID is missing in the request path, or `from` date or `to` date is missing in the query parameters.
        '403':
          description: Automation feature is not enabled or Insufficient permissions.
        '500':
          description: The request do not contain a valid user or API Token.
      security:
      - ApiKeyAuth:
        - canDeleteAutomationActionHistory
      summary: Deletes an automation action run result from the action run history by ID
      tags:
      - Action History
      x-ibm-ahub-byok: true
    get:
      description: Get the details of automation action run result specified in the request path from action run history. The automation action run result will be fetched only if the action run result was created within the timeframe specified by the `windowSize` and `to` query parameters. The `windowSize` parameter is used to compute the from date (`from = to - windowSize`) of the timeframe. The default value for `windowSize` is 10 minutes and the default value for `to` is current system time. To get the automation action run result ID and the created time, you can run `/api/automation/actioninstances` REST calls. When using personal access tokens, the user must have at least `Viewer` access for Automation.
      operationId: getActionInstance
      parameters:
      - description: action run result ID to get action run result details
        example: nCtEoR6NSPqG61QkIkwwCw
        in: path
        name: actionInstanceId
        required: true
        schema:
          type: string
      - description: Window size in milliseconds. This value is used compute the from date `(from = to - windowSize)` to get the action run result details. The default `windowSize` is set to 10 minutes if this value is not provided.
        example: 10000
        in: query
        name: windowSize
        schema:
          type: integer
          format: int64
      - description: To date filter in milliseconds (13-digit) to get the action run result details. The default `to` date is set to `System.currentTimeMillis()` if this value is not provided.
        example: 1706713140000
        in: query
        name: to
        schema:
          type: integer
          format: int64
      responses:
        '200':
          content:
            application/json:
              example:
                actionInstanceId: fqiH0HOgR1-4Ygoy5EDycw
                actionId: d473c1b0-0740-4d08-95fe-31e5d0a9faff
                actionName: Hello World
                type: SCRIPT
                status: SUCCESS
                returnCode: 0
                errorMessage: ''
                createdDate: 1710162882369
                startDate: 1710162882653
                endDate: 1710162882826
                eventId: M3wuBxuaSDyecZJ7ICioiw
                eventSpecificationId: en0FW6XRWu7aRsD4055dbMLAuSU
                problemText: Test event
                hostSnapshotId: 2nIOVtEW-iPbsEIi89-yDqJHi2g
                inputParameters: []
                outputParameters: []
                metadata: []
                targetSnapshotId: jfSmhACY-Oa3a8zfjJxvOxJeDSk
                externalSourceType: ''
                actorId: 5ee5195fbea6150001758c40
                actorName: Stan
                actorType: USER
                eventEntityType: ''
                actionDescription: Simple script action for testing
                policyId: 2nIOVtEW-iPbsEIi89-yDqJabc
                output: Hello world!
              schema:
                $ref: '#/components/schemas/ActionInstance'
          description: The automation action run result detail is returned.
        '400':
          description: Missing automation action run result ID.
        '403':
          description: Automation feature is not enabled or Insufficient permissions.
      security:
      - ApiKeyAuth:
        - Default
      summary: Get the details of an automation action run result by ID from action run history
      tags:
      - Action History
      x-ibm-ahub-byok: true
components:
  schemas:
    ActionInstance:
      type: object
      properties:
        actionDescription:
          type: string
          description: Action description of the action to run.
        actionId:
          type: string
          description: Action identifier of the action to run.
        actionInstanceId:
          type: string
          description: Action run identifier.
          readOnly: true
        actionName:
          type: string
          description: Action name of the action to run.
        actionSnapshot:
          type: string
          description: Snapshot of the action definition.
          readOnly: true
        actorId:
          type: string
          description: User identifier, API token or the policy identifier that started the action run.
        actorName:
          type: string
          description: Name of the user, API token or the policy that started the action run.
        actorType:
          type: string
          description: Type of Actor. Valid values are listed in the enum definition.
          enum:
          - ACTOR_UNKNOWN
          - USER
          - APITOKEN
          - POLICY
        createdDate:
          type: integer
          format: int64
          description: Action run created timestamp. The timestamp at which the action run got submitted.
        endDate:
          type: integer
          format: int64
          description: Action run end timestamp. The timestamp at which the action run ended on the agent host.
        errorMessage:
          type: string
          description: Error message, if any, of action run on the agent host.
        eventEntityType:
          type: string
          description: Event entity type set in the event that triggered this action run.
        eventId:
          type: string
          description: Event identifier of the event that triggered this action run.
        eventSpecificationId:
          type: string
          description: Event specification identifier of the event that triggered this action run.
        externalSourceType:
          type: string
          description: If the action type is external this field contains the name of the external source.
        hostSnapshotId:
          type: string
          description: Host snapshot identifier of the agent on which the action ran.
        inputParameters:
          type: array
          description: List of input parameters to this action run.
          items:
            $ref: '#/components/schemas/ActionInstanceParameter'
        metadata:
          type: array
          description: List of metadata parameters set to this action run by sensors.
          items:
            $ref: '#/components/schemas/ActionInstanceMetadataEntry'
        output:
          type: string
          description: Action run output.
        policyId:
          type: string
          description: Identifier of the policy that triggered this action run.
        problemText:
          type: string
          description: Event problem text of the event that triggered this action run.
        returnCode:
          type: integer
          format: int32
          description: Return code of action run on the agent host.
        startDate:
          type: integer
          format: int64
          description: Action run start timestamp. The timestamp at which the action run started on the agent host.
        status:
          type: string
          description: Action run status. Valid values are listed in the enum definition.
          enum:
          - STATUS_UNKNOWN
          - SUBMITTED
          - IN_PROGRESS
          - SUCCESS
          - FAILED
          - READY
          - TIMEOUT
        targetSnapshotId:
          type: string
          description: Action target entity identifier set in the event that triggered this action run. This is the identifier of the entity on which an incident or issue was raised.
        type:
          type: string
          description: Action type. Valid values are listed in the enum definition.
          enum:
          - SCRIPT
          - HTTP
          - ANSIBLE
          - EXTERNAL
          - GITHUB
          - GITLAB
          - JIRA
          - MANUAL
          - DOC_LINK
      required:
      - actionId
      - actionName
      - type
    ActionInstanceRequestParameters:
      type: object
      description: Action run input parameters.
      properties:
        name:
          type: string
          description: Name of the input parameter.
        type:
          type: string
          description: Type of the input parameter. Valid values are `static`, `dynamic` or `vault`. Default is `static`.
        value:
          type: string
          description: Value of the input parameter
      required:
      - name
      - value
    ActionInstanceParameter:
      type: object
      description: List of input parameters to this action run.
      properties:
        displayName:
          type: string
          description: Parameter display name.
        name:
          type: string
          description: Parameter name.
        type:
          type: string
          description: Parameter type. Valid values are `static`, `dynamic` or `vault`
        value:
          type: string
          description: Parameter value.
      required:
      - displayName
      - name
    PaginatedResult:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
        page:
          type: integer
          format: int32
          description: Page Number
          minimum: 1
        pageSize:
          type: integer
          format: int32
          minimum: 1
        totalHits:
          type: integer
          format: int64
          minimum: 0
      required:
      - items
    ActionInstanceMetadataEntry:
      type: object
      description: List of metadata parameters set to this action run by sensors.
      properties:
        name:
          type: string
          description: Metadata name.
        value:
          type: string
          description: Metadata value.
      required:
      - name
    ActionInstanceRequest:
      type: object
      properties:
        actionId:
          type: string
          description: Action identifier of the action to run.
        async:
          type: string
          description: '`"true"` if the action should be run in asynchronous mode `"false"` otherwise. Default is `"true"`.'
        eventId:
          type: string
          description: Event identifier (incident or issue) associated with the policy.
        hostId:
          type: string
          description: Agent host identifier on which to run the action.
        inputParameters:
          type: array
          description: Action run input parameters.
          items:
            $ref: '#/components/schemas/ActionInstanceRequestParameters'
        policyId:
          type: string
          description: Policy identifier that associates the action trigger (incident or issue) to the action to run.
        timeout:
          type: string
          description: Action run time out. Default is `30 seconds`.
      required:
      - actionId
      - hostId
  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