> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/xsiam-api/forensics-1/forensics.md).

# Forensics

Public API endpoints for browsing forensic investigations, their hunt and triage collections, and the artifact data collected for them.

## List forensic investigations

> Returns all forensic investigations visible to the caller's scope.\
> \
> Required licenses: Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus with endpoints and the Forensics add-on.\
> RBAC permission: Forensics > View, which is included in the following built-in roles: Viewer, Investigator, Privileged Investigator, and Administrator.

```json
{"openapi":"3.0.2","info":{"title":"Cortex XSIAM Forensics REST API","version":"3.x"},"tags":[{"name":"Forensics","description":"Public API endpoints for browsing forensic investigations, their hunt and triage collections, and the artifact data collected for them."}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/forensics/investigations":{"post":{"summary":"List forensic investigations","description":"Returns all forensic investigations visible to the caller's scope.\n\nRequired licenses: Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus with endpoints and the Forensics add-on.\nRBAC permission: Forensics > View, which is included in the following built-in roles: Viewer, Investigator, Privileged Investigator, and Administrator.","operationId":"getForensicsInvestigations","tags":["Forensics"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","description":"Empty object. No request parameters are accepted.","additionalProperties":false}},"required":["request_data"]}}}},"responses":{"200":{"description":"List of investigations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvestigationsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"schemas":{"InvestigationsResponse":{"type":"object","properties":{"reply":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Investigation"}},"total_count":{"type":"integer"}}}}},"Investigation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"type":"string","description":"Email or identifier of the user that created the investigation."},"updated_by":{"type":"string","description":"Email or identifier of the user that last updated the investigation."},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["open","close_pending"]},"expires_at":{"type":"string","format":"date-time","nullable":true},"total_collections":{"type":"integer","nullable":true},"completed_collections":{"type":"integer","nullable":true}}}},"responses":{"BadRequest":{"description":"Invalid or missing parameters. Returned for example when a required id is missing or not a valid UUID v4, `artifact_type` is missing, pagination is out of range or the wrong type-specific id (`search_id` vs `agent_id`) is sent for the collection type.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Unauthorized":{"description":"Unauthorized access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Forbidden":{"description":"The caller does not have access to the requested investigation (out-of-scope).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"InternalError":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}
```

## List collections in an investigation

> Returns all hunt (scheduled/on-demand artifact searches across multiple endpoints) and triage (targeted artifact collections from specific endpoints) collections that belong to a specific investigation, grouped by type.\
> \
> Required licenses: Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus with endpoints and the Forensics add-on.\
> RBAC permission: Forensics > View, which is included in the following built-in roles: Viewer, Investigator, Privileged Investigator, and Administrator.

```json
{"openapi":"3.0.2","info":{"title":"Cortex XSIAM Forensics REST API","version":"3.x"},"tags":[{"name":"Forensics","description":"Public API endpoints for browsing forensic investigations, their hunt and triage collections, and the artifact data collected for them."}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/forensics/investigations/collections":{"post":{"summary":"List collections in an investigation","description":"Returns all hunt (scheduled/on-demand artifact searches across multiple endpoints) and triage (targeted artifact collections from specific endpoints) collections that belong to a specific investigation, grouped by type.\n\nRequired licenses: Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus with endpoints and the Forensics add-on.\nRBAC permission: Forensics > View, which is included in the following built-in roles: Viewer, Investigator, Privileged Investigator, and Administrator.","operationId":"getForensicsInvestigationCollections","tags":["Forensics"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","required":["investigation_id"],"properties":{"investigation_id":{"$ref":"#/components/schemas/InvestigationId"}}}},"required":["request_data"]}}}},"responses":{"200":{"description":"Collections grouped by type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"schemas":{"InvestigationId":{"type":"string","format":"uuid","description":"UUID v4 identifier of a forensic investigation."},"CollectionsResponse":{"type":"object","properties":{"reply":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CollectionsByType"},"total_count":{"type":"integer"}}}}},"CollectionsByType":{"type":"object","properties":{"hunts":{"type":"array","items":{"$ref":"#/components/schemas/HuntCollection"}},"triages":{"type":"array","items":{"$ref":"#/components/schemas/TriageCollection"}}}},"HuntCollection":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["hunt"]},"investigation_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"os":{"type":"string","description":"Operating system the collection targets (for example `WINDOWS`, `LINUX`, `MACOS`)."},"last_received_at":{"type":"integer","description":"Epoch-millisecond timestamp of the most recent result received for the collection."},"status":{"type":"string","nullable":true},"total_searches":{"type":"integer"},"searches":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Identifiers of the hunt searches belonging to this collection."}}},"TriageCollection":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["triage"]},"investigation_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"os":{"type":"string"},"last_received_at":{"type":"integer","description":"Epoch-millisecond timestamp of the most recent result received for the collection."},"status":{"type":"string","nullable":true},"total_agents":{"type":"integer"},"agents":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Identifiers of the agents that contributed data to this collection."}}}},"responses":{"BadRequest":{"description":"Invalid or missing parameters. Returned for example when a required id is missing or not a valid UUID v4, `artifact_type` is missing, pagination is out of range or the wrong type-specific id (`search_id` vs `agent_id`) is sent for the collection type.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Unauthorized":{"description":"Unauthorized access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Forbidden":{"description":"The caller does not have access to the requested investigation (out-of-scope).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"NotFound":{"description":"The referenced entity does not exist, or the relationship is invalid (collection not in investigation, agent not in triage, search not in collection).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"InternalError":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}
```

