Introduction

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.

To test out the Huntress APIs quickly, use the Swagger Interface. You can also navigate there directly by clicking the "Preview the API (Swagger)" link.

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

API Overview

Authentication

$KEY = echo "$HUNTRESS_PUBLIC_KEY:$HUNTRESS_PRIVATE_KEY" | base64

curl "https://api.huntress.io/v1/agents" \
  -H "Authorization: Basic $KEY"

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.

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.

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.

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.

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.

Rate Limits

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.

As an example for developers unfamiliar with this structure, 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 request 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.

HTTP Response Codes

Response Code	Details
200	Request is okay, response is okay.
400	There is an unexpected value in the API request being made.
404	The requested resource is unavailable to you, either because it doesn't exist or because your account does not hold permissions to access it.
429	You have made too many requests within the rate limit timeframe.
500	An error has occurred on the Huntress API. Please contact support with details of your error.

Pagination

"pagination": {
    "current_page": 1,
    "current_page_count": 10,
    "limit": 10,
    "total_count": 20,
    "next_page": 2,
    "next_page_url": "https://api.huntress.io/v1/agents?page=2&limit=10"
}

The Huntress API utilizes a page and limit parameter to specify a window location and size, respectively, to the resources currently being accessed. By default, not specifying a page and limit argument to an API call defaults these values to page=1 and limit=10, which corresponds to the first 10 results within the resource set you are attempting to access. Note that the minimum value of limit is 1 and the maximum value is 500. Providing a value outside of this range will result in a 400 response.

Each API call will also return a pagination object with details about your current pagination state based on the parameters provided when making the API call. The pagination object contains:

Key	Type	Description
current_page	integer	The current page that this API request is accessing.
current_page_count	integer	The number of items returned on this page.
limit	integer	The number of results returned within this request.
total_count	integer	The total number of results for the resource being accessed.
next_page	integer	The next page number to use in another request in order to continue sequentially accessing resources. Only displays when another page can be accessed.
next_page_url	string	URL containing the next page and the limit provided in the original API request, to be used to continue sequentially accessing resources.

Request and Response Format

Request

curl "https://api.huntress.io/v1/agents?organization_id=1&page=2" \
  -H "Authorization: Basic <Your B64 encoded hash>"

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 endpoint, which only returns the account associated with the API credentials provided.

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.

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 second page with the same filter active would look like api.huntress.io/v1/agents?organization_id=1&page=2.

Response

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

Singular Case

{

  "report": {...}
}

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.

Multiple Case

{
  "reports": [...],
  "pagination": {...}
}

In the case of accessing a list of resources, the JSON response will contain two keys at its root level. The first is the plural representation fo the resource in question. 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.

API Resources

Account

Request

curl "https://api.huntress.io/v1/account" \
  -H "Authorization: Basic <Your B64 encoded hash>"

Response

{
    "account": {
        "id": 1,
        "name": "Your Account Name",
        "subdomain": "exampleaccount",
        "status": "active"
    }
}

The account endpoint shows details of the account associated with your API credentials.

An account is structured as:

Key	Type	Description
id	integer	A unique identifier for the account.
name	string	The public facing display name for the account.
subdomain	string	The subdomain for the account.
status	string	The current status on the account. Can be one of `<enabled, disabled>`.

No additional parameters are available for this endpoint.

Organizations

Request

curl "https://api.huntress.io/v1/organizations/1" \
  -H "Authorization: Basic <Your B64 encoded hash>"

Response

{
    "organization": {
        "id": 1,
        "name": "Test",
        "created_at": "2022-03-01T18:54:02Z",
        "updated_at": "2022-03-01T18:54:02Z",
        "account_id": 5,
        "key": "test1",
        "microsoft_365_tenant_id": "dcd219dd-bc68-4b9b-bf0b-4a33a796be35",
        "notify_emails": [],
        "incident_reports_count": 42,
        "agents_count": 42,
        "microsoft_365_users_count": 42
    }
}

Request

curl "https://api.huntress.io/v1/organizations" \
  -H "Authorization: Basic <Your B64 encoded hash>"

Response

