Dynatrace Events API v2

openapi: 3.1.0
info:
  title: Dynatrace Events API v2
  version: 2.0.0
  description: >-
    The Dynatrace Events API v2 enables you to push custom events into a
    Dynatrace environment and retrieve event data from monitored systems. It
    supports creating deployment events, custom annotations, configuration
    events, and performance events targeting specific entities. Events ingested
    via this API are subject to DDU (Davis Data Units) licensing and may trigger
    Dynatrace AI analysis.
  contact:
    name: Dynatrace Support
    url: https://www.dynatrace.com/support/
  license:
    name: Dynatrace Terms of Service
    url: https://www.dynatrace.com/company/trust-center/terms/
  x-last-validated: '2026-04-18'
externalDocs:
  description: Dynatrace Events API v2 Documentation
  url: https://docs.dynatrace.com/docs/discover-dynatrace/references/dynatrace-api/environment-api/events-v2

servers:
- url: https://{environmentId}.live.dynatrace.com/api/v2
  description: Dynatrace SaaS environment
  variables:
    environmentId:
      description: The unique identifier of your Dynatrace environment
      default: mySampleEnv

tags:
- name: Events
  description: Operations for querying and ingesting custom events

security:
- api-token: []

paths:
  /events:
    get:
      operationId: listEvents
      summary: Dynatrace List Events
      description: >-
        Returns a list of events from the Dynatrace environment matching the
        specified filters. Results are paginated; use nextPageKey from the
        response to retrieve additional pages. Time range defaults to the last
        two hours if not specified.
      tags:
      - Events
      parameters:
      - name: nextPageKey
        in: query
        description: >-
          The cursor for the next page of results, obtained from the
          nextPageKey field of a previous response. When this parameter is
          set, all other query parameters except pageSize are ignored.
        required: false
        schema:
          type: string
        example: example-value
      - name: pageSize
        in: query
        description: >-
          The number of events to return per page. Default is 50, maximum
          is 1000.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 50
        example: 500
      - name: from
        in: query
        description: >-
          The start of the queried time range. Use a relative expression
          (now-1h), ISO 8601 timestamp, or Unix timestamp in milliseconds.
          Default is now-2h.
        required: false
        schema:
          type: string
        example: example-value
      - name: to
        in: query
        description: >-
          The end of the queried time range. Use a relative expression (now),
          ISO 8601 timestamp, or Unix timestamp in milliseconds. Default is
          now.
        required: false
        schema:
          type: string
        example: example-value
      - name: eventSelector
        in: query
        description: >-
          Defines the scope of the query using the event selector syntax.
          For example, eventType("CUSTOM_DEPLOYMENT") to filter by type, or
          title("My event") to filter by title. Multiple conditions can be
          combined.
        required: false
        schema:
          type: string
        example: type(SERVICE)
      - name: entitySelector
        in: query
        description: >-
          Filters events to those affecting entities matching this selector.
          Use the standard entity selector syntax, e.g., type(HOST),tag(prod).
        required: false
        schema:
          type: string
        example: type(SERVICE)
      - name: eventType
        in: query
        description: >-
          Filters results to events of the specified type. For a full list of
          types, see the eventType enum in EventIngestPayload.
        required: false
        schema:
          type: string
          enum:
          - AVAILABILITY_EVENT
          - CUSTOM_ALERT
          - CUSTOM_ANNOTATION
          - CUSTOM_CONFIGURATION
          - CUSTOM_DEPLOYMENT
          - ERROR_EVENT
          - MARKED_FOR_TERMINATION
          - PERFORMANCE_EVENT
          - RESOURCE_CONTENTION_EVENT
        example: AVAILABILITY_EVENT
      responses:
        '200':
          description: A paginated list of events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventCollection'
              examples:
                ListEvents200Example:
                  summary: Default listEvents 200 response
                  x-microcks-default: true
                  value:
                    nextPageKey: example-value
                    totalCount: 500
                    pageSize: 500
                    events: &id003
                    - eventId: abc123
                      eventType: STANDARD
                      title: example-value
                      startTime: 1718153645993
                      endTime: 1718153645993
                      entityId: {}
                      properties: &id001 {}
                      status: OPEN
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /events/{eventId}:
    get:
      operationId: getEvent
      summary: Dynatrace Get Event by Id
      description: >-
        Returns the details of a specific event identified by its event ID.
        The event ID is obtained from the list events endpoint or from event
        notification callbacks.
      tags:
      - Events
      parameters:
      - name: eventId
        in: path
        description: The unique identifier of the event to retrieve.
        required: true
        schema:
          type: string
        example: abc123
      responses:
        '200':
          description: The event details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
              examples:
                GetEvent200Example:
                  summary: Default getEvent 200 response
                  x-microcks-default: true
                  value:
                    eventId: abc123
                    eventType: STANDARD
                    title: example-value
                    startTime: 1718153645993
                    endTime: 1718153645993
                    entityId:
                      entityId: {}
                      name: {}
                      type: {}
                    properties: *id001
                    status: OPEN
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /events/ingest:
    post:
      operationId: ingestEvent
      summary: Dynatrace Ingest a Custom Event
      description: >-
        Ingests a custom event into the Dynatrace environment. The event is
        associated with one or more entities specified by the entitySelector.
        Custom events are used to annotate the timeline with deployment
        information, configuration changes, or custom alerts. Events consume
        Davis Data Units (DDUs). The API token requires the events.ingest scope.
      tags:
      - Events
      requestBody:
        description: The custom event to ingest
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventIngestPayload'
            example:
              eventType: CUSTOM_DEPLOYMENT
              title: Production deployment v2.5.1
              entitySelector: type(SERVICE),tag(production)
              startTime: 1609459200000
              properties:
                version: v2.5.1
                deployedBy: CI/CD pipeline
                remediationAction: https://runbook.example.com/rollback
      responses:
        '201':
          description: The event was successfully ingested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventIngestResult'
              examples:
                IngestEvent201Example:
                  summary: Default ingestEvent 201 response
                  x-microcks-default: true
                  value:
                    reportCount: 500
                    eventIngestResults: &id002
                    - eventId: abc123
                      status: ACTIVE
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    api-token:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Dynatrace API token. Use the format: Api-Token {your-token}
        Required scopes: events.read (for GET operations), events.ingest (for POST /events/ingest)

  responses:
    BadRequest:
      description: Bad request — invalid query parameters or request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Unauthorized:
      description: Unauthorized — missing or invalid API token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Forbidden:
      description: Forbidden — the API token lacks the required scope
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: Not found — the specified event does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'

  schemas:
    EventIngestPayload:
      type: object
      description: >-
        The payload for ingesting a custom event into Dynatrace. All events
        require at least an eventType and title. Custom events can target
        specific entities, include a time window, and carry additional metadata
        as key-value properties.
      required:
      - eventType
      - title
      properties:
        eventType:
          type: string
          description: >-
            The type of the custom event. Determines how the event is
            categorized and whether it triggers alerts or problem detection.
          enum:
          - AVAILABILITY_EVENT
          - CUSTOM_ALERT
          - CUSTOM_ANNOTATION
          - CUSTOM_CONFIGURATION
          - CUSTOM_DEPLOYMENT
          - ERROR_EVENT
          - MARKED_FOR_TERMINATION
          - PERFORMANCE_EVENT
          - RESOURCE_CONTENTION_EVENT
          example: AVAILABILITY_EVENT
        timeout:
          type: integer
          description: >-
            How long the event remains open, in minutes, if no endTime is
            specified. Range: 1 to 60 minutes. If not specified, the event
            closes after a short default duration.
          minimum: 1
          maximum: 60
          example: 1718153645993
        entitySelector:
          type: string
          description: >-
            The entity selector specifying which entities the event should be
            associated with. For example, type(SERVICE),tag(production).
            Required for most event types.
          example: type(SERVICE)
        title:
          type: string
          description: >-
            The title of the event. This is displayed in the Dynatrace UI and
            in problem notifications. Required.
          example: example-value
        startTime:
          type: integer
          format: int64
          description: >-
            The start time of the event as a Unix timestamp in milliseconds.
            If not specified, defaults to the current time.
          example: 1718153645993
        endTime:
          type: integer
          format: int64
          description: >-
            The end time of the event as a Unix timestamp in milliseconds.
            If specified, creates a closed event covering the time range.
          example: 1718153645993
        properties:
          type: object
          description: >-
            Additional key-value metadata to attach to the event. Maximum of
            30 key-value pairs. Keys and values must be strings.
          additionalProperties:
            type: string
          maxProperties: 30

          example: {}
    EventIngestResult:
      type: object
      description: The result returned after successfully ingesting a custom event.
      properties:
        reportCount:
          type: integer
          description: >-
            The number of event reports created. This may be greater than 1
            if the entitySelector matched multiple entities.
          example: 500
        eventIngestResults:
          type: array
          description: Details of each individual event ingestion result.
          items:
            $ref: '#/components/schemas/EventIngestResultItem'

          example: *id002
    EventIngestResultItem:
      type: object
      description: The result of ingesting an event for a single entity.
      properties:
        eventId:
          type: string
          description: The unique identifier assigned to the created event.
          example: abc123
        status:
          type: string
          description: >-
            The ingestion status for this entity. OK indicates success;
            other values indicate warnings or errors.

          example: ACTIVE
    Event:
      type: object
      description: >-
        Represents a single event in the Dynatrace environment. Events can
        be ingested via the API or detected automatically by Dynatrace.
      properties:
        eventId:
          type: string
          description: The unique identifier of the event.
          example: abc123
        eventType:
          type: string
          description: The type of the event.
          example: STANDARD
        title:
          type: string
          description: The display title of the event.
          example: example-value
        startTime:
          type: integer
          format: int64
          description: The start time of the event as a Unix timestamp in milliseconds.
          example: 1718153645993
        endTime:
          type: integer
          format: int64
          description: >-
            The end time of the event as a Unix timestamp in milliseconds.
            Null for open events.
          nullable: true
          example: 1718153645993
        entityId:
          $ref: '#/components/schemas/EntityStub'
        properties:
          type: object
          description: Additional key-value metadata attached to the event.
          additionalProperties:
            type: string
          example: *id001
        status:
          type: string
          description: >-
            The current status of the event. OPEN indicates the event is
            still active; CLOSED indicates it has ended.
          enum:
          - OPEN
          - CLOSED

          example: OPEN
    EventCollection:
      type: object
      description: A paginated collection of events.
      properties:
        nextPageKey:
          type: string
          description: >-
            The cursor for the next page of results. Null if there are no more
            pages.
          nullable: true
          example: example-value
        totalCount:
          type: integer
          format: int64
          description: The total number of events matching the query.
          example: 500
        pageSize:
          type: integer
          description: The number of results returned on this page.
          example: 500
        events:
          type: array
          description: The list of events on this page.
          items:
            $ref: '#/components/schemas/Event'

          example: *id003
    EntityStub:
      type: object
      description: A lightweight reference to a monitored entity.
      properties:
        entityId:
          type: string
          description: >-
            The unique identifier of the entity, e.g.,
            SERVICE-1234567890ABCDEF.
          example: abc123
        name:
          type: string
          description: The display name of the entity.
          example: Production Service
        type:
          type: string
          description: >-
            The type of the entity, e.g., SERVICE, HOST, PROCESS_GROUP,
            APPLICATION.

          example: STANDARD
    ErrorEnvelope:
      type: object
      description: Error response envelope returned when a request fails.
      properties:
        error:
          $ref: '#/components/schemas/Error'

    Error:
      type: object
      description: Details of an API error.
      properties:
        code:
          type: integer
          description: The HTTP status code of the error.
          example: 500
        message:
          type: string
          description: A human-readable description of the error.
          example: Example description.
        constraintViolations:
          type: array
          description: A list of constraint violations for validation errors (HTTP 400).
          items:
            $ref: '#/components/schemas/ConstraintViolation'

          example:
          - path: example-value
            message: Example description.
            parameterLocation: example-value
            location: example-value
    ConstraintViolation:
      type: object
      description: Details of a single constraint violation in a request.
      properties:
        path:
          type: string
          description: The JSON path to the field that caused the violation.
          example: example-value
        message:
          type: string
          description: A description of the constraint violation.
          example: Example description.
        parameterLocation:
          type: string
          description: The location of the violating parameter (QUERY, PATH, BODY).
          example: example-value
        location:
          type: string
          description: The location detail for the violation.
          example: example-value