## List results of a hunt search

> Returns the summary results (one entry per artifact category, such as PERSISTENCE or EXECUTION, produced by the search) of a specific hunt search inside a hunt collection.\
> \
> Required licenses: Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus with endpoints and the Forensics add-on.\
> RBAC permission: Forensics > View, which is included in the following built-in roles: Viewer, Investigator, Privileged Investigator, and Administrator.

```json
{"openapi":"3.0.2","info":{"title":"Cortex XSIAM Forensics REST API","version":"3.x"},"tags":[{"name":"Forensics","description":"Public API endpoints for browsing forensic investigations, their hunt and triage collections, and the artifact data collected for them."}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/forensics/investigations/collections/hunt":{"post":{"summary":"List results of a hunt search","description":"Returns the summary results (one entry per artifact category, such as PERSISTENCE or EXECUTION, produced by the search) of a specific hunt search inside a hunt collection.\n\nRequired licenses: Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus with endpoints and the Forensics add-on.\nRBAC permission: Forensics > View, which is included in the following built-in roles: Viewer, Investigator, Privileged Investigator, and Administrator.","operationId":"getForensicsHuntResults","tags":["Forensics"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","required":["investigation_id","collection_id","search_id"],"properties":{"investigation_id":{"$ref":"#/components/schemas/InvestigationId"},"collection_id":{"allOf":[{"$ref":"#/components/schemas/CollectionId"}],"description":"Identifier of the hunt collection. Must reference a hunt-type collection that belongs to `investigation_id`."},"search_id":{"allOf":[{"$ref":"#/components/schemas/SearchId"}],"description":"Identifier of the hunt search whose results should be returned. Must belong to `collection_id`."}}}},"required":["request_data"]}}}},"responses":{"200":{"description":"Hunt result rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HuntResultsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"schemas":{"InvestigationId":{"type":"string","format":"uuid","description":"UUID v4 identifier of a forensic investigation."},"CollectionId":{"type":"string","format":"uuid","description":"UUID v4 identifier of a hunt or triage collection."},"SearchId":{"type":"string","format":"uuid","description":"UUID v4 identifier of a hunt search."},"HuntResultsResponse":{"type":"object","properties":{"reply":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HuntResult"}},"total_count":{"type":"integer"}}}}},"HuntResult":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"category":{"type":"string","description":"Logical category of the artifact returned by the search."},"artifact_type":{"type":"string","description":"Public name of the forensic artifact table that holds the result rows. Use this value as `artifact_type` when calling `/get_data`."},"filters":{"type":"object","description":"Search parameters that were applied to produce the result.","additionalProperties":true},"status":{"type":"string"},"total_results":{"type":"integer"}}}},"responses":{"BadRequest":{"description":"Invalid or missing parameters. Returned for example when a required id is missing or not a valid UUID v4, `artifact_type` is missing, pagination is out of range or the wrong type-specific id (`search_id` vs `agent_id`) is sent for the collection type.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Unauthorized":{"description":"Unauthorized access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Forbidden":{"description":"The caller does not have access to the requested investigation (out-of-scope).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"NotFound":{"description":"The referenced entity does not exist, or the relationship is invalid (collection not in investigation, agent not in triage, search not in collection).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"InternalError":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}
```

