swagger: '2.0' info: title: Huntress API Reference Accounts Summary Reports API description: "\n

© Huntress - All rights reserved

\n

Introduction

\n\n

Webhook event payloads are available via the dropdown menu above the search bar on this page.

\n\n

The Huntress API follows a RESTful pattern. Requests are made via resource-oriented URLs as described in this document and API responses are formatted as JSON data.

\n\n

A command-line client is also available for interacting with the API from your terminal. It requires Ruby 3.1+ and has no external dependencies. You can download it from https://api.huntress.io/api/huntress-cli.

\n\n

Alternatively, if you'd prefer to use an MCP, we have instructions for setting up the Huntress MCP. Note that the MCP is read-only, so this is a good option if you're looking for a safer way to access your Huntress data from an LLM.

\n\n

If you'd like to request additional API endpoints or capabilities, submit feedback through our feedback portal.

\n\n

API Overview

\n
\n\t

Authentication

\n
$KEY = echo \"$HUNTRESS_PUBLIC_KEY:$HUNTRESS_PRIVATE_KEY\" | base64\ncurl \"https://api.huntress.io/v1/agents\" \\ -H \"Authorization: Basic $KEY\"\n
\n
\n

To begin, generate your API Key at <your_account_subdomain>.huntress.io. Once you are logged into your account on the Huntress site, check the dropdown menu at the top-right corner of the site header. You should see API Credentials among the options if your account has been granted access to the Huntress API. Click on the option to continue to the API Key generation page.

\n\n

Once on the API Key generation page, click on the green Setup button to begin the process to generate your API Key. You will be redirected to a page where you will be prompted to generate your API Key. Click the Generate button to generate a public and private key pair for Huntress API access. The inputs on the page will be filled in with your access credentials once you have done so.

\n\n

Your API Private Key will only be visible at this stage of API Key generation. Be sure to save the value provided somewhere secure, as once you navigate away from this page, this value will no longer be accessible and you must regenerate your API credentials if your secret key value is lost.

\n\n

If necessary, you can repeat the process to regenerate your API credentials with a new API Key and API Secret Key on the same API Key generation page, at <your_account_subdomain>.huntress.io/account/api_credentials.

\n\n

The Huntress API implements basic access authentication. Once you have your API Key and API Secret Key, provide these values as the result of a Base64 encoded string in every request to the Huntress API via the Authorization header. Your request header should look something like Authorization: Basic [Base64Encode(<your_api_key>:<your_api_secret_key>)]. Please refer to the code snippets for further examples.

\n
\n
\n\t

Rate Limits

\n

Every Huntress API account is rate limited to 60 requests per minute, on a sliding window. This means that no more than 60 requests can be made within a 60 second time interval between the first request and the last request.

\n\n

For example, if request 1 is made at T0, request 2 is made at T5, and requests 3 through 60 are made at T10, making request 61 at T55 would result in a 429 error response. Making request 61 at T61 would succeed, however making request 62 at T61 would fail, at least until the time has passed T65, corresponding to a minute after request 2 was made.

\n
\n
\n\t

HTTP Response Codes

\n

Huntress follows HTTP standards when delivering responses: a 2xx response is a success, a 4xx response indicates an issue with the client request, and a 5xx response indicates an issue with Huntress servers.\n
\n
\nSpecific error codes are detailed in the following table:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Error Status CodeDetails
400There is an unexpected value in the API request being made.
401Your request could not be authenticated. Check that your API key is properly formatted and included in the Authorization header.
404The requested resource is unavailable: either it doesn't exist, or your account does not hold correct permissions to access it.
429You have made too many requests within the rate limit timeframe. See the previous section on rate_limits for details.
500

An error has occurred within Huntress servers.

You could retry the request, but if you encounter continued errors, please contact Support with details of your error. If all traffic from Huntress is resulting in 500 responses, please check our Huntress Status Page.

\n
\n
\n\t

Pagination

\n

Certain Huntress API endpoints utilize a page_token and limit parameter to specify a window location and size, respectively, to the resources currently being requested.\n

\nEach API request will also return a pagination object with details about your current pagination state based on the parameters provided. The pagination object contains:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
KeyTypeDescription
next_page_tokenstringThe token used to request the next page in paginated results. If no page token is included, the first page contains all results.
next_page_urlstringURL containing the next page and the limit provided in the original API request, to be used to continue sequentially accessing resources. Only displays when another page can be accessed.
\n
\n

Following is a formatted example of the pagination object in an API response:
\n

\n
\n\"pagination\": {\n  \"next_page_url\": \"https://api.huntress.io/v1/agents?page_token=MjAyMi0wMy0wMVQxODo1NDoyNFo&limit=10\",\n  \"next_page_token\": \"MjAyMi0wMy0wMVQxODo1NDoyNFo\"\n}
\n
\n
\n
\n\t

Request and Response Format

\n\t
\n\t\t

Request

\n\t
\n
\ncurl \"https://api.huntress.io/v1/agents?organization_id=1&page_token=MjAyMi0wMy0wMVQxODo1NDoyNFo\" -H \"Authorization: Basic <Your B64 encoded hash>\"
\n\t

The base URL for API requests is api.huntress.io/v1/, followed by the resource requested. Resources can be requested either singularly or as a list, which correspond to /v1/<resources>/:id or /v1/<resources> respectively, with the exception of the /v1/account and /v1/actor endpoints, which only returns the account associated with the API credentials provided.

\n\t

As an example, api.huntress.io/v1/agents would return a list of agents, while api.huntress.io/v1/agents/1 would return a singular agent with ID: 1.

\n\t

Parameters are provided to the API through a query string. As an example, providing the organization_id filter as a parameter to the /v1/agents endpoint would look like api.huntress/io/v1/agents?organization_id=1. Accessing a sequential page with the same filter active would look like api.huntress.io/v1/agents?organization_id=1&page_token=MjAyMi0wMy0wMVQxODo1NDoyNFo.

\n\t
\n\t
\n\t\t

Response

\n\t

The Huntress API responds with a JSON object containing requested resources if the request is valid and authorized.

\n\t

Singular Case

\n\t
\n\t
{\n  \"report\": { ... }\n}\n
\n\t

In the case of accessing a singular resource, the JSON object in question will contain one key that maps the singular resource to the singular representation of the resource name. As an example, if you were to request api.huntress.io/v1/reports/1, the JSON response would contain a single key report that maps to the report with ID: 1.

\n\t

Multiple Case

\n
{\n  \"reports\": [ ... ],\n  \"pagination\": { ... }\n}\n
\n\t

When accessing a list of resources, the JSON response contains two keys at the root level. The first key is the plural representation of that resource. The second is a pagination key that represents the current state of pagination based on parameters provided in the original request. As an example, a request to api.huntress.io/v1/reports returns a JSON object with the keys reports and pagination at its root level. Further details on the fields within the pagination object can be seen at the relevant section.

\n\t
\n
\n" version: 1.0.0 host: api.huntress.io schemes: - https produces: - application/json 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.\n\n**Note:** This endpoint will also return a `pagination` key on the root level. \nPlease refer to the [pagination section](https://api.huntress.io/docs#pagination) within our docs for more information.\n" produces: - application/json 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. type: integer format: int32 default: 10 minimum: 1 maximum: 500 required: false - in: query name: page_token description: Token used to request the next page in paginated results. Defaults to 'null' type: string required: false - in: query name: sort_field description: Field to sort by. Defaults to 'id'. type: string default: id enum: - id - created_at - updated_at required: false - in: query name: sort_direction description: Sort direction. Defaults to 'desc'. type: string default: desc enum: - asc - desc required: false - 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. type: string required: false - 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. type: string required: false - in: query name: organization_id description: Filter by organization ID within Huntress account type: integer format: int32 required: false - in: query name: type description: Filter by report type. One of monthly_summary, quarterly_summary, yearly_summary type: string enum: - monthly_summary - quarterly_summary - yearly_summary required: false responses: '200': description: List Summary Reports schema: type: object properties: reports: type: array items: $ref: '#/definitions/SummaryReport' pagination: $ref: '#/definitions/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. produces: - application/json parameters: - in: path name: id description: Report ID within Huntress account type: integer format: int32 required: true responses: '200': description: Get Summary Report schema: type: object properties: report: $ref: '#/definitions/SummaryReport' '403': description: There was an issue with your API credential or permissions. tags: - Summary Reports operationId: getV1ReportsId definitions: Pagination: type: object properties: next_page_url: type: string next_page_token: type: string description: Pagination model 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. 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: '#/definitions/ReportIncidentRemediation' description: Remediation actions taken for this incident. 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: '#/definitions/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: '#/definitions/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: '#/definitions/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: '#/definitions/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 ReportIncidentRemediation: type: object properties: type: type: string example: Remediations::SessionRevocation description: The remediation type. subtype: type: string example: containment description: The remediation action category. securityDefinitions: basic_auth: type: basic desc: Base 64 encoded string of your Huntress Account API key and API secret.