NAV
shell

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": "00000000-0000-0000-0000-000000000000",
        "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": "00000000-0000-0000-0000-000000000000",
            "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": "00000000-0000-0000-0000-000000000000",
            "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": "00000000-0000-0000-0000-000000000000",
            "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"
    }
}

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"
        },
        ...
        {
            "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"
        }
    ],
    "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.

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 ThreatOps 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 ThreatOps 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 ThreatOps 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>.