> 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/managed-services/reports.md).

# Reports

APIs for retrieving MTH/MDR reports

## Get reports by source ID

> Retrieves one or more MTH/MDR reports by their \`xsoar\_source\_id\` values.\
> \
> \*\*Validation rules:\*\*\
> \- \`xsoar\_source\_ids\` is required and must be a non-empty string or a non-empty array of non-empty strings.\
> \
> \*\*Response notes — this endpoint differs from all the others:\*\*\
> \- Rows are returned \*\*exactly as stored in MySQL\*\*, so field names are \*\*lower\_snake\_case\*\* (\`xsoar\_source\_id\`, \`incident\_id\`, ...), unlike every other reports endpoint which returns UPPER\_SNAKE\_CASE.\
> \- \`attachments\` is the \*\*raw JSON column returned as a JSON-encoded string\*\* (for example \`"{}"\` or \`"{\\"update\_report/...\\": {...}}"\`), not a parsed array.\
> \- There is \*\*no \`comments\` field\*\* on this response; comments are not joined here.\
> \- \`created\_by\` \*\*is\*\* included (it is absent from no shape, but note it is present here as a raw column).\
> \- The response is wrapped in \`reply.status\` / \`reply.data\`.\
> \
> \*\*Required licenses:\*\* MDR, MTH, Managed XSIAM Pro, Managed XSIAM Premium.\
> \
> \*\*Permissions:\*\* Users with Instance Administrator privileges only can access these endpoints.

```json
{"openapi":"3.0.1","info":{"title":"Managed Services APIs","version":"1.0.1"},"tags":[{"name":"Reports","description":"APIs for retrieving MTH/MDR reports"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"apiKey","name":"Authorization","in":"header","description":"API Key for authentication"}},"schemas":{"GetReportsBySourceIdRequestData":{"type":"object","required":["xsoar_source_ids"],"properties":{"xsoar_source_ids":{"description":"A single XSOAR source ID or an array of XSOAR source IDs. Values must be non-empty strings.","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"},"minItems":1}]}}},"GetReportsBySourceIdResponse":{"type":"object","properties":{"reply":{"type":"object","properties":{"status":{"type":"boolean","description":"Operation success status"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ReportRawRow"},"description":"Array of raw report rows matching the requested source IDs. Note the lower_snake_case field names and the string-encoded `attachments`."}}}}},"ReportRawRow":{"type":"object","description":"MTH/MDR report as returned **only** by `get_reports_by_source_id`. This is the raw MySQL row: keys are lower_snake_case, `attachments` is a JSON-encoded string, and there is no `comments` field.","properties":{"xsoar_source_id":{"type":"string","description":"Unique identifier of the report"},"report_type":{"type":"string","nullable":true,"description":"Type of the report"},"insert_time":{"type":"integer","format":"int64","nullable":true,"description":"Creation timestamp in epoch milliseconds"},"update_time":{"type":"integer","format":"int64","nullable":true,"description":"Last update timestamp in epoch milliseconds"},"name":{"type":"string","nullable":true,"description":"Name/title of the report"},"description":{"type":"string","nullable":true,"description":"Detailed description of the report"},"created_by":{"type":"string","nullable":true,"description":"Author of the report"},"incident_id":{"type":"integer","format":"int64","nullable":true,"description":"Associated incident ID"},"severity":{"$ref":"#/components/schemas/Severity"},"attachments":{"type":"string","nullable":true,"description":"Raw MySQL JSON column, returned as a **JSON-encoded string**. `\"{}\"` when there are no attachments. Each key is the storage path and each value is an object with `attachment_name` and `attachment_size` (lower_snake_case)."},"classification":{"$ref":"#/components/schemas/Classification"},"assigned_user":{"type":"string","nullable":true,"description":"Email/identifier of the assigned user"},"assigned_user_pretty":{"type":"string","nullable":true,"description":"Display name of the assigned user"},"report_status":{"$ref":"#/components/schemas/ReportStatusInternal"}}},"Severity":{"type":"string","nullable":true,"description":"Severity level of the report.","enum":["SEV_010_INFO","SEV_020_LOW","SEV_030_MEDIUM","SEV_040_HIGH","SEV_050_CRITICAL","SEV_090_UNKNOWN"]},"Classification":{"type":"string","description":"Classification of the report. Note the MDR value is the literal string `Unit 42 MDR`, not `MDR`.","enum":["MTH","Unit 42 MDR"]},"ReportStatusInternal":{"type":"string","description":"Report status, expressed as its internal name. Always used in responses.","enum":["NEW","IN_PROGRESS","ON_HOLD","RESOLVED_FP","RESOLVED_TP","RESOLVED_OTHER","RESOLVED_SECURITY_TESTING"]},"BaseError":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer","description":"Numeric error code, mirroring the HTTP status code. Most validation and business-logic failures on these endpoints return 500."},"err_msg":{"type":"string","description":"Generic error message, for example `An error occurred while processing XDR public API`."},"err_extra":{"type":"string","nullable":true,"description":"Specific reason for the failure. This is the field to inspect when diagnosing a rejected request."}}}}}},"responses":{"BadRequest":{"description":"Bad Request - Invalid parameters or missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}},"Unauthorized":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}},"Forbidden":{"description":"Forbidden - Tenant not authorized for this endpoint, or the caller lacks Instance Administrator privileges","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}},"InternalServerError":{"description":"Internal Server Error.\n\nNote: most business-logic and input-validation failures on these endpoints are also returned with HTTP 500 and `reply.err_code` 500, with the specific reason in `reply.err_extra`. Do not rely on a 400 status to detect a bad request; inspect `reply.err_extra`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}}}},"paths":{"/public_api/v1/mth/child/get_reports_by_source_id":{"post":{"summary":"Get reports by source ID","operationId":"postGetReportsBySourceId","description":"Retrieves one or more MTH/MDR reports by their `xsoar_source_id` values.\n\n**Validation rules:**\n- `xsoar_source_ids` is required and must be a non-empty string or a non-empty array of non-empty strings.\n\n**Response notes — this endpoint differs from all the others:**\n- Rows are returned **exactly as stored in MySQL**, so field names are **lower_snake_case** (`xsoar_source_id`, `incident_id`, ...), unlike every other reports endpoint which returns UPPER_SNAKE_CASE.\n- `attachments` is the **raw JSON column returned as a JSON-encoded string** (for example `\"{}\"` or `\"{\\\"update_report/...\\\": {...}}\"`), not a parsed array.\n- There is **no `comments` field** on this response; comments are not joined here.\n- `created_by` **is** included (it is absent from no shape, but note it is present here as a raw column).\n- The response is wrapped in `reply.status` / `reply.data`.\n\n**Required licenses:** MDR, MTH, Managed XSIAM Pro, Managed XSIAM Premium.\n\n**Permissions:** Users with Instance Administrator privileges only can access these endpoints.","parameters":[{"schema":{"type":"string"},"in":"header","name":"Authorization","description":"{api_key}","required":true},{"schema":{"type":"string"},"in":"header","name":"x-xdr-auth-id","description":"{api_key_id}","required":true}],"requestBody":{"description":"Request body for retrieving MTH/MDR reports by source ID.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetReportsBySourceIdRequestData"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetReportsBySourceIdResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}},"tags":["Reports"]}}}}
```

## Get reports by incident ID

> Retrieves MTH/MDR reports associated with one or more incident IDs.\
> \
> \*\*Validation rules:\*\*\
> \- \`incident\_ids\` is required and must be a non-empty string or a non-empty array of non-empty \*\*strings\*\*. Numeric JSON values are rejected by input validation even though the underlying column is an integer — send IDs as strings.\
> \
> \*\*Response notes:\*\*\
> \- \`reply\` is a \*\*bare array\*\* of reports. Unlike \`get\_all\_reports\` and \`get\_reports\_by\_statuses\`, there is \*\*no \`DATA\`/\`COUNT\` wrapper\*\*, and unlike \`get\_reports\_by\_source\_id\` there is no \`status\`/\`data\` wrapper.\
> \- Reports use the \*\*UPPER\_SNAKE\_CASE\*\* shape (\`ReportUpperCase\`) and include the \`COMMENTS\` array and the parsed \`ATTACHMENTS\` array.\
> \- MTH reports typically have no incident association, so this endpoint mostly returns MDR reports.\
> \
> \*\*Required licenses:\*\* MDR, MTH, Managed XSIAM Pro, Managed XSIAM Premium.\
> \
> \*\*Permissions:\*\* Users with Instance Administrator privileges only can access these endpoints.

```json
{"openapi":"3.0.1","info":{"title":"Managed Services APIs","version":"1.0.1"},"tags":[{"name":"Reports","description":"APIs for retrieving MTH/MDR reports"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"apiKey","name":"Authorization","in":"header","description":"API Key for authentication"}},"schemas":{"GetReportsByIncidentIdRequestData":{"type":"object","required":["incident_ids"],"properties":{"incident_ids":{"description":"A single incident ID or an array of incident IDs. Values must be non-empty **strings**; numeric JSON values are rejected.","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"},"minItems":1}]}}},"GetReportsByIncidentIdResponse":{"type":"object","properties":{"reply":{"type":"array","items":{"$ref":"#/components/schemas/ReportUpperCase"},"description":"Bare array of report objects matching the requested incident IDs. There is no `DATA`/`COUNT` wrapper on this endpoint."}}},"ReportUpperCase":{"type":"object","description":"MTH/MDR report as returned by `get_all_reports`, `get_reports_by_statuses`, `get_reports_by_incident_id`, `report/update/status`, and `report/update/assign`. All keys are UPPER_SNAKE_CASE.","properties":{"XSOAR_SOURCE_ID":{"type":"string","description":"Unique identifier of the report"},"NAME":{"type":"string","nullable":true,"description":"Name/title of the report"},"DESCRIPTION":{"type":"string","nullable":true,"description":"Detailed description of the report"},"CREATED_BY":{"type":"string","nullable":true,"description":"Author of the report. Normalized to `Unit42 Threat Hunting` or `Unit42 MDR` for Palo Alto Networks authored reports."},"INSERT_TIME":{"type":"integer","format":"int64","nullable":true,"description":"Creation timestamp in epoch milliseconds"},"UPDATE_TIME":{"type":"integer","format":"int64","nullable":true,"description":"Last update timestamp in epoch milliseconds"},"ATTACHMENTS":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/Attachment"},"description":"Parsed attachment metadata. Empty array when the report has no attachments. **Always `null`** on the `report/update/status` and `report/update/assign` responses."},"INCIDENT_ID":{"type":"integer","format":"int64","nullable":true,"description":"Associated incident ID. Null for MTH reports, which are not incident-scoped."},"REPORT_TYPE":{"type":"string","nullable":true,"description":"Type of the report, as a display string. Examples: `Threat Report`, `Threat Report Update`, `Impact Report`, `Threat Inquiry`, `Threat Inquiry Update`, `Hunting Report`, `Emerging Threat Report`, `Active Campaigns Report`, `Baseline Hunting Report`, `Threat Profiling Report`, `Cyber Hygiene Report`, `Monthly Status Report`, `Evaluation Summary Report`, `Managed Case Report`."},"SEVERITY":{"$ref":"#/components/schemas/Severity"},"COMMENTS":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/EmbeddedComment"},"description":"Comments joined onto the report. Empty array when the report has no comments. **Always `null`** on the `report/update/status` and `report/update/assign` responses."},"CLASSIFICATION":{"$ref":"#/components/schemas/Classification"},"ASSIGNED_USER":{"type":"string","nullable":true,"description":"Email/identifier of the assigned user"},"ASSIGNED_USER_PRETTY":{"type":"string","nullable":true,"description":"Display name of the assigned user"},"REPORT_STATUS":{"$ref":"#/components/schemas/ReportStatusInternal"}}},"Attachment":{"type":"object","description":"A single parsed attachment entry. Keys are UPPER_SNAKE_CASE.","properties":{"ATTACHMENT_PATH":{"type":"string","description":"Storage key of the attachment inside the public API GCS bucket"},"ATTACHMENT_SIZE":{"type":"integer","nullable":true,"description":"Size of the attachment in bytes"},"ATTACHMENT_NAME":{"type":"string","nullable":true,"description":"Original file name of the attachment. May be an empty string."}}},"Severity":{"type":"string","nullable":true,"description":"Severity level of the report.","enum":["SEV_010_INFO","SEV_020_LOW","SEV_030_MEDIUM","SEV_040_HIGH","SEV_050_CRITICAL","SEV_090_UNKNOWN"]},"EmbeddedComment":{"type":"object","description":"A comment as embedded inside a `ReportUpperCase.COMMENTS` array. Keys are UPPER_SNAKE_CASE and the field set differs from the standalone `Comment` returned by `get_comments`.","properties":{"COMMENT_ID":{"type":"integer","description":"Unique identifier of the comment"},"COMMENT_CREATED_BY":{"type":"string","description":"Author of the comment. For hunter-authored comments this is masked to the literal `Unit 42 Managed Services` unless the caller is an MTH research user."},"COMMENT_TEXT":{"type":"string","nullable":true,"description":"Text content of the comment"},"COMMENT_INSERT_TIME":{"type":"integer","format":"int64","description":"Creation timestamp in epoch milliseconds"},"COMMENT_UPDATE_TIME":{"type":"integer","format":"int64","nullable":true,"description":"Last update timestamp in epoch milliseconds, or null if never edited"},"COMMENT_USERNAME":{"type":"string","nullable":true,"description":"User name of the account that created the comment"},"COMMENT_ATTACHMENTS":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"},"description":"Parsed attachment metadata. Empty array when the comment has no attachments. Note these are metadata objects, not signed URLs — unlike the `get_comments` endpoint."},"COMMENT_IS_HUNTER":{"type":"boolean","description":"True when the comment was authored by a hunter/analyst rather than the customer"}}},"Classification":{"type":"string","description":"Classification of the report. Note the MDR value is the literal string `Unit 42 MDR`, not `MDR`.","enum":["MTH","Unit 42 MDR"]},"ReportStatusInternal":{"type":"string","description":"Report status, expressed as its internal name. Always used in responses.","enum":["NEW","IN_PROGRESS","ON_HOLD","RESOLVED_FP","RESOLVED_TP","RESOLVED_OTHER","RESOLVED_SECURITY_TESTING"]},"BaseError":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer","description":"Numeric error code, mirroring the HTTP status code. Most validation and business-logic failures on these endpoints return 500."},"err_msg":{"type":"string","description":"Generic error message, for example `An error occurred while processing XDR public API`."},"err_extra":{"type":"string","nullable":true,"description":"Specific reason for the failure. This is the field to inspect when diagnosing a rejected request."}}}}}},"responses":{"BadRequest":{"description":"Bad Request - Invalid parameters or missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}},"Unauthorized":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}},"Forbidden":{"description":"Forbidden - Tenant not authorized for this endpoint, or the caller lacks Instance Administrator privileges","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}},"InternalServerError":{"description":"Internal Server Error.\n\nNote: most business-logic and input-validation failures on these endpoints are also returned with HTTP 500 and `reply.err_code` 500, with the specific reason in `reply.err_extra`. Do not rely on a 400 status to detect a bad request; inspect `reply.err_extra`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}}}},"paths":{"/public_api/v1/mth/child/get_reports_by_incident_id":{"post":{"summary":"Get reports by incident ID","operationId":"postGetReportsByIncidentId","description":"Retrieves MTH/MDR reports associated with one or more incident IDs.\n\n**Validation rules:**\n- `incident_ids` is required and must be a non-empty string or a non-empty array of non-empty **strings**. Numeric JSON values are rejected by input validation even though the underlying column is an integer — send IDs as strings.\n\n**Response notes:**\n- `reply` is a **bare array** of reports. Unlike `get_all_reports` and `get_reports_by_statuses`, there is **no `DATA`/`COUNT` wrapper**, and unlike `get_reports_by_source_id` there is no `status`/`data` wrapper.\n- Reports use the **UPPER_SNAKE_CASE** shape (`ReportUpperCase`) and include the `COMMENTS` array and the parsed `ATTACHMENTS` array.\n- MTH reports typically have no incident association, so this endpoint mostly returns MDR reports.\n\n**Required licenses:** MDR, MTH, Managed XSIAM Pro, Managed XSIAM Premium.\n\n**Permissions:** Users with Instance Administrator privileges only can access these endpoints.","parameters":[{"schema":{"type":"string"},"in":"header","name":"Authorization","description":"{api_key}","required":true},{"schema":{"type":"string"},"in":"header","name":"x-xdr-auth-id","description":"{api_key_id}","required":true}],"requestBody":{"description":"Request body for retrieving MTH/MDR reports by incident ID.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetReportsByIncidentIdRequestData"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetReportsByIncidentIdResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}},"tags":["Reports"]}}}}
```

## Get all MTH/MDR reports

> Retrieves all MTH/MDR reports for the calling child tenant.\
> \
> This endpoint takes no request parameters; any supplied body is ignored. Send \`{}\`.\
> \
> \*\*Response notes:\*\*\
> \- Reports use the \*\*UPPER\_SNAKE\_CASE\*\* shape (\`ReportUpperCase\`) and include the joined \`COMMENTS\` array and the parsed \`ATTACHMENTS\` array.\
> \- \`COUNT\` is derived from the internal \`FILTER\_COUNT\` (number of reports matching the query). The internal \`TOTAL\_COUNT\` field is stripped from the response.\
> \- No paging is applied, so the full report set for the tenant is returned in one response.\
> \
> \*\*Required licenses:\*\* MDR, MTH, Managed XSIAM Pro, Managed XSIAM Premium.\
> \
> \*\*Permissions:\*\* Users with Instance Administrator privileges only can access these endpoints.

```json
{"openapi":"3.0.1","info":{"title":"Managed Services APIs","version":"1.0.1"},"tags":[{"name":"Reports","description":"APIs for retrieving MTH/MDR reports"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"apiKey","name":"Authorization","in":"header","description":"API Key for authentication"}},"schemas":{"GetAllReportsResponse":{"type":"object","properties":{"reply":{"type":"object","properties":{"DATA":{"type":"array","items":{"$ref":"#/components/schemas/ReportUpperCase"},"description":"Array of report objects matching the query"},"COUNT":{"type":"integer","description":"Number of reports matching the applied filters"}}}}},"ReportUpperCase":{"type":"object","description":"MTH/MDR report as returned by `get_all_reports`, `get_reports_by_statuses`, `get_reports_by_incident_id`, `report/update/status`, and `report/update/assign`. All keys are UPPER_SNAKE_CASE.","properties":{"XSOAR_SOURCE_ID":{"type":"string","description":"Unique identifier of the report"},"NAME":{"type":"string","nullable":true,"description":"Name/title of the report"},"DESCRIPTION":{"type":"string","nullable":true,"description":"Detailed description of the report"},"CREATED_BY":{"type":"string","nullable":true,"description":"Author of the report. Normalized to `Unit42 Threat Hunting` or `Unit42 MDR` for Palo Alto Networks authored reports."},"INSERT_TIME":{"type":"integer","format":"int64","nullable":true,"description":"Creation timestamp in epoch milliseconds"},"UPDATE_TIME":{"type":"integer","format":"int64","nullable":true,"description":"Last update timestamp in epoch milliseconds"},"ATTACHMENTS":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/Attachment"},"description":"Parsed attachment metadata. Empty array when the report has no attachments. **Always `null`** on the `report/update/status` and `report/update/assign` responses."},"INCIDENT_ID":{"type":"integer","format":"int64","nullable":true,"description":"Associated incident ID. Null for MTH reports, which are not incident-scoped."},"REPORT_TYPE":{"type":"string","nullable":true,"description":"Type of the report, as a display string. Examples: `Threat Report`, `Threat Report Update`, `Impact Report`, `Threat Inquiry`, `Threat Inquiry Update`, `Hunting Report`, `Emerging Threat Report`, `Active Campaigns Report`, `Baseline Hunting Report`, `Threat Profiling Report`, `Cyber Hygiene Report`, `Monthly Status Report`, `Evaluation Summary Report`, `Managed Case Report`."},"SEVERITY":{"$ref":"#/components/schemas/Severity"},"COMMENTS":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/EmbeddedComment"},"description":"Comments joined onto the report. Empty array when the report has no comments. **Always `null`** on the `report/update/status` and `report/update/assign` responses."},"CLASSIFICATION":{"$ref":"#/components/schemas/Classification"},"ASSIGNED_USER":{"type":"string","nullable":true,"description":"Email/identifier of the assigned user"},"ASSIGNED_USER_PRETTY":{"type":"string","nullable":true,"description":"Display name of the assigned user"},"REPORT_STATUS":{"$ref":"#/components/schemas/ReportStatusInternal"}}},"Attachment":{"type":"object","description":"A single parsed attachment entry. Keys are UPPER_SNAKE_CASE.","properties":{"ATTACHMENT_PATH":{"type":"string","description":"Storage key of the attachment inside the public API GCS bucket"},"ATTACHMENT_SIZE":{"type":"integer","nullable":true,"description":"Size of the attachment in bytes"},"ATTACHMENT_NAME":{"type":"string","nullable":true,"description":"Original file name of the attachment. May be an empty string."}}},"Severity":{"type":"string","nullable":true,"description":"Severity level of the report.","enum":["SEV_010_INFO","SEV_020_LOW","SEV_030_MEDIUM","SEV_040_HIGH","SEV_050_CRITICAL","SEV_090_UNKNOWN"]},"EmbeddedComment":{"type":"object","description":"A comment as embedded inside a `ReportUpperCase.COMMENTS` array. Keys are UPPER_SNAKE_CASE and the field set differs from the standalone `Comment` returned by `get_comments`.","properties":{"COMMENT_ID":{"type":"integer","description":"Unique identifier of the comment"},"COMMENT_CREATED_BY":{"type":"string","description":"Author of the comment. For hunter-authored comments this is masked to the literal `Unit 42 Managed Services` unless the caller is an MTH research user."},"COMMENT_TEXT":{"type":"string","nullable":true,"description":"Text content of the comment"},"COMMENT_INSERT_TIME":{"type":"integer","format":"int64","description":"Creation timestamp in epoch milliseconds"},"COMMENT_UPDATE_TIME":{"type":"integer","format":"int64","nullable":true,"description":"Last update timestamp in epoch milliseconds, or null if never edited"},"COMMENT_USERNAME":{"type":"string","nullable":true,"description":"User name of the account that created the comment"},"COMMENT_ATTACHMENTS":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"},"description":"Parsed attachment metadata. Empty array when the comment has no attachments. Note these are metadata objects, not signed URLs — unlike the `get_comments` endpoint."},"COMMENT_IS_HUNTER":{"type":"boolean","description":"True when the comment was authored by a hunter/analyst rather than the customer"}}},"Classification":{"type":"string","description":"Classification of the report. Note the MDR value is the literal string `Unit 42 MDR`, not `MDR`.","enum":["MTH","Unit 42 MDR"]},"ReportStatusInternal":{"type":"string","description":"Report status, expressed as its internal name. Always used in responses.","enum":["NEW","IN_PROGRESS","ON_HOLD","RESOLVED_FP","RESOLVED_TP","RESOLVED_OTHER","RESOLVED_SECURITY_TESTING"]},"BaseError":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer","description":"Numeric error code, mirroring the HTTP status code. Most validation and business-logic failures on these endpoints return 500."},"err_msg":{"type":"string","description":"Generic error message, for example `An error occurred while processing XDR public API`."},"err_extra":{"type":"string","nullable":true,"description":"Specific reason for the failure. This is the field to inspect when diagnosing a rejected request."}}}}}},"responses":{"BadRequest":{"description":"Bad Request - Invalid parameters or missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}},"Unauthorized":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}},"Forbidden":{"description":"Forbidden - Tenant not authorized for this endpoint, or the caller lacks Instance Administrator privileges","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}},"InternalServerError":{"description":"Internal Server Error.\n\nNote: most business-logic and input-validation failures on these endpoints are also returned with HTTP 500 and `reply.err_code` 500, with the specific reason in `reply.err_extra`. Do not rely on a 400 status to detect a bad request; inspect `reply.err_extra`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}}}},"paths":{"/public_api/v1/mth/child/get_all_reports":{"post":{"summary":"Get all MTH/MDR reports","operationId":"postGetAllReports","description":"Retrieves all MTH/MDR reports for the calling child tenant.\n\nThis endpoint takes no request parameters; any supplied body is ignored. Send `{}`.\n\n**Response notes:**\n- Reports use the **UPPER_SNAKE_CASE** shape (`ReportUpperCase`) and include the joined `COMMENTS` array and the parsed `ATTACHMENTS` array.\n- `COUNT` is derived from the internal `FILTER_COUNT` (number of reports matching the query). The internal `TOTAL_COUNT` field is stripped from the response.\n- No paging is applied, so the full report set for the tenant is returned in one response.\n\n**Required licenses:** MDR, MTH, Managed XSIAM Pro, Managed XSIAM Premium.\n\n**Permissions:** Users with Instance Administrator privileges only can access these endpoints.","parameters":[{"schema":{"type":"string"},"in":"header","name":"Authorization","description":"{api_key}","required":true},{"schema":{"type":"string"},"in":"header","name":"x-xdr-auth-id","description":"{api_key_id}","required":true}],"requestBody":{"description":"Empty request body. No parameters are required; any supplied fields are ignored.","required":true,"content":{"application/json":{"schema":{"type":"object","description":"Empty request body. No parameters are required."}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAllReportsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}},"tags":["Reports"]}}}}
```

## Get reports by statuses

> Retrieves MTH/MDR reports filtered by one or more status values.\
> \
> \*\*Validation rules:\*\*\
> \- \`report\_statuses\` is required and must be a non-empty \*\*array\*\* of strings. A bare string is rejected.\
> \- Each entry must be one of the supported \*\*display\*\* values: \`New\`, \`In Progress\`, \`On Hold\`, \`Resolved False Positive\`, \`Resolved True Positive\`, \`Resolved Other\`, \`Resolved Security Testing\`. There is no single \`Resolved\` value — the four resolved outcomes are distinct.\
> \- Invalid values fail the request with a message listing the supported statuses.\
> \
> \*\*Response notes:\*\*\
> \- Identical shape to \`get\_all\_reports\`: \`reply.DATA\` (array of \`ReportUpperCase\`) plus \`reply.COUNT\`.\
> \- \`REPORT\_STATUS\` in the response is the internal name (for example \`RESOLVED\_FP\`), not the display value used in the request.\
> \
> \*\*Required licenses:\*\* MDR, MTH, Managed XSIAM Pro, Managed XSIAM Premium.\
> \
> \*\*Permissions:\*\* Users with Instance Administrator privileges only can access these endpoints.

```json
{"openapi":"3.0.1","info":{"title":"Managed Services APIs","version":"1.0.1"},"tags":[{"name":"Reports","description":"APIs for retrieving MTH/MDR reports"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"apiKey","name":"Authorization","in":"header","description":"API Key for authentication"}},"schemas":{"GetReportsByStatusesRequestData":{"type":"object","required":["report_statuses"],"properties":{"report_statuses":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/ReportStatusDisplay","type":"string","enum":["New","In Progress","On Hold","Resolved"]},"description":"List of report statuses to filter by. At least one status must be provided. Each value must be one of the supported status values."}}},"ReportStatusDisplay":{"type":"string","description":"Report status, expressed as its display value. Used in request payloads.","enum":["New","In Progress","On Hold","Resolved False Positive","Resolved True Positive","Resolved Other","Resolved Security Testing"]},"GetAllReportsResponse":{"type":"object","properties":{"reply":{"type":"object","properties":{"DATA":{"type":"array","items":{"$ref":"#/components/schemas/ReportUpperCase"},"description":"Array of report objects matching the query"},"COUNT":{"type":"integer","description":"Number of reports matching the applied filters"}}}}},"ReportUpperCase":{"type":"object","description":"MTH/MDR report as returned by `get_all_reports`, `get_reports_by_statuses`, `get_reports_by_incident_id`, `report/update/status`, and `report/update/assign`. All keys are UPPER_SNAKE_CASE.","properties":{"XSOAR_SOURCE_ID":{"type":"string","description":"Unique identifier of the report"},"NAME":{"type":"string","nullable":true,"description":"Name/title of the report"},"DESCRIPTION":{"type":"string","nullable":true,"description":"Detailed description of the report"},"CREATED_BY":{"type":"string","nullable":true,"description":"Author of the report. Normalized to `Unit42 Threat Hunting` or `Unit42 MDR` for Palo Alto Networks authored reports."},"INSERT_TIME":{"type":"integer","format":"int64","nullable":true,"description":"Creation timestamp in epoch milliseconds"},"UPDATE_TIME":{"type":"integer","format":"int64","nullable":true,"description":"Last update timestamp in epoch milliseconds"},"ATTACHMENTS":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/Attachment"},"description":"Parsed attachment metadata. Empty array when the report has no attachments. **Always `null`** on the `report/update/status` and `report/update/assign` responses."},"INCIDENT_ID":{"type":"integer","format":"int64","nullable":true,"description":"Associated incident ID. Null for MTH reports, which are not incident-scoped."},"REPORT_TYPE":{"type":"string","nullable":true,"description":"Type of the report, as a display string. Examples: `Threat Report`, `Threat Report Update`, `Impact Report`, `Threat Inquiry`, `Threat Inquiry Update`, `Hunting Report`, `Emerging Threat Report`, `Active Campaigns Report`, `Baseline Hunting Report`, `Threat Profiling Report`, `Cyber Hygiene Report`, `Monthly Status Report`, `Evaluation Summary Report`, `Managed Case Report`."},"SEVERITY":{"$ref":"#/components/schemas/Severity"},"COMMENTS":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/EmbeddedComment"},"description":"Comments joined onto the report. Empty array when the report has no comments. **Always `null`** on the `report/update/status` and `report/update/assign` responses."},"CLASSIFICATION":{"$ref":"#/components/schemas/Classification"},"ASSIGNED_USER":{"type":"string","nullable":true,"description":"Email/identifier of the assigned user"},"ASSIGNED_USER_PRETTY":{"type":"string","nullable":true,"description":"Display name of the assigned user"},"REPORT_STATUS":{"$ref":"#/components/schemas/ReportStatusInternal"}}},"Attachment":{"type":"object","description":"A single parsed attachment entry. Keys are UPPER_SNAKE_CASE.","properties":{"ATTACHMENT_PATH":{"type":"string","description":"Storage key of the attachment inside the public API GCS bucket"},"ATTACHMENT_SIZE":{"type":"integer","nullable":true,"description":"Size of the attachment in bytes"},"ATTACHMENT_NAME":{"type":"string","nullable":true,"description":"Original file name of the attachment. May be an empty string."}}},"Severity":{"type":"string","nullable":true,"description":"Severity level of the report.","enum":["SEV_010_INFO","SEV_020_LOW","SEV_030_MEDIUM","SEV_040_HIGH","SEV_050_CRITICAL","SEV_090_UNKNOWN"]},"EmbeddedComment":{"type":"object","description":"A comment as embedded inside a `ReportUpperCase.COMMENTS` array. Keys are UPPER_SNAKE_CASE and the field set differs from the standalone `Comment` returned by `get_comments`.","properties":{"COMMENT_ID":{"type":"integer","description":"Unique identifier of the comment"},"COMMENT_CREATED_BY":{"type":"string","description":"Author of the comment. For hunter-authored comments this is masked to the literal `Unit 42 Managed Services` unless the caller is an MTH research user."},"COMMENT_TEXT":{"type":"string","nullable":true,"description":"Text content of the comment"},"COMMENT_INSERT_TIME":{"type":"integer","format":"int64","description":"Creation timestamp in epoch milliseconds"},"COMMENT_UPDATE_TIME":{"type":"integer","format":"int64","nullable":true,"description":"Last update timestamp in epoch milliseconds, or null if never edited"},"COMMENT_USERNAME":{"type":"string","nullable":true,"description":"User name of the account that created the comment"},"COMMENT_ATTACHMENTS":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"},"description":"Parsed attachment metadata. Empty array when the comment has no attachments. Note these are metadata objects, not signed URLs — unlike the `get_comments` endpoint."},"COMMENT_IS_HUNTER":{"type":"boolean","description":"True when the comment was authored by a hunter/analyst rather than the customer"}}},"Classification":{"type":"string","description":"Classification of the report. Note the MDR value is the literal string `Unit 42 MDR`, not `MDR`.","enum":["MTH","Unit 42 MDR"]},"ReportStatusInternal":{"type":"string","description":"Report status, expressed as its internal name. Always used in responses.","enum":["NEW","IN_PROGRESS","ON_HOLD","RESOLVED_FP","RESOLVED_TP","RESOLVED_OTHER","RESOLVED_SECURITY_TESTING"]},"BaseError":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer","description":"Numeric error code, mirroring the HTTP status code. Most validation and business-logic failures on these endpoints return 500."},"err_msg":{"type":"string","description":"Generic error message, for example `An error occurred while processing XDR public API`."},"err_extra":{"type":"string","nullable":true,"description":"Specific reason for the failure. This is the field to inspect when diagnosing a rejected request."}}}}}},"responses":{"BadRequest":{"description":"Bad Request - Invalid parameters or missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}},"Unauthorized":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}},"Forbidden":{"description":"Forbidden - Tenant not authorized for this endpoint, or the caller lacks Instance Administrator privileges","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}},"InternalServerError":{"description":"Internal Server Error.\n\nNote: most business-logic and input-validation failures on these endpoints are also returned with HTTP 500 and `reply.err_code` 500, with the specific reason in `reply.err_extra`. Do not rely on a 400 status to detect a bad request; inspect `reply.err_extra`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}}}},"paths":{"/public_api/v1/mth/child/get_reports_by_statuses":{"post":{"summary":"Get reports by statuses","operationId":"postGetReportsByStatuses","description":"Retrieves MTH/MDR reports filtered by one or more status values.\n\n**Validation rules:**\n- `report_statuses` is required and must be a non-empty **array** of strings. A bare string is rejected.\n- Each entry must be one of the supported **display** values: `New`, `In Progress`, `On Hold`, `Resolved False Positive`, `Resolved True Positive`, `Resolved Other`, `Resolved Security Testing`. There is no single `Resolved` value — the four resolved outcomes are distinct.\n- Invalid values fail the request with a message listing the supported statuses.\n\n**Response notes:**\n- Identical shape to `get_all_reports`: `reply.DATA` (array of `ReportUpperCase`) plus `reply.COUNT`.\n- `REPORT_STATUS` in the response is the internal name (for example `RESOLVED_FP`), not the display value used in the request.\n\n**Required licenses:** MDR, MTH, Managed XSIAM Pro, Managed XSIAM Premium.\n\n**Permissions:** Users with Instance Administrator privileges only can access these endpoints.","parameters":[{"schema":{"type":"string"},"in":"header","name":"Authorization","description":"{api_key}","required":true},{"schema":{"type":"string"},"in":"header","name":"x-xdr-auth-id","description":"{api_key_id}","required":true}],"requestBody":{"description":"Request body for retrieving MTH/MDR reports by statuses.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetReportsByStatusesRequestData"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAllReportsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}},"tags":["Reports"]}}}}
```


---

# 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/managed-services/reports.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.