> 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/cortex-commands-guide/timeline-commands.md).
# Timeline Commands
* [listTimelines](#listtimelines)
* [listTimelineRecords](#listtimelinerecords)
* [listTimelineTags](#listtimelinetags)
* [createTimelineRecord](#createtimelinerecord)
* [deleteTimelineRecord](#deletetimelinerecord)
* [updateTimelineRecordTags](#updatetimelinerecordtags)
* [linkRecordToTimeline](#linkrecordtotimeline)
* [markTimelineRecordAsEvidence](#marktimelinerecordasevidence)
#### listTimelines
***
Returns all named timelines available for a specific case. Use this command to discover existing timeline names before organizing records into them.
Arguments
| Argument Name | Description | Required |
| ------------- | --------------------------------------------------------- | -------- |
| case\_id | The ID of the case for which to list available timelines. | Required |
Outputs
**Core.Case.case\_id** *number*
The ID of the case.
**Core.Case.Timeline.Records.record\_id** *string*
The unique ID of the timeline record.
**Core.Case.Timeline.Records.record\_type** *string*
The type of the timeline record. Possible values: Case activity, Detection, Automation, System update, Response.
**Core.Case.Timeline.Records.record\_subtype** *string*
The subtype of the timeline record. For example: Note, Playbook started, Case created.
**Core.Case.Timeline.Records.record\_name** *string*
The name or title of the timeline record.
**Core.Case.Timeline.Records.description** *string*
The free-text description or content body of the timeline record.
**Core.Case.Timeline.Records.start\_ts** *number*
The date and time the record was added to the timeline (record creation time).
**Core.Case.Timeline.Records.occurred\_at** *number*
The date and time the event actually occurred. This may differ from the record creation time.
**Core.Case.Timeline.Records.origin** *string*
The source that created the record. Possible values: User, Automation, System, API Key, AI.
**Core.Case.Timeline.Records.origin\_id** *string*
The identifier of the source that created the record, for example, the username or automation name.
**Core.Case.Timeline.Records.is\_evidence** *boolean*
Whether the record is marked as evidence.
**Core.Case.Timeline.Records.evidence\_title** *string*
The title assigned to the record when it was marked as evidence.
**Core.Case.Timeline.Records.evidence\_comment** *string*
The comment provided when the record was marked as evidence.
**Core.Case.Timeline.Records.evidence\_flag\_time** *number*
The date and time the record was flagged as evidence.
**Core.Case.Timeline.Records.evidence\_flag\_by** *string*
The user who flagged the record as evidence.
**Core.Case.Timeline.Records.timelines** *string*
The named timelines this record belongs to.
**Core.Case.Timeline.Records.tags** *string*
The tags attached to this timeline record.
**Core.Case.Timeline.Records.is\_manual** *boolean*
Whether the record was created manually.
**Core.Case.Timeline.Records.attachments** *unknown*
Files attached to this timeline record.
**Core.Case.Timeline.Records.xql\_execution\_id** *string*
The XQL Query Center execution ID linked to this record.
**Core.Case.Timeline.Records.xql\_data** *unknown*
The XQL query results linked to this record.
**Core.Case.Timeline.Metadata.returned\_count** *number*
The number of records returned in this response.
**Core.Case.Timeline.Metadata.filtered\_count** *number*
The number of records matching the applied filters.
**Core.Case.Timeline.Metadata.total\_count** *number*
The total number of records in the case timeline.
#### listTimelineRecords
***
Returns a list of timeline records for a specific case. Multiple filters are combined using AND logic. If no filters are specified, all records are returned.
Arguments
| Argument Name | Description | Required |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| case\_id | The ID of the case. | Required |
| record\_id | Filters records by ID (exact match). | Optional |
| record\_type | Filters by record type. Accepts a comma-separated list. Possible values are: Case activity, Detection, Automation, System update, Response. | Optional |
| record\_subtype | Filters by record subtype. Accepts a comma-separated list. Possible values are: Case created, Case assigned, Status changed, Case starred, Case merged, Severity changed, Score changed, Description changed, Name changed, Field updated, Comment added / deleted, Issues grouped, Issues linked to case, Issues unlinked from case, Note added, Issue created, Playbook executed, Response action. | Optional |
| record\_name | Filters by record name (partial match, case-insensitive). | Optional |
| source | Filters by the source that created the record. Accepts a comma-separated list. Possible values are: User, Automation, System, API Key. | Optional |
| source\_id | Filters by source ID (partial match). For user-created records, this is the username. For automation-created records, this is 'Automation'. | Optional |
| timelines | Filters by named timeline. Accepts a comma-separated list. | Optional |
| tags | Filters by tag. Accepts a comma-separated list. | Optional |
| is\_evidence | Filters by evidence status. Set to true to return only evidence records, or false to return only non-evidence records. Possible values are: true, false. | Optional |
| evidence\_comment | Filters by evidence comment (partial match, case-insensitive). | Optional |
| evidence\_flag\_time\_start\_time | Returns records flagged as evidence on or after this date and time. Accepts natural language and ISO 8601 formats, for example, '2 days ago' or '2024-01-15T10:00:00Z'. | Optional |
| evidence\_flag\_time\_end\_time | Returns records flagged as evidence on or before this date and time. Accepts natural language and ISO 8601 formats, for example, '2024-01-15T10:00:00Z'. | Optional |
| evidence\_flag\_by | Filters by the user who flagged the record as evidence (partial match, case-insensitive). | Optional |
| record\_creation\_time\_start\_time | Returns records added to the timeline on or after this date and time (record creation time). Accepts natural language and ISO 8601 formats, for example, '2 days ago' or '2024-01-15T10:00:00Z'. | Optional |
| record\_creation\_time\_end\_time | Returns records added to the timeline on or before this date and time (record creation time). Accepts natural language and ISO 8601 formats, for example, '2024-01-15T10:00:00Z'. | Optional |
| occurred\_at\_start\_time | Returns records with an Occurred At timestamp on or after this date and time. Accepts natural language and ISO 8601 formats, for example, '2 days ago' or '2024-01-15T10:00:00Z'. | Optional |
| occurred\_at\_end\_time | Returns records with an Occurred At timestamp on or before this date and time. Accepts natural language and ISO 8601 formats, for example, '2024-01-15T10:00:00Z'. | Optional |
| sort\_field | The field to sort results by. Defaults to occurred\_at. Possible values are: occurred\_at, record\_creation\_time, record\_type, record\_subtype, record\_name, source, is\_evidence. Default is occurred\_at. | Optional |
| sort\_order | The sort order for results. Defaults to DESC. Possible values are: ASC, DESC. Default is DESC. | Optional |
| page | The page number for pagination. Defaults to 0 (the first page). Default is 0. | Optional |
| limit | The maximum number of records to return per page. Defaults to 50. Default is 50. | Optional |
Outputs
**Core.Case.case\_id** *number*
The ID of the case.
**Core.Case.Timeline.Records.record\_id** *string*
The unique ID of the timeline record.
**Core.Case.Timeline.Records.record\_type** *string*
The type of the timeline record. Possible values: Case activity, Detection, Automation, System update, Response.
**Core.Case.Timeline.Records.record\_subtype** *string*
The subtype of the timeline record. For example: Note, Playbook started, Case created.
**Core.Case.Timeline.Records.record\_name** *string*
The name or title of the timeline record.
**Core.Case.Timeline.Records.description** *string*
The free-text description or content body of the timeline record.
**Core.Case.Timeline.Records.start\_ts** *number*
The date and time the record was added to the timeline (record creation time).
**Core.Case.Timeline.Records.occurred\_at** *number*
The date and time the event actually occurred. This may differ from the record creation time.
**Core.Case.Timeline.Records.origin** *string*
The source that created the record. Possible values: User, Automation, System, API Key, AI.
**Core.Case.Timeline.Records.origin\_id** *string*
The identifier of the source that created the record, for example, the username or automation name.
**Core.Case.Timeline.Records.is\_evidence** *boolean*
Whether the record is marked as evidence.
**Core.Case.Timeline.Records.evidence\_title** *string*
The title assigned to the record when it was marked as evidence.
**Core.Case.Timeline.Records.evidence\_comment** *string*
The comment provided when the record was marked as evidence.
**Core.Case.Timeline.Records.evidence\_flag\_time** *number*
The date and time the record was flagged as evidence.
**Core.Case.Timeline.Records.evidence\_flag\_by** *string*
The user who flagged the record as evidence.
**Core.Case.Timeline.Records.timelines** *string*
The named timelines this record belongs to.
**Core.Case.Timeline.Records.tags** *string*
The tags attached to this timeline record.
**Core.Case.Timeline.Records.is\_manual** *boolean*
Whether the record was created manually.
**Core.Case.Timeline.Records.attachments** *unknown*
Files attached to this timeline record.
**Core.Case.Timeline.Records.xql\_execution\_id** *string*
The XQL Query Center execution ID linked to this record.
**Core.Case.Timeline.Records.xql\_data** *unknown*
The XQL query results linked to this record.
**Core.Case.Timeline.Metadata.returned\_count** *number*
The number of records returned in this response.
**Core.Case.Timeline.Metadata.filtered\_count** *number*
The number of records matching the applied filters.
**Core.Case.Timeline.Metadata.total\_count** *number*
The total number of records in the case timeline.
#### listTimelineTags
***
Returns all distinct tags used across timeline records for a case. Use this command to discover available tags before filtering with listTimelineRecords.
Arguments
| Argument Name | Description | Required |
| ------------- | ------------------------------------------------------------------------------------- | -------- |
| case\_id | The ID of the case for which to list tags. If omitted, returns tags across all cases. | Optional |
Outputs
**Core.Case.case\_id** *number*
The ID of the case.
**Core.Case.Timeline.Records.record\_id** *string*
The unique ID of the timeline record.
**Core.Case.Timeline.Records.record\_type** *string*
The type of the timeline record. Possible values: Case activity, Detection, Automation, System update, Response.
**Core.Case.Timeline.Records.record\_subtype** *string*
The subtype of the timeline record. For example: Note, Playbook started, Case created.
**Core.Case.Timeline.Records.record\_name** *string*
The name or title of the timeline record.
**Core.Case.Timeline.Records.description** *string*
The free-text description or content body of the timeline record.
**Core.Case.Timeline.Records.start\_ts** *number*
The date and time the record was added to the timeline (record creation time).
**Core.Case.Timeline.Records.occurred\_at** *number*
The date and time the event actually occurred. This may differ from the record creation time.
**Core.Case.Timeline.Records.origin** *string*
The source that created the record. Possible values: User, Automation, System, API Key, AI.
**Core.Case.Timeline.Records.origin\_id** *string*
The identifier of the source that created the record, for example, the username or automation name.
**Core.Case.Timeline.Records.is\_evidence** *boolean*
Whether the record is marked as evidence.
**Core.Case.Timeline.Records.evidence\_title** *string*
The title assigned to the record when it was marked as evidence.
**Core.Case.Timeline.Records.evidence\_comment** *string*
The comment provided when the record was marked as evidence.
**Core.Case.Timeline.Records.evidence\_flag\_time** *number*
The date and time the record was flagged as evidence.
**Core.Case.Timeline.Records.evidence\_flag\_by** *string*
The user who flagged the record as evidence.
**Core.Case.Timeline.Records.timelines** *string*
The named timelines this record belongs to.
**Core.Case.Timeline.Records.tags** *string*
The tags attached to this timeline record.
**Core.Case.Timeline.Records.is\_manual** *boolean*
Whether the record was created manually.
**Core.Case.Timeline.Records.attachments** *unknown*
Files attached to this timeline record.
**Core.Case.Timeline.Records.xql\_execution\_id** *string*
The XQL Query Center execution ID linked to this record.
**Core.Case.Timeline.Records.xql\_data** *unknown*
The XQL query results linked to this record.
**Core.Case.Timeline.Metadata.returned\_count** *number*
The number of records returned in this response.
**Core.Case.Timeline.Metadata.filtered\_count** *number*
The number of records matching the applied filters.
**Core.Case.Timeline.Metadata.total\_count** *number*
The total number of records in the case timeline.
#### createTimelineRecord
***
Creates a manual timeline record for a case. Manual records are always created with the subtype NOTE.
Arguments
| Argument Name | Description | Required |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| case\_id | The ID of the case. | Required |
| record\_type | The type of the timeline record. Possible values are: Case activity, Detection, Response. | Required |
| record\_name | The name or title of the timeline record. | Required |
| occurred\_at | The date and time the event actually occurred. Use this to backdate a record. Defaults to the current time if omitted. Accepts natural language and ISO 8601 formats, for example, '2 days ago' or '2024-01-15T10:00:00Z'. | Optional |
| is\_evidence | Whether to mark the record as evidence. Defaults to false. Possible values are: true, false. Default is false. | Optional |
| evidence\_comment | An optional comment to attach when marking the record as evidence. Only used when is\_evidence is true. | Optional |
| tags | A comma-separated list of tags to attach to the record. | Optional |
| description | A free-text description of the timeline record. | Optional |
| xql\_execution\_id | The XQL Query Center execution ID to link to this timeline record. | Optional |
| entry\_id | The War Room file entry ID to attach to this record. The file must already be in the War Room (uploaded by the user or returned by a prior command). Must be used together with file\_name. | Optional |
| file\_name | The display name of the file to attach (e.g. 'malware.exe'). Required when entry\_id is provided. This name appears in the timeline record and is used for downloading the attachment. | Optional |
Outputs
**Core.Case.case\_id** *number*
The ID of the case.
**Core.Case.Timeline.Records.record\_id** *string*
The ID of the newly created timeline record.
**Core.Case.Timeline.Records.attachment\_id** *string*
The UUID of the uploaded attachment.
**Core.Case.Timeline.Records.file\_name** *string*
The file name of the attachment.
**Core.Case.Timeline.Records.file\_size** *number*
The file size in bytes.
#### deleteTimelineRecord
***
Deletes a manual timeline record from a case. Only manually created records can be deleted.
Arguments
| Argument Name | Description | Required |
| ------------- | ---------------------------------------- | -------- |
| case\_id | The ID of the case. | Required |
| record\_id | The ID of the timeline record to delete. | Required |
Outputs
**Core.Case.Timeline.Records.Success** *boolean*
Success
**Core.Case.Timeline.Records.RecordID** *string*
RecordID
**Core.Case.Timeline.Records.CaseID** *number*
CaseID
#### updateTimelineRecordTags
***
Adds or removes tags on one or more timeline records. Use tags\_to\_add to append new tags; existing tags are preserved. Use tags\_to\_remove to remove specific tags; all other existing tags are preserved. Use remove\_all to clear all tags from the records. At least one of tags\_to\_add, tags\_to\_remove, or remove\_all must be provided. case\_id is required when tags\_to\_remove or remove\_all is used.
Arguments
| Argument Name | Description | Required |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| record\_ids | A comma-separated list of timeline record IDs to update. | Required |
| case\_id | The ID of the case the records belong to. Required when tags\_to\_remove or remove\_all is used. | Optional |
| tags\_to\_add | A comma-separated list of tags to add. Existing tags on the records are preserved. | Optional |
| tags\_to\_remove | A comma-separated list of tags to remove. All other existing tags on the records are preserved. | Optional |
| remove\_all | Set to true to remove all tags from the specified records. Cannot be combined with tags\_to\_add or tags\_to\_remove. Possible values are: true, false. | Optional |
Outputs
**Core.Case.Timeline.success** *boolean*
Whether the tag operation completed successfully.
**Core.Case.Timeline.is\_replace** *boolean*
Indicates whether the existing tags were fully replaced (true) or new tags were appended to the existing ones (false).
#### linkRecordToTimeline
***
Assigns one or more timeline records to a named timeline. If the named timeline does not exist, it is created automatically. Existing timeline assignments on the records are preserved. Records are appended to the specified timelines.
Arguments
| Argument Name | Description | Required |
| ------------- | -------------------------------------------------------------------------------------------------------------------------- | -------- |
| record\_ids | A comma-separated list of timeline record IDs to assign. | Required |
| timelines | A comma-separated list of named timelines to assign the records to. Timelines that do not exist are created automatically. | Required |
Outputs
**Core.Case.Timeline.success** *boolean*
Whether the operation completed successfully.
**Core.Case.Timeline.is\_replace** *boolean*
Indicates whether the existing timeline assignments were fully replaced (true) or new timelines were appended to the existing ones (false).
#### markTimelineRecordAsEvidence
***
Marks or unmarks a timeline record as evidence.
Arguments
| Argument Name | Description | Required |
| ------------- | ------------------------------------------------------------------------------------------------------------------- | -------- |
| record\_id | The ID of the timeline record to mark or unmark. | Required |
| is\_evidence | Set to true to mark the record as evidence, or false to remove the evidence mark. Possible values are: true, false. | Required |
| comment | An optional comment to attach when marking the record as evidence. Only used when is\_evidence is true. | Optional |
Outputs
**Core.Case.Timeline.Records.record\_id** *string*
The ID of the updated timeline record.
**Core.Case.Timeline.Records.is\_evidence** *boolean*
The evidence status of the record after the operation.
**Core.Case.Timeline.Records.success** *boolean*
Whether the operation completed successfully.
---
# 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/cortex-commands-guide/timeline-commands.md?ask=&goal=
```
`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.