Huntress Summary Reports API

openapi: 3.2.0
info:
  title: Huntress API Reference Summary Reports API
  description: '© Huntress - All rights reserved


    Introduction


    Webhook event payloads are available via the dropdown menu above the search bar on this page.'
  version: 1.0.0
servers:
- url: https://api.huntress.io
security:
- basic:
  - basic_auth
tags:
- name: Summary Reports
  description: Operations about Summary Reports
paths:
  /v1/reports:
    get:
      summary: List Summary Reports
      description: 'Shows Summary Reports associated with your account.


        **Note:** This endpoint will also return a `pagination` key on the root level.

        Please refer to the pagination section within our docs for more information.'
      parameters:
      - in: query
        name: limit
        description: Max number of resources returned in a paged collection. Defaults to 10, with a minimum of 1 and maximum 500.
        required: false
        schema:
          type: integer
          format: int32
          default: 10
          maximum: 500
          minimum: 1
      - in: query
        name: page_token
        description: Token used to request the next page in paginated results. Defaults to 'null'
        required: false
        schema:
          type: string
      - in: query
        name: sort_field
        description: Field to sort by. Defaults to 'id'.
        required: false
        schema:
          type: string
          enum:
          - id
          - created_at
          - updated_at
          default: id
      - in: query
        name: sort_direction
        description: Sort direction. Defaults to 'desc'.
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - in: query
        name: period_min
        description: Filter by an ISO-8601 formatted date string that represents the lower bound of the search range for the period date.
        required: false
        schema:
          type: string
      - in: query
        name: period_max
        description: Filter by an ISO-8601 formatted date string that represents the upper bound of the search range for the period date.
        required: false
        schema:
          type: string
      - in: query
        name: organization_id
        description: Filter by organization ID within Huntress account
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: type
        description: Filter by report type. One of monthly_summary, quarterly_summary, yearly_summary
        required: false
        schema:
          type: string
          enum:
          - monthly_summary
          - quarterly_summary
          - yearly_summary
      responses:
        '200':
          description: List Summary Reports
          content:
            application/json:
              schema:
                type: object
                properties:
                  reports:
                    type: array
                    items:
                      $ref: '#/components/schemas/SummaryReport'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                required:
                - reports
                - pagination
        '403':
          description: There was an issue with your API credential or permissions.
      tags:
      - Summary Reports
      operationId: getV1Reports
  /v1/reports/{id}:
    get:
      summary: Get Summary Report
      description: Shows details on a single Summary Report associated with your account.
      parameters:
      - in: path
        name: id
        description: Report ID within Huntress account
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Get Summary Report
          content:
            application/json:
              schema:
                type: object
                properties:
                  report:
                    $ref: '#/components/schemas/SummaryReport'
        '403':
          description: There was an issue with your API credential or permissions.
      tags:
      - Summary Reports
      operationId: getV1ReportsId