{
    "organizations": [
        {
            "id": 1,
            "name": "Test",
            "created_at": "2022-03-01T18:54:02Z",
            "updated_at": "2022-03-01T18:54:02Z",
            "account_id": 5,
            "key": "test1",
            "microsoft_365_tenant_id": "dcd219dd-bc68-4b9b-bf0b-4a33a796be35",
            "notify_emails": ["test@example.com"],
            "incident_reports_count": 42,
            "agents_count": 42,
            "microsoft_365_users_count": 42
        },
        {
            "id": 2,
            "name": "Test 2",
            "created_at": "2022-03-01T18:54:16Z",
            "updated_at": "2022-03-01T18:54:16Z",
            "account_id": 5,
            "key": "test2",
            "microsoft_365_tenant_id": "dcd219dd-bc68-4b9b-bf0b-4a33a796be35",
            "notify_emails": [],
            "incident_reports_count": 42,
            "agents_count": 42,
            "microsoft_365_users_count": 42
        },
        ...
        {
            "id": 10,
            "name": "Test 10",
            "created_at": "2022-03-01T18:54:24Z",
            "updated_at": "2022-03-01T18:54:24Z",
            "account_id": 5,
            "key": "test10",
            "microsoft_365_tenant_id": "dcd219dd-bc68-4b9b-bf0b-4a33a796be35",
            "notify_emails": [],
            "incident_reports_count": 42,
            "agents_count": 42,
            "microsoft_365_users_count": 42
        }
    ],
    "pagination": {
        "current_page": 1,
        "current_page_count": 10,
        "limit": 10,
        "total_count": 32
    }
}

The organizations endpoint shows details of organizations belonging to the account associated with your API credentials.

Organizations are accessible via both the /v1/organizations endpoint to list accessible organizations and the /v1/organizations/:id endpoint to show a single organization by ID.

An organization is structured as:

Key	Type	Description
id	integer	The Huntress internal ID for this organization.
name	string	The public facing name for this organization.
created_at	string	A timestamp for when the organization was created, formatted as per ISO8601.
updated_at	string	A timestamp for when the organization was last updated, formatted as per ISO8601.
account_id	integer	The unique identifier of the account associated with the orgnaization.
key	string	The subdomain associated with the organization.
microsoft_365_tenant_id	string	The Microsoft 365 Tenant ID associated with the organization
notify_emails	array	A list of emails the organization is configured to send emails to when notifications are sent.
incident_reports_count	integer	Number of incident reports for the organization.
agents_count	integer	Number of agents for the organization.
microsoft_365_users_count	integer	Number of billable Microsoft 365 users for the organization.

The /v1/organizations endpoint accepts the following optional parameters:

Parameter	Type	Description
page	integer	The window location for the current resource. In conjunction with the `limit` field, shows results beginning with `page * limit` up to `(page + 1) * limit`. Must be an integer greater than 0 or a 400 error will occur.
limit	integer	The number of elements to show per page. Must be an integer between 1 and 500, otherwise a 400 error will occur.
created_at_min	string	An ISO8601 formatted date string representing the lower bound of the search range for the created_at date. Must provide a date greater than January 1st, 2010 or a 400 error will occur.
created_at_max	string	An ISO8601 formatted date string representing the upper bound of the search range for the created_at date. If provided with `created_at_min`, `created_at_max` must be greater than `created_at_min` or a 400 error will occur.
updated_at_min	string	An ISO8601 formatted date string representing the lower bound of the search range for the updated_at date. Must provide a date greater than January 1st, 2010 or a 400 error will occur.
updated_at_max	string	An ISO8601 formatted date string representing the upper bound of the search range for the updated_at date. If provided with `updated_at_min`, `updated_at_max` must be greater than `updated_at_min` or a 400 error will occur.

Agents

Request

curl "https://api.huntress.io/v1/agents/1" \
  -H "Authorization: Basic <Your B64 encoded hash>"

Response

{
    "agent": {
        "id": 1,
        "version": "0.11.3",
        "arch": "x86_64",
        "win_build_number": null,
        "domain_name": null,
        "created_at": "2022-03-01T20:05:10Z",
        "hostname": "laptop01",
        "ipv4_address": "146.134.139.9",
        "external_ip": null,
        "mac_addresses": ["7c:a7:b0:16:2f:78", ...],
        "updated_at": "2022-03-01T20:05:10Z",
        "last_survey_at": null,
        "last_callback_at": "2022-03-01T20:05:10Z",
        "account_id": 5,
        "organization_id": 7,
        "platform": "windows",
        "os": "Windows 8 Pro",
        "service_pack_major": 0,
        "service_pack_minor": 0,
        "tags": [],
        "os_major": 6,
        "os_minor": 2,
        "os_patch": 0,
        "version_number": 720899,
        "edr_version": "0.3.20",
        "os_build_version": 19044,
        "serial_number": "wtIe1bvDbh",
        "defender_status": "Healthy",
        "defender_substatus": "Up to date",
        "defender_policy_status": "Compliant"
    }
}

Request

curl "https://api.huntress.io/v1/agents" \
  -H "Authorization: Basic <Your B64 encoded hash>"

Response

{
    "agents": [
        {
            "id": 1,
            "version": "0.11.3",
            "arch": "x86_64",
            "win_build_number": null,
            "domain_name": null,
            "created_at": "2022-03-01T20:05:10Z",
            "hostname": "laptop01",
            "ipv4_address": "146.134.139.9",
            "external_ip": null,
            "mac_addresses": ["7c:a7:b0:16:2f:78", ...],
            "updated_at": "2022-03-01T20:05:10Z",
            "last_survey_at": null,
            "last_callback_at": "2022-03-01T20:05:10Z",
            "account_id": 5,
            "organization_id": 7,
            "platform": "windows",
            "os": "Windows 8 Pro",
            "service_pack_major": 0,
            "service_pack_minor": 0,
            "tags": [],
            "os_major": 6,
            "os_minor": 2,
            "os_patch": 0,
            "version_number": 720899,
            "edr_version": "0.3.20",
            "os_build_version": 19044,
            "serial_number": "wtIe1bvDbh",
            "defender_status": "Healthy",
            "defender_substatus": "Up to date",
            "defender_policy_status": "Compliant"
        },
        ...
        {
            "id": 10,
            "version": "0.11.3",
            "arch": "x86_64",
            "win_build_number": null,
            "domain_name": null,
            "created_at": "2022-03-01T20:06:03Z",
            "hostname": "laptop01",
            "ipv4_address": "71.136.18.183",
            "external_ip": null,
            "mac_addresses": ["7c:a7:b0:16:2f:78", ...],
            "updated_at": "2022-03-01T20:06:03Z",
            "last_survey_at": null,
            "last_callback_at": "2022-03-01T20:06:03Z",
            "account_id": 5,
            "organization_id": 16,
            "platform": "windows",
            "os": "Windows 8 Pro",
            "service_pack_major": 0,
            "service_pack_minor": 0,
            "tags": [],
            "os_major": 6,
            "os_minor": 2,
            "os_patch": 0,
            "version_number": 720899,
            "edr_version": "0.3.20",
            "os_build_version": 19044,
            "serial_number": "wtIe1bvDbh",
            "defender_status": "Healthy",
            "defender_substatus": "Up to date",
            "defender_policy_status": "Compliant"
        }
    ],
    "pagination": {
        "current_page": 1,
        "current_page_count": 10,
        "limit": 10,
        "total_count": 10
    }
}

The agents endpoint shows agents associated with your account.

An agent is structured as:

