---
title: "Investigations: Get usage"
method: GET
path: "/v3/threat-hunting/investigations/usage"
tags: ["Threat Hunting", "Adversary Investigation"]
---

# Investigations: Get usage

`GET /v3/threat-hunting/investigations/usage`

## Request

- Base URL: `https://api.platform.censys.io`
- URL: `https://api.platform.censys.io/v3/threat-hunting/investigations/usage`
- Auth: HTTP bearer

Retrieve your organization's investigation limit, current usage, and the number of remaining investigations.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module.<br><br>This endpoint does not cost any credits to execute.

## Query parameters

- `organization_id` string, uuid, required: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.

## Headers

- `X-Organization-ID` string, uuid: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.

## Response `200`

Investigation usage retrieved successfully

- ResponseEnvelopeInvestigationUsage
  - `result` InvestigationUsage
    - `limit` integer, required: Maximum new investigations allowed per organization in the rolling window.
    - `next_expire_time` string, date-time: When the oldest counted start reaches the end of the rolling window and stops counting. This expires one start, it does not reset the allowance, and it is reported whenever any start is counted rather than only when remaining is zero. Omitted when used is zero.
    - `remaining` integer, required: Additional new investigations available, never less than zero. This is a snapshot, not a reservation.
    - `used` integer, required: New investigations started by all organization members through the UI and API within the rolling window.
    - `window_seconds` integer, required: Duration of the rolling allowance window in seconds.

## Other responses

- `401`: Request does not contain a valid Authorization token
- `403`: User does not have permission to access this data
- `409`: Feature not enabled
- `422`: Invalid input
- `500`: Internal server error

## Changes

- **2026-11-03** `ec1686b0a36a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/censys/apis/censys-platform-api/changes/v3/threat-hunting/investigations/usage/get.md)

---

[API](https://skmtc.dev/censys/apis/censys-platform-api.md) - [All operations](https://skmtc.dev/censys/apis/censys-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/censys/apis/censys-platform-api/revisions/ec1686b0a36a?raw)