CEcensys
Threat Hunting
Adversary Investigation

Investigations: Create job

Changed on

Start an AI investigation 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.<br><br>Supply at least one indicators or file_ids. To use files, upload them first with the create file upload endpoint.<br><br>This endpoint returns a job_id that you can poll to retrieve its status and results.<br><br>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.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module.

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

Query parameters

organization_idstring uuid required

The ID of a Censys organization to associate the request with. See the Getting Started docs for more information.

Example:11111111-2222-3333-4444-555555555555

Headers

X-Organization-IDstring uuid

The ID of a Censys organization to associate the request with. See the Getting Started docs for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.

Example:11111111-2222-3333-4444-555555555555

Request body

end_timestring 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_idsstring[] 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.

indicatorsstring[] 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_timestring 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.

Example request

{
  "end_time": "2026-08-01T00:00:00Z",
  "file_ids": [
    "file_550e8400-e29b-41d4-a716-446655440000"
  ],
  "indicators": [
    "1.1.1.1",
    "example.com"
  ],
  "start_time": "2026-06-01T00:00:00Z"
}

Response

Investigation started successfully

Example response

{
  "result": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "state": "completed"
  }
}

Changes