components:
  schemas:
    ReportIncidentRemediation:
      type: object
      properties:
        type:
          type: string
          example: Remediations::SessionRevocation
          description: The remediation type.
        subtype:
          type: string
          example: containment
          description: The remediation action category.
    ReportIncident:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 12345678
          description: The incident report identifier.
        severity:
          type: string
          example: critical
          description: The severity level of the incident.
        sent_at:
          type: string
          example: '2026-04-17T12:34:56Z'
          description: ISO-8601 formatted timestamp for when the incident was sent.
        event_summary:
          type: string
          example: Suspicious login detected from unusual location.
          description: A brief summary of the incident event.
        body:
          type: string
          example: A suspicious login was detected from an unusual location.
          description: The full description of the incident.
        remediations:
          type: array
          items:
            $ref: '#/components/schemas/ReportIncidentRemediation'
          description: Remediation actions taken for this incident.
    ReportExternalService:
      type: object
      properties:
        name:
          type: string
          example: SSH
          description: The name of the external service.
        risky:
          type: boolean
          example: true
          description: Whether this service is considered risky.
    SummaryReport:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
          description: A unique identifier for the summary report.
        agents_count:
          type: integer
          format: int64
          example: 2
          description: The number of agents deployed.
        allowed_exclusions_count:
          type: integer
          format: int64
          example: 0
          description: The number of allowed exclusions.
        analyst_name:
          type: string
          example: Jane Doe
          description: The name of the analyst who reviewed this report.
        analyst_note:
          type: string
          example: Everything is awesome! Thanks for using Huntress.
          description: The analyst note for this report.
        analyst_threats:
          type: array
          items:
            type: string
          example:
          - Ransomware
          - Dridex
          - Jupyter
          description: Global threat landscape information curated by the analyst.
        analyst_title:
          type: string
          example: Senior Security Analyst
          description: The title of the analyst who reviewed this report.
        antivirus_exclusions_count:
          type: integer
          format: int64
          example: 0
          description: The number of antivirus exclusions.
        autorun_events:
          type: integer
          format: int64
          example: 0
          description: The total number of autorun (auto-starting application) events in this report.
        autorun_signals_detected:
          type: integer
          format: int64
          example: 0
          description: The total number of autorun (auto-starting application) signals detected
        autorun_signals_reviewed:
          type: integer
          format: int64
          example: 0
          description: The number of autorun signals (auto-starting application) reviewed.
        autoruns_reviewed:
          type: integer
          format: int64
          example: 0
          description: A count of all the autoruns (auto-starting application) reviewed.
        blocked_malware_count:
          type: integer
          format: int64
          example: 0
          description: A count of blocked malware.
        created_at:
          type: string
          format: date-time
          example: '2022-03-01T20:56:15Z'
          description: ISO-8601 formatted timestamp for when this summary report was created.
        deployed_canaries_count:
          type: integer
          format: int64
          example: 0
          description: The number of canaries deployed.
        events_analyzed:
          type: integer
          format: int64
          example: 0
          description: A count of the events analyzed.
        external_ips_count:
          type: integer
          format: int64
          example: 3
          description: The number of external IP addresses discovered.
        external_ports_count:
          type: integer
          format: int64
          example: 12
          description: The number of external ports discovered.
        external_services:
          type: array
          items:
            $ref: '#/components/schemas/ReportExternalService'
          example:
          - name: SSH
            risky: true
          - name: HTTP
            risky: false
          description: Details of external services discovered during reconnaissance.
        firewall_disabled_count:
          type: integer
          format: int64
          example: 0
          description: The number of endpoints with firewall disabled.
        firewall_disabled_with_conflict_count:
          type: integer
          format: int64
          example: 0
          description: The number of endpoints with firewall disabled due to a conflict.
        firewall_enabled_count:
          type: integer
          format: int64
          example: 10
          description: The number of endpoints with firewall enabled.
        firewall_enabled_with_conflict_count:
          type: integer
          format: int64
          example: 0
          description: The number of endpoints with firewall enabled but with a conflict.
        global_threats_note:
          type: string
          example: World peace! No threats to see here.
          description: The global threats note for this report.
        host_processes_analyzed:
          type: integer
          format: int64
          example: 0
          description: A count of host processes analyzed.
        incident_indicator_counts:
          type: Object
          example:
            managed_av: 0
          description: A map of incident indicators (as strings) to counts (as integers).
        incident_log:
          type: array
          items:
            type: string
          example: []
          description: A JSON representation of any critical or high severity incidents from this report.
        incident_product_counts:
          type: Object
          example:
            edr: 16
            itdr: 0
            siem: 0
          description: A map of product names (as strings) to counts (as integers).
        incident_severity_counts:
          type: Object
          example:
            low: 16
          description: A map of incident severities (as strings) to counts (as integers).
        incidents_reported:
          type: integer
          format: int64
          example: 16
          description: The total number of incidents reported.
        incidents_resolved:
          type: integer
          format: int64
          example: 1
          description: The total number of incidents resolved.
        investigated_mav_detection_count:
          type: integer
          format: int64
          example: 0
          description: A count of investigated Managed Antivirus (MAV) detections.
        investigations_completed:
          type: integer
          format: int64
          example: 0
          description: The total number of investigations completed in this report.
        itdr_entities:
          type: integer
          format: int64
          example: 0
          description: A count of Identity Threat Detection Response entities
        itdr_events:
          type: integer
          format: int64
          example: 0
          description: A count of Identity Threat Detection Response events
        itdr_incidents_reported:
          type: integer
          format: int64
          example: 0
          description: The number of Identity Threat Detection Response incidents reported
        itdr_investigations_completed:
          type: integer
          format: int64
          example: 0
          description: A count of Identity Threat Detection Response investigations completed
        itdr_signals:
          type: integer
          format: int64
          example: 0
          description: The total number of Identity Threat Detection Response signals
        itdr_billable_identity_count:
          type: integer
          format: int64
          example: 50
          description: The number of billable identities for Identity Threat Detection Response.
        itdr_non_billable_identity_count:
          type: integer
          format: int64
          example: 10
          description: The number of non-billable identities for Identity Threat Detection Response.
        itdr_license_distribution:
          type: Object
          example:
            Microsoft 365 E3: 25
            Microsoft 365 E5: 15
            Other: 10
          description: A breakdown of Identity Threat Detection Response license types and their counts.
        itdr_usage_locations:
          type: array
          items:
            type: string
          example:
          - US
          - CA
          - GB
          - DE
          description: Top usage locations for Identity Threat Detection Response, as ISO country codes.
        linux_agent_count:
          type: integer
          format: int64
          example: 0
          description: The number of Linux agents.
        macos_agent_count:
          type: integer
          format: int64
          example: 0
          description: The number of MacOS agents.
        macos_agents:
          type: boolean
          example: false
          description: Indicates whether there are _any_ MacOS agents.
        mav_incident_report_count:
          type: integer
          format: int64
          example: 0
          description: A count of Managed Antivirus (MAV) incident reports.
        new_exclusions_count:
          type: integer
          format: int64
          example: 0
          description: The number of new exclusions since the last summary report.
        only_macos_agents:
          type: boolean
          example: false
          description: Indicates whether there are _only_ MacOS agents.
        organization_id:
          type: integer
          format: int64
          example: 7
          description: Unique identifier for the organization this summary report is associated with.
        period:
          type: string
          example: 2022-02-01...2022-03-02
          description: A date range representing the coverage of the report, formatted as `start_date...end_date`.
        powerful_application_count:
          type: integer
          format: int64
          example: 3
          description: The number of powerful applications detected.
        potential_threat_indicators:
          type: integer
          format: int64
          example: 0
          description: A count of the potential threat indicators.
        process_detections:
          type: integer
          format: int64
          example: 0
          description: The total number of process detections.
        process_detections_reported:
          type: integer
          format: int64
          example: 0
          description: ' A count of the process detections reported.'
        process_detections_reviewed:
          type: integer
          format: int64
          example: 0
          description: ' A count of the process detections reviewed.'
        protected_profiles_count:
          type: integer
          format: int64
          example: 0
          description: The number of protected profiles.
        ransomware_note:
          type: string
          example: No ransoms to report, all is well.
          description: The ransomware note for this report.
        risky_exclusions_removed_count:
          type: integer
          format: int64
          example: 0
          description: The number of risky exclusions removed.
        risky_services_count:
          type: integer
          format: int64
          example: 1
          description: The number of risky external services discovered.
        rogue_app_incidents:
          type: array
          items:
            $ref: '#/components/schemas/ReportIncident'
          description: Details of rogue application incidents detected.
        servers_agent_count:
          type: integer
          format: int64
          example: 0
          description: The number of server agents.
        shadow_workflow_incidents:
          type: array
          items:
            $ref: '#/components/schemas/ReportIncident'
          description: Details of shadow workflow incidents detected.
        siem_incidents_reported:
          type: integer
          format: int64
          example: 0
          description: The number of Security Information & Event Management incidents reported
        siem_ingested_logs:
          type: integer
          format: int64
          example: 0
          description: A count of Security Information & Event Management ingested logs
        siem_investigations_completed:
          type: integer
          format: int64
          example: 0
          description: A count of Security Information & Event Management signals that have been investigated
        siem_signals:
          type: integer
          format: int64
          example: 0
          description: The total number of Security Information & Event Management signals
        siem_total_logs:
          type: integer
          format: int64
          example: 0
          description: A count of Security Information & Event Management total logs
        signals_detected:
          type: integer
          format: int64
          example: 0
          description: A count of total signals detected.
        signals_investigated:
          type: integer
          format: int64
          example: 0
          description: A count of total signals investigated.
        top_incident_av_threats:
          type: array
          items:
            type: string
          example:
          - some_threat
          - another_threat
          - threats_threats_threats
          description: A list of the top av threats.
        top_incident_hosts:
          type: array
          items:
            type: string
          example:
          - some_host
          - another_host
          - hosts_hosts_hosts
          description: A list of the top hosts by number of incidents.
        total_entities:
          type: integer
          format: int64
          example: 2
          description: A count of the total entities included in this report.
        total_mav_detection_count:
          type: integer
          format: int64
          example: 0
          description: A count of the Managed Antivirus (MAV) detections.
        type:
          type: string
          example: monthly_summary
          description: The report type. Can be one of `monthly_summary`, `quarterly_summary`, `yearly_summary`.
        unwanted_access_incidents:
          type: array
          items:
            $ref: '#/components/schemas/ReportIncident'
          description: Details of unwanted access incidents detected.
        updated_at:
          type: string
          format: date-time
          example: '2022-03-01T20:56:15Z'
          description: ISO-8601 formatted timestamp for when this summary report was last updated.
        url:
          type: string
          example: https://huntress.io/rails/active_storage/blobs/redirect/uuid.pdf?disposition=download
          description: The direct url to the pdf version of this summary report.
        windows_agent_count:
          type: integer
          format: int64
          example: 2
          description: The number of Windows agents.
        weak_application_count:
          type: integer
          format: int64
          example: 1
          description: The number of weak applications detected.
        windows_agents:
          type: boolean
          example: true
          description: Indicates whether there are _any_ Windows agents.
      description: SummaryReport model
    Pagination:
      type: object
      properties:
        next_page_url:
          type: string
        next_page_token:
          type: string
      description: Pagination model
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic