--- title: "Investigations: Create job" method: POST path: "/v3/threat-hunting/investigations/jobs" tags: ["Threat Hunting", "Adversary Investigation"] --- # Investigations: Create job `POST /v3/threat-hunting/investigations/jobs` ## Request - Base URL: `https://api.platform.censys.io` - URL: `https://api.platform.censys.io/v3/threat-hunting/investigations/jobs` - Auth: HTTP bearer Start an [AI investigation](https://docs.censys.com/docs/platform-ai-investigations) from a set of indicators, a set of previously uploaded evidence files, or both to obtain a report on suspect infrastructure without doing the pivots by hand.

Supply at least one `indicators` or `file_ids`. To use files, upload them first with the [create file upload endpoint](https://docs.censys.com/reference/v3-threathunting-investigations-files-create).

This endpoint returns a `job_id` that you can poll to retrieve its status and results.

Provide `start_time` and `end_time` to scope the investigation to a time frame, or `start_time` alone to scope it from that time up to now. Omit both to investigate current data.

To use this endpoint, your organization must have access to the Adversary Investigation module. ## 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. ## Request body - CreateInvestigationJobInputBody - `end_time` string, date-time: End of the reported timeframe, as an RFC 3339 timestamp. Inclusive. Requires start_time and must not be before it. It may not be in the future; omit it to scope the investigation up to now. Equal bounds scope the investigation to that single instant. - `file_ids` string[], nullable: Evidence files to investigate, identified by the file_id returned when each upload was prepared. The most that one investigation accepts is set by the service and can change. A file is meant for one investigation. A later job naming the same file is rejected, though as with a retried create, two requests sent at the same instant may both be accepted. An identifier that was never uploaded, or that belongs to someone else, returns an unprocessable entity response. May be omitted when indicators is supplied. - `indicators` string[], nullable: The indicators to investigate. Can be IP addresses, domains, or host and port pairs. Each must be a single non-empty value. May be omitted when file_ids is provided. The maximum number of indicators you can submit is 100. - `start_time` string, date-time: Start of the reported timeframe to scope the investigation to, as an RFC 3339 timestamp. Inclusive, and must be in the past. Omit both start_time and end_time to investigate current data. Supplying start_time on its own scopes the investigation from that instant up to now, which is how an open-ended report is expressed. ## Response `202` Investigation started successfully - ResponseEnvelopeCreatedInvestigationJob - `result` CreatedInvestigationJob - `complete_time` string, date-time: When the investigation finished. Omitted while it is still running. - `create_time` string, date-time, required: When the investigation was started. - `end_time` string, date-time: End of the reported timeframe, echoed from the request that started it. Omitted when the request left it open, in which case the investigation was scoped up to the moment it started. The investigation does not store it, so it is returned only here and never by a later read. - `expire_time` string, date-time: When the investigation and its results stop being available for download. - `job_id` string, uuid, required: The unique identifier of the investigation. - `start_time` string, date-time: Start of the reported timeframe this investigation was scoped to, echoed from the request that started it. Omitted when the investigation uses current data. The investigation does not store it, so it is returned only here and never by a later read. - `state` 'started' | 'completed' | 'failed' | 'unknown', required: The current state of the investigation. Completed means the investigation succeeded, not that its results are still available to download, and unknown means only that this API is older than the state the service reported. - `title` string: A short description of what the investigation looked into. Omitted when the investigation has no title yet. ## 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 - `413`: Request body too large - `422`: Invalid input - `429`: Too many investigations running, or the organization's allowance is spent - `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/jobs/post.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)