Key	Type	Description
id	integer	A unique identifier for an agent.
version	string	The semantic versioning number of the agent installed on the host machine.
arch	string	The architecture on the host machine.
win_build_number	integer	The Windows Build Number. Should correspond to information on the Microsoft site.
domain_name	string	Domain that refers to the host machine.
created_at	string	A timestamp for when the agent was created, formatted as per ISO8601.
hostname	string	The hostname of the host machine.
ipv4_address	string	The internal IP of the host machine.
external_ip	string	The external IP of the host machine, if applicable.
mac_addresses	array	The unique media access control (MAC) addresses associated with the agent.
updated_at	string	A timestamp for when the agent was last updated, formatted as per ISO8601.
last_survey_at	string	A timestamp for when the last Microsoft Defender survey was received by Huntress for this host machine.
last_callback_at	string	A timestamp for when the last time Huntress was able to access the host machine.
account_id	integer	The unique identifier of the account associated with the agent.
organization_id	integer	The unique identifier of the organization associated with the agent.
platform	string	The platform of the host machine (`darwin` or `windows`).
os	string	The operating system of the host machine.
service_pack_major	integer	The major version of the Windows service pack installed on the host machine.
service_pack_minor	integer	The minor version of the Windows service pack installed on the host machine.
tags	array	User classifications on the host machine.
os_major	integer	The major OS version of the host machine. Corresponds with the major releases of Windows operating systems. A list is accessible here.
os_minor	integer	The minor OS version of the host machine. Refer to the `os_major` field details for further details.
os_patch	integer	The patch version of the macOS update installed on the host machine, such as 1 in version 12.5.1.
version_number	integer	Windows version number.
edr_version	string	The semantic versioning number of the Huntress EDR software installed on the machine or `null` if EDR is not installed.
os_build_version	string	The operating system build number of the host machine corresponding to its platform (windows or darwin).
serial_number	string	The serial number of the host machine as reported to the operating system.
defender_status	string	Status of Defender AV Managed Antivirus.
defender_substatus	string	Sub-status of Defender AV Managed Antivirus.
defender_policy_status	string	Policy status of Defender AV for Managed Antivirus.

The /v1/agents endpoint accepts the following optional parameters:

Parameter	Type	Description
page	integer	The window location for the current resource. In conjunction with the `limit` field, shows results beginning with `page * limit` up to `(page + 1) * limit`. Must be an integer greater than 0 or a 400 error will occur.
limit	integer	The number of elements to show per page. Must be an integer between 1 and 500, otherwise a 400 error will occur.
created_at_min	string	An ISO8601 formatted date string representing the lower bound of the search range for the created_at date. Must provide a date greater than January 1st, 2010 or a 400 error will occur.
created_at_max	string	An ISO8601 formatted date string representing the upper bound of the search range for the created_at date. If provided with `created_at_min`, `created_at_max` must be greater than `created_at_min` or a 400 error will occur.
updated_at_min	string	An ISO8601 formatted date string representing the lower bound of the search range for the updated_at date. Must provide a date greater than January 1st, 2010 or a 400 error will occur.
updated_at_max	string	An ISO8601 formatted date string representing the upper bound of the search range for the updated_at date. If provided with `updated_at_min`, `updated_at_max` must be greater than `updated_at_min` or a 400 error will occur.
organization_id	integer	The unique identifier of an organization under the account associated with your API credentials. Will only select agents under this organization.
platform	string	The platform of the host machine (`darwin` or `windows`).

Incident Reports

Request

curl "https://api.huntress.io/v1/incident_reports/1" \
  -H "Authorization: Basic <Your B64 encoded hash>"

Response

{
    "incident_report": {
        "id": 1,
        "status": "closed",
        "summary": null,
        "body": "<Content>",
        "updated_at": "2022-03-01T20:31:30Z",
        "agent_id": 12,
        "status_updated_at": null,
        "organization_id": 4,
        "sent_at": null,
        "account_id": 5,
        "subject": "LOW - Incident on laptop01 (Test)",
        "created_by_id": null,
        "remediation_instructions": null,
        "footholds": "<Content>",
        "severity": "low",
        "assigned_to_id": null,
        "closed_at": null,
        "indicator_types": [
            "footholds"
        ],
        "indicator_counts": {
            "footholds": 1,
            "monitored_files": 0,
            "process_detections": 0,
            "ransomware_canaries": 0,
            "antivirus_detections": 0
        },
        "details": {}
    }
}

Request

curl "https://api.huntress.io/v1/incident_reports" \
  -H "Authorization: Basic <Your B64 encoded hash>"

Response


