openapi: 3.1.0
info:
  title: HubSpot Analytics Events Access Tokens Event Instances API
  description: "The HubSpot Analytics Events API allows you to retrieve event completion data \nfrom your HubSpot account. Use this API to query event instances associated with \nCRM objects, filter by event types, and analyze user behavior and engagement patterns.\n\n## Key Features\n- Retrieve event instances for CRM objects\n- Filter events by type, date range, and object\n- Paginate through large result sets\n- Query available event types\n"
  version: 3.0.0
  contact:
    name: HubSpot Developer Support
    url: https://developers.hubspot.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://api.hubapi.com
  description: HubSpot Production API Server
tags:
- name: Event Instances
  description: Retrieve and query event completion data from CRM objects
paths:
  /events/v3/events:
    get:
      tags:
      - Event Instances
      operationId: getEventInstances
      summary: Hubspot Retrieve Event Instances
      description: "Retrieve instances of event completion data from your HubSpot account. \nUse this endpoint to query events associated with specific CRM objects, \nfilter by event type and date range, and paginate through large result sets. \nThis is useful for analyzing user engagement and tracking conversion funnels.\n"
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: 'return "Success"

          '
      security:
      - OAuth2:
        - analytics.read
      parameters:
      - name: objectType
        in: query
        schema:
          type: string
          enum:
          - contact
          - company
          - deal
          - ticket
        description: The type of CRM object to filter event instances on
        example: contact
      - name: objectId
        in: query
        schema:
          type: string
        description: The ID of the CRM object to filter events. Requires objectType parameter.
        example: '123456'
      - name: eventType
        in: query
        schema:
          type: string
        description: Filter by specific event type name
        example: page_view
      - name: occurredAfter
        in: query
        schema:
          type: string
          format: date-time
        description: Filter for events that occurred after this ISO 8601 datetime
        example: '2024-01-01T00:00:00Z'
      - name: occurredBefore
        in: query
        schema:
          type: string
          format: date-time
        description: Filter for events that occurred before this ISO 8601 datetime
        example: '2024-12-31T23:59:59Z'
      - name: sort
        in: query
        schema:
          type: string
          enum:
          - ASCENDING
          - DESCENDING
        description: Sort direction based on event timestamp
        example: DESCENDING
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        description: Maximum number of results per page (1-100)
        example: 20
      - name: after
        in: query
        schema:
          type: string
        description: Pagination cursor for the next page of results
        example: example-value
      responses:
        '200':
          description: Successfully retrieved event instances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventInstanceCollection'
              examples:
                Success:
                  $ref: '#/components/examples/EventInstanceCollectionExample'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse'
        '500':
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    ErrorDetail:
      type: object
      description: Detailed information about a specific error
      properties:
        message:
          type: string
          description: Human-readable error message
          example: This is an example description.
        code:
          type: string
          description: Machine-readable error code
          example: example-value
        subCategory:
          type: string
          description: Specific error subcategory
          example: standard
        in:
          type: string
          description: Location where the error occurred (e.g., query, path, body)
          example: example-value
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Additional context about the specific error
          example:
            key: value
      required:
      - message
    Error:
      type: object
      description: Standard error response returned when an API request fails
      properties:
        category:
          type: string
          description: High-level error category
          example: standard
        correlationId:
          type: string
          format: uuid
          description: Unique identifier for tracking and debugging the error
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        message:
          type: string
          description: Human-readable error message
          example: This is an example description.
        subCategory:
          type: string
          description: Specific error subcategory for detailed classification
          example: standard
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Additional context about the error
          example:
            key: value
        links:
          type: object
          additionalProperties:
            type: string
          description: Relevant links for error resolution and documentation
          example:
            key: value
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
          description: List of specific errors encountered
          example:
          - message: This is an example description.
            code: example-value
            subCategory: standard
            in: example-value
            context:
              key: value
      required:
      - category
      - correlationId
      - message
    PagingPrevious:
      type: object
      description: Pagination cursor for retrieving the previous page of results
      properties:
        before:
          type: string
          description: Cursor token for the previous page
          example: example-value
        link:
          type: string
          description: API link to the previous page of results
          example: https://app.hubspot.com/contacts/12345
    EventInstanceCollection:
      type: object
      description: Paginated collection of event instances
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/EventInstance'
          description: Array of event instances
          example:
          - id: '500123'
            eventType: standard
            objectId: '500123'
            objectType: standard
            occurredAt: '2025-03-15T14:30:00Z'
            properties:
              key: value
        paging:
          $ref: '#/components/schemas/Paging'
      required:
      - results
    EventInstance:
      type: object
      description: Represents a single event instance that occurred in the system
      properties:
        id:
          type: string
          description: Unique identifier for the event instance
          example: '500123'
        eventType:
          type: string
          description: The type of event that occurred
          example: standard
        objectId:
          type: string
          description: The ID of the CRM object associated with this event
          example: '500123'
        objectType:
          type: string
          description: The type of CRM object (e.g., contact, company, deal)
          example: standard
        occurredAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the event occurred
          example: '2025-03-15T14:30:00Z'
        properties:
          type: object
          additionalProperties:
            type: string
          description: Additional properties associated with the event
          example:
            key: value
      required:
      - id
      - eventType
      - occurredAt
    Paging:
      type: object
      description: Pagination information for navigating result sets
      properties:
        next:
          $ref: '#/components/schemas/PagingNext'
        prev:
          $ref: '#/components/schemas/PagingPrevious'
    PagingNext:
      type: object
      description: Pagination cursor for retrieving the next page of results
      properties:
        after:
          type: string
          description: Cursor token for the next page
          example: example-value
        link:
          type: string
          description: API link to the next page of results
          example: https://app.hubspot.com/contacts/12345
  responses:
    ErrorResponse:
      description: An error occurred while processing the request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            ValidationError:
              $ref: '#/components/examples/ErrorExample'
  examples:
    ErrorExample:
      summary: Validation error response
      value:
        category: VALIDATION_ERROR
        correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
        message: Invalid input parameters
        subCategory: INVALID_PARAMETER
        context:
          invalidFields:
          - objectType
        links:
          documentation: https://developers.hubspot.com/docs/api/events
        errors:
        - message: objectType must be a valid CRM object type
          code: INVALID_OBJECT_TYPE
          in: query
    EventInstanceCollectionExample:
      summary: Successful retrieval of event instances
      value:
        results:
        - id: evt_12345
          eventType: page_view
          objectId: '123456'
          objectType: contact
          occurredAt: '2024-01-15T10:30:00Z'
          properties:
            page_url: https://example.com/pricing
            duration: '45'
        - id: evt_12346
          eventType: form_submission
          objectId: '123456'
          objectType: contact
          occurredAt: '2024-01-15T10:35:00Z'
          properties:
            form_name: Contact Us
            submission_id: sub_789
        paging:
          next:
            after: NTI1Cg%3D%3D
            link: /events/v3/events/?after=NTI1Cg%3D%3D
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.hubspot.com/oauth/authorize
          tokenUrl: https://api.hubapi.com/oauth/v1/token
          scopes:
            analytics.read: Read analytics data