## List triage results for an agent

> Returns the artifact summaries collected from a specific endpoint agent inside a triage collection, separated into structured data artifacts (e.g., AMCACHE, REGISTRY) and collected-file artifacts (e.g., MFT, EVTX).\
> \
> Required licenses: Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus with endpoints and the Forensics add-on.\
> RBAC permission: Forensics > View, which is included in the following built-in roles: Viewer, Investigator, Privileged Investigator, and Administrator.

```json
{"openapi":"3.0.2","info":{"title":"Cortex XSIAM Forensics REST API","version":"3.x"},"tags":[{"name":"Forensics","description":"Public API endpoints for browsing forensic investigations, their hunt and triage collections, and the artifact data collected for them."}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/forensics/investigations/collections/triage":{"post":{"summary":"List triage results for an agent","description":"Returns the artifact summaries collected from a specific endpoint agent inside a triage collection, separated into structured data artifacts (e.g., AMCACHE, REGISTRY) and collected-file artifacts (e.g., MFT, EVTX).\n\nRequired licenses: Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus with endpoints and the Forensics add-on.\nRBAC permission: Forensics > View, which is included in the following built-in roles: Viewer, Investigator, Privileged Investigator, and Administrator.","operationId":"getForensicsTriageResults","tags":["Forensics"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","required":["investigation_id","collection_id","agent_id"],"properties":{"investigation_id":{"$ref":"#/components/schemas/InvestigationId"},"collection_id":{"allOf":[{"$ref":"#/components/schemas/CollectionId"}],"description":"Identifier of the triage collection. Must reference a triage-type collection that belongs to `investigation_id`."},"agent_id":{"allOf":[{"$ref":"#/components/schemas/AgentId"}],"description":"Identifier of the agent whose triage results should be returned. The agent must belong to `collection_id`."}}}},"required":["request_data"]}}}},"responses":{"200":{"description":"Triage artifact summaries grouped by type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TriageResultsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"schemas":{"InvestigationId":{"type":"string","format":"uuid","description":"UUID v4 identifier of a forensic investigation."},"CollectionId":{"type":"string","format":"uuid","description":"UUID v4 identifier of a hunt or triage collection."},"AgentId":{"type":"string","format":"uuid","description":"UUID v4 identifier of an endpoint agent."},"TriageResultsResponse":{"type":"object","properties":{"reply":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TriageResultsByType"},"total_count":{"type":"integer"}}}}},"TriageResultsByType":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TriageDataArtifactSummary"}},"files":{"type":"array","items":{"$ref":"#/components/schemas/TriageFileArtifactSummary"}}}},"TriageDataArtifactSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"integer","description":"Epoch-millisecond timestamp."},"artifact_type":{"type":"string"},"status":{"type":"string","description":"Normalised upper-case status (for example `COMPLETED`, `FAILED`)."},"total_results":{"type":"integer"}}},"TriageFileArtifactSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"integer","description":"Epoch-millisecond timestamp."},"artifact_type":{"type":"string"},"status":{"type":"string"},"successful_file_paths":{"type":"array","items":{"type":"string"},"description":"File paths that were collected successfully. Populated only when the artifact succeeded."},"failed_file_paths":{"type":"array","items":{"type":"string"},"description":"File paths that the agent failed to collect. Populated when the artifact did not succeed."},"total_files":{"type":"integer"},"total_results":{"type":"integer"}}}},"responses":{"BadRequest":{"description":"Invalid or missing parameters. Returned for example when a required id is missing or not a valid UUID v4, `artifact_type` is missing, pagination is out of range or the wrong type-specific id (`search_id` vs `agent_id`) is sent for the collection type.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Unauthorized":{"description":"Unauthorized access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Forbidden":{"description":"The caller does not have access to the requested investigation (out-of-scope).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"NotFound":{"description":"The referenced entity does not exist, or the relationship is invalid (collection not in investigation, agent not in triage, search not in collection).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"InternalError":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}
```