{
    "incident_reports": [
        {
            "id": 1,
            "status": "closed",
            "summary": null,
            "body": "<Content>",
            "updated_at": "2022-03-01T20:31:30Z",
            "agent_id": 12,
            "platform": "windows",
            "status_updated_at": null,
            "organization_id": 4,
            "sent_at": null,
            "account_id": 5,
            "subject": "LOW - Incident on laptop01 (Test)",
            "created_by_id": null,
            "remediation_instructions": null,
            "footholds": "<Content>",
            "notes": "<Content>",
            "severity": "low",
            "assigned_to_id": null,
            "closed_at": null,
            "indicator_types": [
                "footholds"
            ],
            "indicator_counts": {
                "footholds": 1,
                "monitored_files": 0,
                "process_detections": 0,
                "ransomware_canaries": 0,
                "antivirus_detections": 0
            },
            "details": {}
        },
        {
            "id": 2,
            "status": "closed",
            "summary": null,
            "body": "<Content>",
            "updated_at": "2022-03-01T20:31:59Z",
            "agent_id": 13,
            "status_updated_at": null,
            "organization_id": 4,
            "sent_at": null,
            "account_id": 5,
            "subject": "LOW - Incident on laptop01 (Test)",
            "created_by_id": null,
            "remediation_instructions": null,
            "footholds": "<Content>",
            "severity": "low",
            "assigned_to_id": null,
            "closed_at": null,
            "indicator_types": [
                "footholds"
            ],
            "indicator_counts": {
                "footholds": 1,
                "monitored_files": 0,
                "process_detections": 0,
                "ransomware_canaries": 0,
                "antivirus_detections": 0
            },
            "details": {}
        }
    ],
    "pagination": {
        "current_page": 1,
        "current_page_count": 2,
        "limit": 10,
        "total_count": 2
    }
}

An incident report is structured as:

Key	Type	Description
id	integer	Unique identifier for the incident report.
status	string	Status of the incident report. Can be one of `<sent, closed, dismissed>`
summary	string	Details of the incident report, as provided by a Huntress SOC analyst.
body	string	Autogenerated content describing the details of the incident in question.
updated_at	string	ISO8601 formatted timestamp for when this incident report was last updated.
agent_id	integer	Unique identifier for the agent this incident report is associated with.
platform	string	The platform of the host machine (`darwin` or `windows` or `microsoft_365`).
status_updated_at	string	ISO8601 formatted timestamp for when the status of this incident report was last updated.
organization_id	integer	Unique identifier for the organization this incident report is associated with.
sent_at	string	ISO8601 formatted timestamp for when a Huntress SOC analyst has notified necessary parties regarding this incident report. Null if not sent.
account_id	integer	Unique identifier for the account this incident report is associated with.
subject	string	Autogenerated one-line description of the incident.
created_by_id	integer	Unique identifier for the user that created the incident report.
remediation_instructions	string	Details provided by Huntress SOC analysts for how to resolve the issues noted in the incident report.
footholds	string	Details on footholds found within the scope of this incident report.
severity	string	The severity of the incident report. Can be one of `<low, high, critical>`.
assigned_to_id	integer	Unique identifier for the user that is assigned to this incident report.
closed_at	string	ISO8601 formatted timestamp for when this incident report had its status set to `closed`. Null if non-applicable.
indicator_types	array	Unique list of threat indicators that have been found in the context of this incident report.
indicator_counts	object	Mapping of indicator types to number of incidences of that threat in the context of this incident report.
details	object	Additional details attached to this report.

The /v1/incident_reports endpoint takes the following optional parameters:

Key	Type	Description
page	integer	The window location for the current resource. In conjunction with the `limit` field, shows results beginning with `page * limit` up to `(page + 1) * limit`. Must be an integer greater than 0 or a 400 error will occur.
limit	integer	The number of elements to show per page. Must be an integer between 1 and 500, otherwise a 400 error will occur.
updated_at_min	string	An ISO8601 formatted date string representing the lower bound of the search range for the updated_at date. Must provide a date greater than January 1st, 2010 or a 400 error will occur.
updated_at_max	string	An ISO8601 formatted date string representing the upper bound of the search range for the updated_at date. If provided with `updated_at_min`, `updated_at_max` must be greater than `updated_at_min` or a 400 error will occur.
status	string	The status of the incident report. Must be one of `<sent, closed, dismissed>`. Will return only incident reports matching the status provided.
severity	string	The severity of the incident report. Must be one of `<low, high, critical>`. Will return only incident reports matching the severity provided.
organization_id	integer	The unique identifier of an organization under the account associated with your API credentials. Will only select incident reports under this organization.
agent_id	integer	The unique identifier of an agent under the account associated with your API credentials. Will only select incident reports under this organization.
platform	string	The platform of the host machine (`darwin` or `windows` or `microsoft_365`).
indicator_type	string	An indicator type to filter reports by. Must be one of `<footholds, monitored_files, ransomware_canaries, antivirus_detections, process_detections, managed_identity>`. Will return only incident reports whose indicator types include the specified value.

