> 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/xsoar-8-api/cortex-xsoar-8.x-apis/widgets.md).

# Widgets

APIs for managing widgets

## Get widget statistics

> Get the statistics for the specified widget.\
> \
> \*\*Note:\*\* This endpoint has many return types depending on the widget type and data. Each 200X represents a 200 OK request of specific widget type and data.

```json
{"openapi":"3.0.1","info":{"title":"Cortex XSOAR 8 API","version":"XSOAR 8 Cloud"},"tags":[{"name":"Widgets","description":"APIs for managing widgets"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"paths":{"/xsoar/public/v2/statistics/widgets/query":{"post":{"tags":["Widgets"],"summary":"Get widget statistics","description":"Get the statistics for the specified widget.\n\n**Note:** This endpoint has many return types depending on the widget type and data. Each 200X represents a 200 OK request of specific widget type and data.","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}],"operationId":"GetStatsForWidget","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"dataType":{"type":"string"},"widgetType":{"type":"string"},"query":{"type":"string"},"dateRange":{"type":"object","properties":{"fromDate":{"type":"string"},"toDate":{"type":"string"}}},"params":{"type":"object","properties":{"groupBy":{"type":"array","items":{"type":"string"}}}},"category":{"type":"string"}}}}},"required":false},"responses":{"200":{"description":"Response depends on the widget type:\n  -  Incident data type of a \"table\" or \"list\" widget returns incidentSearchResponse\n     total:\n       type: integer\n       data:\n         type: array\n      items:\n        \"$ref\": \"#/components/schemas/Incident\"\n  - Indicators data type of a \"table\" or \"list\" widget returns IoCsResponse\n    total:\n      type: integer\n    data:\n      type: array\n      items:\n        \"$ref\": \"#/components/schemas/IocObject\"\n  - Number widget returns a simple number\n    type: integer\n  - Trend widget returns a trend object\n    \"$ref\": \"#/components/schemas/StatsTrendsResponse\"\n  - Text widget returns a text object, describing the final text and the placeholders values.\n    \"$ref\": \"#/components/schemas/StatsTextResponse\"\n  - Line chart widget or Column chart widget returns StatsResponseWithReferenceLine\n    \"$ref\": \"#/components/schemas/StatsResponseWithReferenceLine\"\n  - A chart data array by groups. When requesting a date, the key is the date string, according to the specified time frame. Empty groups (dates) are also returned.\n    type: array\n    items:\n      \"$ref\": \"#/components/schemas/Group\"","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"total":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Incident"}}}},{"type":"object","properties":{"total":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/IocObject"}}}},{"type":"object","properties":{"number":{"type":"integer"}}},{"$ref":"#/components/schemas/StatsTrendsResponse"},{"$ref":"#/components/schemas/StatsTextResponse"},{"$ref":"#/components/schemas/StatsResponseWithReferenceLine"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Group"}}}}]}}}}}}}},"components":{"schemas":{"Incident":{"title":"Incident","type":"object","properties":{"account":{"type":"string","description":"Account holds the tenant name so that slicing and dicing on the master can leverage bleve"},"activated":{"type":"string","description":"When was this activated","format":"date-time"},"activatingingUserId":{"type":"string","description":"The user that activated this investigation"},"allRead":{"type":"boolean"},"allReadWrite":{"type":"boolean"},"attachment":{"type":"array","description":"Attachments","items":{"$ref":"#/components/schemas/Attachment"}},"autime":{"type":"integer","description":"AlmostUniqueTime is an attempt to have a unique sortable ID for an incident","format":"int64"},"cacheVersn":{"type":"integer","format":"int64"},"canvases":{"type":"array","description":"Canvases of the incident","items":{"type":"string"}},"category":{"type":"string","description":"Category"},"closeNotes":{"type":"string","description":"Notes for closing the incident"},"closeReason":{"type":"string","description":"The reason for closing the incident (select from existing predefined values)"},"closed":{"type":"string","description":"When was this closed","format":"date-time"},"closingUserId":{"type":"string","description":"The user ID that closed this investigation"},"created":{"type":"string","description":"When was this created","format":"date-time"},"dbotCreatedBy":{"type":"string","description":"Who has created this event - relevant only for manual incidents"},"dbotCurrentDirtyFields":{"type":"array","description":"For mirroring, manage a list of current dirty fields so that we can send delta to outgoing integration","items":{"type":"string"}},"dbotDirtyFields":{"type":"array","description":"For mirroring, manage a list of dirty fields to not override them from the source of the incident","items":{"type":"string"}},"dbotMirrorDirection":{"type":"string","description":"DBotMirrorDirection of how to mirror the incident (in/out/both)"},"dbotMirrorId":{"type":"string","description":"DBotMirrorID of a remote system we are syncing with"},"dbotMirrorInstance":{"type":"string","description":"DBotMirrorInstance name of a mirror integration instance"},"dbotMirrorLastSync":{"type":"string","description":"The last time we synced this incident even if we did not update anything","format":"date-time"},"dbotMirrorTags":{"type":"array","description":"The entry tags I want to sync to remote system","items":{"type":"string"}},"details":{"type":"string","description":"The details of the incident - reason, etc."},"droppedCount":{"type":"integer","description":"DroppedCount ...","format":"int64"},"dueDate":{"type":"string","description":"SLA","format":"date-time"},"feedBased":{"type":"boolean","description":"If this incident was triggered by a feed job"},"hasRole":{"type":"boolean","description":"Internal field to make queries on role faster"},"highlight":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"id":{"type":"string"},"investigationId":{"type":"string","description":"Investigation that was opened as a result of the incoming event"},"isDebug":{"type":"boolean","description":"IsDebug ..."},"isPlayground":{"type":"boolean","description":"IsPlayGround"},"labels":{"type":"array","description":"Labels related to incident - each label is composed of a type and value","items":{"$ref":"#/components/schemas/Label"}},"lastJobRunTime":{"type":"string","description":"If this incident was triggered by a job, this would be the time the **previous** job started","format":"date-time"},"lastOpen":{"type":"string","format":"date-time"},"linkedCount":{"type":"integer","description":"LinkedCount ...","format":"int64"},"linkedIncidents":{"type":"array","description":"LinkedIncidents incidents that were marked as linked by user","items":{"type":"string"}},"modified":{"type":"string","format":"date-time"},"name":{"type":"string","description":"Incident Name - given by user"},"notifyTime":{"type":"string","description":"Incdicates when last this field was changed with a value that supposed to send a notification","format":"date-time"},"numericId":{"type":"integer","format":"int64"},"occurred":{"type":"string","description":"When this incident has really occurred","format":"date-time"},"openDuration":{"type":"integer","description":"Duration incident was open","format":"int64"},"owner":{"type":"string","description":"The user who owns this incident"},"parent":{"type":"string","description":"Parent"},"phase":{"type":"string","description":"Phase"},"playbookId":{"type":"string","description":"The associated playbook for this incident"},"previousAllRead":{"type":"boolean"},"previousAllReadWrite":{"type":"boolean"},"previousRoles":{"type":"array","description":"Do not change this field manually","items":{"type":"string"}},"primaryTerm":{"type":"integer","format":"int64"},"rawCategory":{"type":"string"},"rawCloseReason":{"type":"string","description":"The reason for closing the incident (select from existing predefined values)"},"rawJSON":{"type":"string"},"rawName":{"type":"string","description":"Incident RawName"},"rawPhase":{"type":"string","description":"RawPhase"},"rawType":{"type":"string","description":"Incident raw type"},"reason":{"type":"string","description":"The reason for the resolve"},"reminder":{"type":"string","description":"When if at all to send a reminder","format":"date-time"},"roles":{"type":"array","description":"The role assigned to this investigation","items":{"type":"string"}},"runStatus":{"$ref":"#/components/schemas/RunStatus"},"sequenceNumber":{"type":"integer","format":"int64"},"severity":{"$ref":"#/components/schemas/Severity"},"sla":{"$ref":"#/components/schemas/SLAState"},"sortValues":{"type":"array","items":{"type":"string"}},"sourceBrand":{"type":"string","description":"SourceBrand ..."},"sourceInstance":{"type":"string","description":"SourceInstance ..."},"status":{"$ref":"#/components/schemas/IncidentStatus"},"syncHash":{"type":"string"},"todoTaskIds":{"type":"array","description":"ToDoTaskIDs list of to do task ids","items":{"type":"string"}},"type":{"type":"string","description":"Incident type"},"version":{"type":"integer","format":"int64"},"xsoarHasReadOnlyRole":{"type":"boolean"},"xsoarPreviousReadOnlyRoles":{"type":"array","items":{"type":"string"}},"xsoarReadOnlyRoles":{"type":"array","items":{"type":"string"}}},"description":"Note: CustomFields (an optional generic object type) is missing from the following definition."},"Attachment":{"title":"Attachment","type":"object","properties":{"description":{"type":"string"},"isTempPath":{"type":"boolean"},"name":{"type":"string"},"path":{"type":"string"},"showMediaFile":{"type":"boolean"},"type":{"type":"string"}},"description":""},"Label":{"title":"Label","type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"}}},"RunStatus":{"title":"RunStatus","type":"string","description":"Run status of a job."},"Severity":{"title":"Severity","maximum":4,"minimum":0,"type":"number","description":"Severity is the incident severity","format":"double"},"SLAState":{"title":"SLAState","type":"number","description":"SLAState is the incident SLA at closure time, in minutes.","format":"double"},"IncidentStatus":{"title":"IncidentStatus","maximum":2,"minimum":0,"type":"number","description":"IncidentStatus is the status of the incident","format":"double"},"IocObject":{"title":"IocObject","type":"object","properties":{"CustomFields":{"$ref":"#/components/schemas/CustomFields"},"account":{"type":"string"},"aggregatedReliability":{"type":"string"},"cacheVersn":{"type":"integer","format":"int64"},"calculatedTime":{"type":"string","description":"Do not set the fields bellow this line","format":"date-time"},"comment":{"type":"string"},"comments":{"$ref":"#/components/schemas/Comments"},"deletedFeedFetchTime":{"type":"string","format":"date-time"},"expiration":{"type":"string","format":"date-time"},"expirationSource":{"$ref":"#/components/schemas/ExpirationSource"},"expirationStatus":{"$ref":"#/components/schemas/ExpirationStatus"},"firstSeen":{"type":"string","format":"date-time"},"firstSeenEntryID":{"type":"string"},"highlight":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"id":{"type":"string"},"indicator_type":{"type":"string"},"insightCache":{"$ref":"#/components/schemas/InsightCache"},"investigationIDs":{"type":"array","items":{"type":"string"}},"isDetectable":{"type":"boolean"},"isPreventable":{"type":"boolean"},"isShared":{"type":"boolean"},"lastReputationRun":{"type":"string","format":"date-time"},"lastSeen":{"type":"string","format":"date-time"},"lastSeenEntryID":{"type":"string"},"manualExpirationTime":{"type":"string","format":"date-time"},"manualScore":{"type":"boolean"},"manualSetTime":{"type":"string","format":"date-time"},"manuallyEditedFields":{"type":"array","items":{"type":"string"}},"modified":{"type":"string","format":"date-time"},"modifiedTime":{"type":"string","format":"date-time"},"moduleToFeedMap":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/FeedIndicator"}},"numericId":{"type":"integer","format":"int64"},"primaryTerm":{"type":"integer","format":"int64"},"relatedIncCount":{"type":"integer","format":"int64"},"score":{"type":"integer","format":"int64"},"sequenceNumber":{"type":"integer","format":"int64"},"setBy":{"type":"string"},"sortValues":{"type":"array","items":{"type":"string"}},"source":{"type":"string"},"sourceBrands":{"type":"array","items":{"type":"string"}},"sourceInstances":{"type":"array","items":{"type":"string"}},"syncHash":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"value":{"type":"string"},"version":{"type":"integer","format":"int64"}},"description":"IocObject - represents an Ioc (or simply an indicator) object"},"CustomFields":{"title":"CustomFields","type":"object","additionalProperties":{"type":"object","properties":{}},"description":"The keys should be the field's display name, all lowercase and without spaces. For example: Scan IP -> scanip\nTo get the actual key name you can also go to Cortex XSOAR CLI and run /incident_add and look for the key that you would like to update."},"Comments":{"title":"Comments","type":"array","items":{"$ref":"#/components/schemas/Comment"}},"Comment":{"title":"Comment","type":"object","properties":{"cacheVersn":{"type":"integer","format":"int64"},"category":{"type":"string"},"content":{"type":"string"},"created":{"type":"string","format":"date-time"},"entryId":{"type":"string"},"highlight":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"id":{"type":"string"},"modified":{"type":"string","format":"date-time"},"numericId":{"type":"integer","format":"int64"},"primaryTerm":{"type":"integer","format":"int64"},"sequenceNumber":{"type":"integer","format":"int64"},"sortValues":{"type":"array","items":{"type":"string"}},"source":{"type":"string"},"syncHash":{"type":"string"},"type":{"$ref":"#/components/schemas/CommentType"},"user":{"type":"string"},"version":{"type":"integer","format":"int64"}}},"CommentType":{"title":"CommentType","type":"string","description":"Comment types: regular comment, timeline, etc..."},"ExpirationSource":{"title":"ExpirationSource","type":"object","properties":{"brand":{"type":"string"},"expirationInterval":{"type":"integer","format":"int64"},"expirationPolicy":{"$ref":"#/components/schemas/ExpirationPolicy"},"instance":{"type":"string"},"moduleId":{"type":"string"},"setTime":{"type":"string","format":"date-time"},"source":{"$ref":"#/components/schemas/ExpirationSettingsSource"},"user":{"type":"string"}}},"ExpirationPolicy":{"title":"ExpirationPolicy","type":"string"},"ExpirationSettingsSource":{"title":"ExpirationSettingsSource","type":"string"},"ExpirationStatus":{"title":"ExpirationStatus","type":"string"},"InsightCache":{"title":"InsightCache","type":"object","properties":{"cacheVersn":{"type":"integer","format":"int64"},"highlight":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"id":{"type":"string"},"modified":{"type":"string","format":"date-time"},"numericId":{"type":"integer","format":"int64"},"primaryTerm":{"type":"integer","format":"int64"},"scores":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DBotScore"}},"sequenceNumber":{"type":"integer","format":"int64"},"sortValues":{"type":"array","items":{"type":"string"}},"syncHash":{"type":"string"},"version":{"type":"integer","format":"int64"}},"description":"InsightCache - map insight name to all its metadata. Name is case insensitive."},"DBotScore":{"title":"DBotScore","type":"object","properties":{"content":{"type":"string"},"contentFormat":{"type":"string"},"context":{"type":"object","additionalProperties":{"type":"object","properties":{}}},"isTypedIndicator":{"type":"boolean"},"reliability":{"type":"string"},"score":{"type":"integer","format":"int64"},"scoreChangeTimestamp":{"type":"string","description":"We need to track when the score changes to know if we need to re-calculate the overall score","format":"date-time"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string"}},"description":"Contains the score of a specific brand for a specific insight."},"FeedIndicator":{"title":"FeedIndicator","type":"object","properties":{"ExpirationSource":{"$ref":"#/components/schemas/ExpirationSource"},"bypassExclusionList":{"type":"boolean"},"classifierId":{"type":"string"},"classifierVersion":{"type":"integer","format":"int64"},"comments":{"type":"array","items":{"$ref":"#/components/schemas/FeedIndicatorComment"}},"expirationInterval":{"type":"integer","format":"int64"},"expirationPolicy":{"$ref":"#/components/schemas/ExpirationPolicy"},"fetchTime":{"type":"string","format":"date-time"},"fields":{"$ref":"#/components/schemas/CustomFields"},"isEnrichment":{"type":"boolean"},"mapperId":{"type":"string"},"mapperVersion":{"type":"integer","format":"int64"},"modifiedTime":{"type":"string","format":"date-time"},"moduleId":{"type":"string"},"rawJSON":{"type":"object","additionalProperties":{"type":"object","properties":{}}},"relationships":{"$ref":"#/components/schemas/RelationshipsAPI"},"reliability":{"$ref":"#/components/schemas/Reliability"},"score":{"type":"integer","format":"int64"},"sourceBrand":{"type":"string"},"sourceInstance":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string"},"value":{"type":"string"}},"description":""},"FeedIndicatorComment":{"title":"FeedIndicatorComment","type":"object","properties":{"content":{"type":"string"},"created":{"type":"string","format":"date-time"},"id":{"type":"string"},"user":{"type":"string"}}},"RelationshipsAPI":{"title":"RelationshipsAPI","type":"array","items":{"$ref":"#/components/schemas/RelationshipAPI"}},"RelationshipAPI":{"title":"RelationshipAPI","type":"object","properties":{"brand":{"type":"string"},"entityA":{"type":"string"},"entityAFamily":{"type":"string"},"entityAType":{"type":"string"},"entityB":{"type":"string"},"entityBFamily":{"type":"string"},"entityBType":{"type":"string"},"fields":{"$ref":"#/components/schemas/CustomFields"},"id":{"type":"string"},"instance":{"type":"string"},"name":{"type":"string"},"reliability":{"$ref":"#/components/schemas/Reliability"},"reverseName":{"type":"string"},"startTime":{"type":"string","format":"date-time"},"type":{"type":"string"}},"description":""},"Reliability":{"title":"Reliability","type":"string"},"StatsTrendsResponse":{"description":"StatsTrendsResponse - Represent a trend response from statistics. Provides information about\nthe current value and the previous value based on the period.","type":"object","properties":{"currSum":{"type":"number","format":"double"},"prevSum":{"type":"number","format":"double"}}},"StatsTextResponse":{"type":"object","title":"StatsTextResponse - Describe the data returned related to a specific text widget cell in a dashboard.","properties":{"groups":{"$ref":"#/components/schemas/Groups"},"text":{"description":"Describe the complete text for the text widget, after placeholders injection.","type":"string"}}},"Groups":{"description":"Groups is a list of group entities","type":"array","items":{"$ref":"#/components/schemas/Group"}},"Group":{"type":"object","title":"Group is the response that returns from a statistics query, describing a grouped value.","properties":{"color":{"description":"color used to identify the group","type":"string"},"count":{"description":"The number of participants in the group","type":"integer","format":"int64"},"data":{"description":"The data value provided in array of integer values.","type":"array","items":{"type":"integer","format":"int64"}},"dataType":{"type":"string"},"floatData":{"description":"The data value provided in array of float values.","type":"array","items":{"type":"number","format":"double"}},"groups":{"$ref":"#/components/schemas/Groups"},"name":{"type":"string"},"pivot":{"type":"string"},"query":{"type":"string"},"x":{"type":"number","format":"double"},"y":{"type":"number","format":"double"},"z":{"type":"number","format":"double"}}},"StatsResponseWithReferenceLine":{"type":"object","title":"StatsResponseWithReferenceLine - Describe the data returned related to a specific Line/Column chart widget cell in a dashboard.","properties":{"groups":{"$ref":"#/components/schemas/Groups"},"referenceLineY":{"type":"number","format":"double"}}}}}}
```


---

# 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/xsoar-8-api/cortex-xsoar-8.x-apis/widgets.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.