## Get artifact data rows from a collection

> Returns the actual collected artifact rows (records) for a hunt search or a triage agent.\
> \
> Exactly one of \`search\_id\` or \`agent\_id\` must be provided, matching the type of \`collection\_id\`:\
> \
> \- For a \*\*hunt\*\* collection, send \`search\_id\`.\
> \- For a \*\*triage\*\* collection, send \`agent\_id\`.\
> \
> Sending the wrong identifier for the collection type returns \`400 Bad Request\`.\
> \
> The per-row schema depends on the requested \`artifact\_type\` (e.g., registry keys, process execution logs) and is not enumerated in this document.\
> \
> Required licenses: Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus with endpoints and the Forensics add-on.\
> RBAC permission: Forensics > View, which is included in the following built-in roles: Viewer, Investigator, Privileged Investigator, and Administrator.

```json
{"openapi":"3.0.2","info":{"title":"Cortex XSIAM Forensics REST API","version":"3.x"},"tags":[{"name":"Forensics","description":"Public API endpoints for browsing forensic investigations, their hunt and triage collections, and the artifact data collected for them."}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/forensics/investigations/collections/get_data":{"post":{"summary":"Get artifact data rows from a collection","description":"Returns the actual collected artifact rows (records) for a hunt search or a triage agent.\n\nExactly one of `search_id` or `agent_id` must be provided, matching the type of `collection_id`:\n\n- For a **hunt** collection, send `search_id`.\n- For a **triage** collection, send `agent_id`.\n\nSending the wrong identifier for the collection type returns `400 Bad Request`.\n\nThe per-row schema depends on the requested `artifact_type` (e.g., registry keys, process execution logs) and is not enumerated in this document.\n\nRequired licenses: Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus with endpoints and the Forensics add-on.\nRBAC permission: Forensics > View, which is included in the following built-in roles: Viewer, Investigator, Privileged Investigator, and Administrator.","operationId":"getForensicsCollectionData","tags":["Forensics"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","required":["investigation_id","collection_id","artifact_type"],"properties":{"investigation_id":{"$ref":"#/components/schemas/InvestigationId"},"collection_id":{"$ref":"#/components/schemas/CollectionId"},"artifact_type":{"$ref":"#/components/schemas/ArtifactType"},"search_id":{"allOf":[{"$ref":"#/components/schemas/SearchId"}],"description":"Required when `collection_id` is a hunt collection. Must be omitted for triage collections."},"agent_id":{"allOf":[{"$ref":"#/components/schemas/AgentId"}],"description":"Required when `collection_id` is a triage collection. Must be omitted for hunt collections."},"search_from":{"$ref":"#/components/schemas/SearchFrom"},"search_to":{"$ref":"#/components/schemas/SearchTo"}}}},"required":["request_data"]}}}},"responses":{"200":{"description":"Artifact rows. The shape of each item depends on `artifact_type`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RawRowsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"schemas":{"InvestigationId":{"type":"string","format":"uuid","description":"UUID v4 identifier of a forensic investigation."},"CollectionId":{"type":"string","format":"uuid","description":"UUID v4 identifier of a hunt or triage collection."},"ArtifactType":{"type":"string","minLength":1,"description":"Name of the forensic artifact (table) to query. Must be a known artifact type registered in the forensic artifacts engine (for example `REGISTRY`, `AMCACHE`, `CHROME_HISTORY`, `MFT`, `EVTX`, `SHIMCACHE`)."},"SearchId":{"type":"string","format":"uuid","description":"UUID v4 identifier of a hunt search."},"AgentId":{"type":"string","format":"uuid","description":"UUID v4 identifier of an endpoint agent."},"SearchFrom":{"type":"integer","minimum":0,"default":0,"description":"Zero-based start index for pagination."},"SearchTo":{"type":"integer","minimum":0,"description":"Exclusive end index for pagination. Defaults to `search_from + 1000`. The page window (`search_to - search_from`) must be `<= 1000` to prevent query timeouts and ensure optimal performance."},"RawRowsResponse":{"type":"object","properties":{"reply":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Artifact row whose shape depends on `artifact_type`."}},"total_count":{"type":"integer"}}}}}},"responses":{"BadRequest":{"description":"Invalid or missing parameters. Returned for example when a required id is missing or not a valid UUID v4, `artifact_type` is missing, pagination is out of range or the wrong type-specific id (`search_id` vs `agent_id`) is sent for the collection type.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Unauthorized":{"description":"Unauthorized access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Forbidden":{"description":"The caller does not have access to the requested investigation (out-of-scope).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"NotFound":{"description":"The referenced entity does not exist, or the relationship is invalid (collection not in investigation, agent not in triage, search not in collection).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"InternalError":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}
```

## Get host timeline rows for an agent

> Returns the chronological host-timeline events (such as process creation, file modifications, and network connections) collected from a specific endpoint agent inside a triage collection. Supports pagination.\
> \
> Required licenses: Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus with endpoints and the Forensics add-on.\
> RBAC permission: Forensics > View, which is included in the following built-in roles: Viewer, Investigator, Privileged Investigator, and Administrator.

```json
{"openapi":"3.0.2","info":{"title":"Cortex XSIAM Forensics REST API","version":"3.x"},"tags":[{"name":"Forensics","description":"Public API endpoints for browsing forensic investigations, their hunt and triage collections, and the artifact data collected for them."}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/forensics/investigations/collections/triage/host_timeline":{"post":{"summary":"Get host timeline rows for an agent","description":"Returns the chronological host-timeline events (such as process creation, file modifications, and network connections) collected from a specific endpoint agent inside a triage collection. Supports pagination.\n\nRequired licenses: Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus with endpoints and the Forensics add-on.\nRBAC permission: Forensics > View, which is included in the following built-in roles: Viewer, Investigator, Privileged Investigator, and Administrator.","operationId":"getForensicsHostTimeline","tags":["Forensics"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","required":["investigation_id","collection_id","agent_id"],"properties":{"investigation_id":{"$ref":"#/components/schemas/InvestigationId"},"collection_id":{"allOf":[{"$ref":"#/components/schemas/CollectionId"}],"description":"Identifier of the triage collection."},"agent_id":{"$ref":"#/components/schemas/AgentId"},"search_from":{"$ref":"#/components/schemas/SearchFrom"},"search_to":{"$ref":"#/components/schemas/SearchTo"}}}},"required":["request_data"]}}}},"responses":{"200":{"description":"Host-timeline rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HostTimelineResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"schemas":{"InvestigationId":{"type":"string","format":"uuid","description":"UUID v4 identifier of a forensic investigation."},"CollectionId":{"type":"string","format":"uuid","description":"UUID v4 identifier of a hunt or triage collection."},"AgentId":{"type":"string","format":"uuid","description":"UUID v4 identifier of an endpoint agent."},"SearchFrom":{"type":"integer","minimum":0,"default":0,"description":"Zero-based start index for pagination."},"SearchTo":{"type":"integer","minimum":0,"description":"Exclusive end index for pagination. Defaults to `search_from + 1000`. The page window (`search_to - search_from`) must be `<= 1000` to prevent query timeouts and ensure optimal performance."},"HostTimelineResponse":{"type":"object","properties":{"reply":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HostTimelineRow"}},"total_count":{"type":"integer"}}}}},"HostTimelineRow":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"agent_id":{"type":"string","format":"uuid"},"timeline_id":{"type":"string"},"host_name":{"type":"string"},"generated_time":{"type":"integer","description":"Epoch-millisecond timestamp at which the row was generated by the agent."},"timestamp":{"type":"integer","description":"Epoch-millisecond timestamp of the event itself."},"timestamp_partition":{"type":"integer","description":"Date partition (YYYYMMDD) the row belongs to."},"description":{"type":"string"},"type":{"type":"string","description":"Event type (for example `PROCESS`, `FILE`, `REGISTRY`)."},"user":{"type":"string"},"data":{"type":"object","description":"Event-type-specific payload.","additionalProperties":true},"tags":{"type":"array","items":{"type":"string"}},"source_row_uuid":{"type":"string","format":"uuid"},"os":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Invalid or missing parameters. Returned for example when a required id is missing or not a valid UUID v4, `artifact_type` is missing, pagination is out of range or the wrong type-specific id (`search_id` vs `agent_id`) is sent for the collection type.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Unauthorized":{"description":"Unauthorized access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Forbidden":{"description":"The caller does not have access to the requested investigation (out-of-scope).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"NotFound":{"description":"The referenced entity does not exist, or the relationship is invalid (collection not in investigation, agent not in triage, search not in collection).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"InternalError":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}
```

## List files collected by a triage artifact

> Returns the individual files collected for a given file-producing artifact type (such as raw event logs or system files) from a specific endpoint agent inside a triage collection. Each item references a single collected file path; \`download\_url\` is populated with a secure, time-limited signed URL only when the file is available for download.\
> \
> Required licenses: Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus with endpoints and the Forensics add-on.\
> RBAC permission: Forensics > View, which is included in the following built-in roles: Viewer, Investigator, Privileged Investigator, and Administrator.

```json
{"openapi":"3.0.2","info":{"title":"Cortex XSIAM Forensics REST API","version":"3.x"},"tags":[{"name":"Forensics","description":"Public API endpoints for browsing forensic investigations, their hunt and triage collections, and the artifact data collected for them."}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/forensics/investigations/collections/triage/get_files":{"post":{"summary":"List files collected by a triage artifact","description":"Returns the individual files collected for a given file-producing artifact type (such as raw event logs or system files) from a specific endpoint agent inside a triage collection. Each item references a single collected file path; `download_url` is populated with a secure, time-limited signed URL only when the file is available for download.\n\nRequired licenses: Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus with endpoints and the Forensics add-on.\nRBAC permission: Forensics > View, which is included in the following built-in roles: Viewer, Investigator, Privileged Investigator, and Administrator.","operationId":"getForensicsTriageFiles","tags":["Forensics"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","required":["investigation_id","collection_id","agent_id","artifact_type"],"properties":{"investigation_id":{"$ref":"#/components/schemas/InvestigationId"},"collection_id":{"allOf":[{"$ref":"#/components/schemas/CollectionId"}],"description":"Identifier of the triage collection."},"agent_id":{"$ref":"#/components/schemas/AgentId"},"artifact_type":{"allOf":[{"$ref":"#/components/schemas/ArtifactType"}],"description":"Name of the file-collecting artifact (for example `MFT`)."}}}},"required":["request_data"]}}}},"responses":{"200":{"description":"Collected files for the requested artifact.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TriageFilesResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"schemas":{"InvestigationId":{"type":"string","format":"uuid","description":"UUID v4 identifier of a forensic investigation."},"CollectionId":{"type":"string","format":"uuid","description":"UUID v4 identifier of a hunt or triage collection."},"AgentId":{"type":"string","format":"uuid","description":"UUID v4 identifier of an endpoint agent."},"ArtifactType":{"type":"string","minLength":1,"description":"Name of the forensic artifact (table) to query. Must be a known artifact type registered in the forensic artifacts engine (for example `REGISTRY`, `AMCACHE`, `CHROME_HISTORY`, `MFT`, `EVTX`, `SHIMCACHE`)."},"TriageFilesResponse":{"type":"object","properties":{"reply":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TriageCollectedFile"}},"total_count":{"type":"integer"}}}}},"TriageCollectedFile":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identifier of the parent triage-result row."},"file_path":{"type":"string"},"time_collected":{"type":"integer","description":"Epoch-millisecond timestamp at which the file was collected."},"available_for_download":{"type":"boolean"},"download_url":{"type":"string","format":"uri","nullable":true,"description":"Time-limited signed URL to download the file. Populated only when `available_for_download` is `true`."}}}},"responses":{"BadRequest":{"description":"Invalid or missing parameters. Returned for example when a required id is missing or not a valid UUID v4, `artifact_type` is missing, pagination is out of range or the wrong type-specific id (`search_id` vs `agent_id`) is sent for the collection type.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Unauthorized":{"description":"Unauthorized access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Forbidden":{"description":"The caller does not have access to the requested investigation (out-of-scope).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"NotFound":{"description":"The referenced entity does not exist, or the relationship is invalid (collection not in investigation, agent not in triage, search not in collection).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"InternalError":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cortex-docs.paloaltonetworks.com/xsiam-api/forensics-1/forensics.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.