Summary Reports

Request

curl "https://api.huntress.io/v1/reports/1" \
  -H "Authorization: Basic <Your B64 encoded hash>"

Response


{
    "report": {
        "id": 1,
        "type": "monthly_summary",
        "period": "2022-02-01...2022-03-02",
        "organization_id": null,
        "created_at": "2022-03-01T20:56:15Z",
        "updated_at": "2022-03-01T20:56:15Z",
        "url": "https://huntress.io/rails/active_storage/blobs/redirect/uuid.pdf?disposition=download"
    }
}

Request

curl "https://api.huntress.io/v1/reports" \
  -H "Authorization: Basic <Your B64 encoded hash>"

Response


{
    "reports": [
        {
            "id": 1,
            "type": "monthly_summary",
            "period": "2022-02-01...2022-03-02",
            "organization_id": null,
            "created_at": "2022-03-01T20:56:15Z",
            "updated_at": "2022-03-01T20:56:15Z",
            "url": "https://huntress.io/rails/active_storage/blobs/redirect/uuid.pdf?disposition=download"
        },
        {
            "id": 2,
            "type": "monthly_summary",
            "period": "2022-02-01...2022-03-02",
            "organization_id": null,
            "created_at": "2022-03-01T20:56:20Z",
            "updated_at": "2022-03-01T20:56:20Z",
            "url": "https://huntress.io/rails/active_storage/blobs/redirect/uuid.pdf?disposition=download"
        }
    ],
    "pagination": {
        "current_page": 1,
        "current_page_count": 2,
        "limit": 10,
        "total_count": 2
    }
}

A summary report is structured as:

Key	Type	Description
id	integer	A unique identifier for the summary report.
type	string	The report type. Can be one of `<monthly_summary, quarterly_summary, yearly_summary>`.
period	string	A date range representing the coverage of the report, formatted as `start_date...end_date`.
organization_id	integer	Unique identifier for the organization this summary report is associated with.
created_at	string	ISO8601 formatted timestamp for when this summary report was created.
updated_at	string	ISO8601 formatted timestamp for when this summary report was last updated.
url	string	The direct url to the pdf version of this summary report.

The /v1/reports endpoint takes the following optional parameters:

Key	Type	Description
page	integer	The window location for the current resource. In conjunction with the `limit` field, shows results beginning with `page * limit` up to `(page + 1) * limit`. Must be an integer greater than 0 or a 400 error will occur.
limit	integer	The number of elements to show per page. Must be an integer between 1 and 500, otherwise a 400 error will occur.
created_at_min	string	An ISO8601 formatted date string representing the lower bound of the search range for the created_at date. Must provide a date greater than January 1st, 2010 or a 400 error will occur.
created_at_max	string	An ISO8601 formatted date string representing the upper bound of the search range for the created_at date. If provided with `created_at_min`, `created_at_max` must be greater than `created_at_min` or a 400 error will occur.
updated_at_min	string	An ISO8601 formatted date string representing the lower bound of the search range for the updated_at date. Must provide a date greater than January 1st, 2010 or a 400 error will occur.
updated_at_max	string	An ISO8601 formatted date string representing the upper bound of the search range for the updated_at date. If provided with `updated_at_min`, `updated_at_max` must be greater than `updated_at_min` or a 400 error will occur.
period_min	string	An ISO860 formatted date string representing the lower bound of a filter window on the period field. Returns summary reports where the upper bound of the period is greater than `period_min`. If provided in conjunction with `period_max`, if `period_max` is less than `period_min`, a 400 error is returned.
period_max	string	An ISO860 formatted date string representing the upper bound of a filter window on the period field. Returns summary reports where the lower bound of the period is less than `period_max`.
organization_id	integer	The unique identifier of an organization under the account associated with your API credentials. Will only select summary reports associated with this organization.
type	string	The type of the summary report. Accepts `<monthly_summary, quarterly_summary, yearly_summary>`.

Billing Reports

Request

curl "https://api.huntress.io/v1/billing_reports/1" \
  -H "Authorization: Basic <Your B64 encoded hash>"

Response

{
    "billing_report": {
        "id": 1,
        "plan": "Huntress Partner 100 Agents",
        "quantity": 101,
        "amount": 303,
        "currency_type": "USD",
        "receipt": "https://pay.stripe/com/invoice/invst_uuid",
        "status": "paid",
        "created_at": "2022-03-01T20:56:15Z",
        "updated_at": "2022-03-01T20:56:15Z"
    }
}

Request

curl "https://api.huntress.io/v1/billing_reports" \
  -H "Authorization: Basic <Your B64 encoded hash>"

Response

{
    "billing_reports": [
        {
            "id": 1,
            "plan": "Huntress Partner 100 Agents",
            "quantity": 101,
            "amount": 303,
            "currency_type": "USD",
            "receipt": "https://pay.stripe/com/invoice/invst_uuid",
            "status": "paid",
            "created_at": "2022-03-01T20:56:15Z",
            "updated_at": "2022-03-01T20:56:15Z"
        },
            {
            "id": 2,
            "plan": "Huntress Partner 200 Agents",
            "quantity": 202,
            "amount": 606,
            "currency_type": "USD",
            "receipt": "https://pay.stripe/com/invoice/invst_uuid",
            "status": "paid",
            "created_at": "2022-03-01T20:56:15Z",
            "updated_at": "2022-03-01T20:56:15Z"
        }
    ],
    "pagination": {
        "current_page": 1,
        "current_page_count": 2,
        "limit": 10,
        "total_count": 2
    }

}

A billing report is structured as:

Key	Type	Description
id	integer	A unique identifier for the billing report.
plan	string	The corresponding name of huntress subscription plan sku.
quantity	integer	The total count of licensed agents accounted for in this billing report.
amount	integer	The Amount intended to be collected by this billing report. Mimics Stripe.
currency_type	string	The currency type. Can be one of `<USD, CAD, AUD>`.
receipt	string	A direct link to stripe payment invoice for this billing report.
status	string	The billing report status. Can be one of `<open, paid, failed, partial_refund, full_refund>`.
created_at	string	ISO8601 formatted timestamp for when this billing report was created.
updated_at	string	ISO8601 formatted timestamp for when this billing report was last updated.

The /v1/billing_reports endpoint takes the following optional parameters:

Key	Type	Description
page	integer	The window location for the current resource. In conjunction with the `limit` field, shows results beginning with `page * limit` up to `(page + 1) * limit`. Must be an integer greater than 0 or a 400 error will occur.
limit	integer	The number of elements to show per page. Must be an integer between 1 and 500, otherwise a 400 error will occur.
created_at_min	string	An ISO8601 formatted date string representing the lower bound of the search range for the created_at date. Must provide a date greater than January 1st, 2010 or a 400 error will occur.
created_at_max	string	An ISO8601 formatted date string representing the upper bound of the search range for the created_at date. If provided with `created_at_min`, `created_at_max` must be greater than `created_at_min` or a 400 error will occur.
updated_at_min	string	An ISO8601 formatted date string representing the lower bound of the search range for the updated_at date. Must provide a date greater than January 1st, 2010 or a 400 error will occur.
updated_at_max	string	An ISO8601 formatted date string representing the upper bound of the search range for the updated_at date. If provided with `updated_at_min`, `updated_at_max` must be greater than `updated_at_min` or a 400 error will occur.
status	string	The status of the billing report. Accepts `<open, paid, failed, partial_refund, full_refund>`.