> ## Documentation Index > Fetch the complete documentation index at: https://docs.tracecat.com/llms.txt > Use this file to discover all available pages before exploring further. # Cases ## `core.cases.create_case` Create a new case. ### Inputs The description of the case. The summary of the case. If true, create any tags that do not already exist. Default: `false`. Dropdown selections to set on the case. Each item must include either definition\_id or definition\_ref, and either option\_id or option\_ref (or null to clear). Default: `null`. Custom fields for the case. Default: `null`. Payload for the case. Default: `null`. The priority of the case. Default: `"unknown"`. Allowed values: `unknown`, `low`, `medium`, `high`, `critical`, `other`. The severity of the case. Default: `"unknown"`. Allowed values: `unknown`, `informational`, `low`, `medium`, `high`, `critical`, `fatal`, `other`. The status of the case. Default: `"unknown"`. Allowed values: `unknown`, `new`, `in_progress`, `on_hold`, `resolved`, `closed`, `other`. List of tag identifiers (IDs or refs) to add to the case. Default: `null`. ### Examples **Create a case** ```yaml theme={null} - ref: create_case action: core.cases.create_case args: summary: "Investigate alert ${{ TRIGGER.alert_id }}" description: "Created from workflow trigger." priority: high severity: high tags: - phishing ``` ## `core.cases.get_case` Get details of a specific case by ID. ### Inputs The ID of the case to retrieve. ### Examples **Get a case** ```yaml theme={null} - ref: get_case action: core.cases.get_case args: case_id: ${{ TRIGGER.case_id }} ``` ## `core.cases.update_case` Update an existing case. ### Inputs The ID of the case to update. If true, append the provided description to the existing description when it is not empty. Default: `false`. If true, create any tags that do not already exist. Default: `false`. The updated description of the case. Default: `null`. Dropdown selections to set or clear. Each item must include either definition\_id or definition\_ref, and either option\_id or option\_ref (or null to clear). Default: `null`. Updated custom fields for the case. Default: `null`. Updated payload for the case. Default: `null`. The updated priority of the case. Default: `null`. The updated severity of the case. Default: `null`. The updated status of the case. Default: `null`. The updated summary of the case. Default: `null`. List of tag identifiers (IDs or refs) to set on the case. This will replace all existing tags. Default: `null`. ### Examples **Update case fields** ```yaml theme={null} - ref: update_case action: core.cases.update_case args: case_id: ${{ TRIGGER.case_id }} status: in_progress priority: critical append: true description: | Analyst note: - Escalated after credential theft indicators were confirmed. ``` ## `core.cases.list_cases` List all cases. ### Inputs Pagination cursor used to fetch a specific page when paginate=true. Default: `null`. Maximum number of cases to return. Default: `100`. The field to order the cases by. Default: `null`. If true, return cursor pagination metadata along with items. Default: `false`. Reverse pagination direction when paginate=true. Default: `false`. The direction to order the cases by. Default: `null`. ### Examples **List cases** ```yaml theme={null} - ref: list_cases action: core.cases.list_cases args: limit: 25 order_by: updated_at sort: desc ``` ## `core.cases.search_cases` Search cases based on various criteria. ### Inputs Filter by assignee ID or 'unassigned'. Default: `null`. Pagination cursor used to fetch a specific page when paginate=true. Default: `null`. Filter by dropdown values in definition\_ref:option\_ref format. Default: `null`. Filter cases created before this time. Default: `null`. Maximum number of cases to return. Default: `100`. The field to order the cases by. Default: `null`. If true, return cursor pagination metadata along with items. Default: `false`. Filter by case priority. Default: `null`. Reverse pagination direction when paginate=true. Default: `false`. Text to search for in case summary and description. Default: `null`. Filter by case severity. Default: `null`. Filter by case short\_id. Default: `null`. The direction to order the cases by. Default: `null`. Filter cases created after this time. Default: `null`. Filter by case status. Default: `null`. Filter by tag IDs or refs (AND logic). Default: `null`. Filter cases updated after this time. Default: `null`. Filter cases updated before this time. Default: `null`. ### Examples **Search cases** ```yaml theme={null} - ref: search_cases action: core.cases.search_cases args: search_term: phishing status: - new - in_progress limit: 25 ``` ## `core.cases.aggregate_cases` Filter, group, and summarize workspace cases. Returns groups and a truncated flag indicating whether more groups exist than the requested limit. ### Inputs Choose how to split cases into groups. Use up to 3 fields, or `[]` for one total across all matching cases. Supply a field name such as `priority`, or an object with `field` and optional `bucket`, `timezone`, and `alias`. For example: \['priority', \{'field': 'created\_at', 'bucket': 'day'}]. An alias names the field in the result; it defaults to the field name. Output names must be unique and at most 63 UTF-8 bytes. Fields you can group by: * Built-in fields: `status`, `priority`, `severity`, and `assignee_id` (a user UUID). * Custom fields: `fields.region`, replacing `region` with a defined field name. URL fields use the URL, not the display label. LONG\_TEXT fields work as text. Other JSONB fields and MULTI\_SELECT fields are unsupported. * Dates and times: `created_at`, `updated_at`, and custom date/time fields. These require a `bucket`: `hour`, `day`, `week`, or `month`. Weeks start on Monday. Date and time settings: * Timestamps accept an IANA timezone name, such as `America/New_York`. The default is `UTC`; results always contain UTC timestamps. * DATE fields return `YYYY-MM-DD`. They do not accept a timezone, and even an `hour` bucket retains only date precision. How group values appear in results: * Missing values share one `null` group, including cases with no saved custom fields. * TEXT and SELECT values use only the first 256 characters. Values with the same prefix merge into one group. * NUMERIC values appear as exact decimal strings. If your server supports tag and dropdown aggregation: * Use `dropdowns.category` to group by option reference; replace `category` with your dropdown reference. This requires case add-ons. Missing or deleted options share the `null` group. * Use `tags` to group by tag reference. A case belongs to every tag group that applies to it; untagged cases share the `null` group. Adding the group counts can therefore count a case more than once. Choose what to calculate for each group. Omit this input to count cases. Supply up to 8 calculations; an empty list is invalid. Each calculation is an object with `function`, optional `field`, and optional `alias`. For example: \[\{'function': 'sum', 'field': 'fields.amount', 'alias': 'total'}]. Available calculations: * `count`: Count cases when you omit `field`, or count non-null values when you supply it. * `count_distinct`: Count different non-null values. * `sum`, `mean`, `median`: Calculate the total, average, or middle value. * `min`, `max`: Return the smallest or largest value. Every function except `count` requires a field. Numeric custom fields support all functions. Text and date/time fields support `count`, `count_distinct`, `min`, and `max`. BOOLEAN and SELECT fields support only `count` and `count_distinct`. Naming and number formats: * Use `alias` to name a result, such as `total`. Otherwise the name is `count` or `function_field`, using the final part of the field name. All output names must be unique and at most 63 UTF-8 bytes. * Counts are integers. INTEGER/NUMERIC sums, all means and medians, and NUMERIC min/max use floating-point numbers and can lose precision. NUMERIC grouping values remain exact decimal strings. When grouping by tags, counts and `min_count` count each case once within each group. You cannot use `sum`, `mean`, or `median` with tag grouping. Default: `null`. Choose which cases to include before grouping. Omit this input to include all cases. Write one condition as \{field, op, value}. For example: \{'field': 'status', 'op': 'in', 'value': \['new', 'in\_progress']}. Combine conditions with \{'and': \[...]}, \{'or': \[...]}, or \{'not': \{...}}. Choose an operator supported by the field type: * Equality: `eq` (equals), `ne` (does not equal). * Lists: `in` (matches any listed value), `not_in` (matches none). Supply a list as `value`. * Ranges: `gt`, `gte`, `lt`, `lte` (greater than, at least, less than, at most). * Text: `contains`, `starts_with`. Both ignore case and match literal text. * Missing values: `is_null`. Omit `value`; custom fields also match cases with no saved field row. You can filter on grouping fields, plus `summary`, `description`, and `case_number`. You cannot filter on `short_id` or `payload`. Use strings for exact decimals and ISO-formatted dates or timestamps. Built-in values must be lowercase: * Status: `unknown`, `new`, `in_progress`, `on_hold`, `resolved`, `closed`, `other`. Status does not support range comparisons. * Priority, from lowest to highest: `low`, `medium`, `high`, `critical`. * Severity, from lowest to highest: `informational`, `low`, `medium`, `high`, `critical`, `fatal`. * Priority and severity also accept `unknown` and `other` for equality or list matching. These values never match a range and cannot be range boundaries. Special cases and limits: * `ne` and `not_in` exclude missing values. An empty `not_in` list matches all cases; an empty `in` list matches none. * Where tag aggregation is supported, `tags` accepts `contains` (one tag reference), `in` (any listed reference), or `is_null` (untagged). * Filters allow up to 4 levels of nesting, 50 conditions, and 1000 total values. The server validates the request when the action runs. Default: `null`. Set the maximum number of groups to return. Use at least 1, up to your server's configured maximum (normally 1000). Omit this input to use the server default (normally 100). If more groups exist, the result sets `truncated` to `true`. There is no next-page cursor. Default: `null`. Only return groups with at least this many cases (minimum 1). Default: `null`. Choose a group or calculation output name to sort by, including any alias you set. If omitted, results sort by the first date/time bucket, or by the first calculation when there is no date/time bucket. Default: `null`. Use `asc` for ascending order or `desc` for descending order. If omitted, the direction is `asc` when the action automatically sorts by a date/time bucket. Otherwise it is `desc`, including when you set `order_by` yourself. Missing values sort last; group values break ties. Default: `null`. ### Examples **Count open cases by priority and day** ```yaml theme={null} - ref: cases_by_priority_per_day action: core.cases.aggregate_cases args: filters: and: - field: status op: in value: [new, in_progress] - field: created_at op: gte value: "2026-01-01T00:00:00Z" group_by: - priority - field: created_at bucket: day aggs: - function: count limit: 100 ``` ## `core.cases.list_case_events` List all events for a case in chronological order. ### Inputs The ID of the case to get events for. ### Examples **List case events** ```yaml theme={null} - ref: list_case_events action: core.cases.list_case_events args: case_id: ${{ TRIGGER.case_id }} ``` ## `core.cases.assign_user` Assign a user to an existing case. ### Inputs The ID of the user to assign to the case. The ID of the case to assign a user to. ### Examples **Assign a user by ID** ```yaml theme={null} - ref: assign_user action: core.cases.assign_user args: case_id: ${{ TRIGGER.case_id }} assignee_id: ${{ TRIGGER.assignee_id }} ``` ## `core.cases.assign_user_by_email` Assign a user to an existing case by email. ### Inputs The email of the user to assign to the case. The ID of the case to assign a user to. ### Examples **Assign a user by email** ```yaml theme={null} - ref: assign_user_by_email action: core.cases.assign_user_by_email args: case_id: ${{ TRIGGER.case_id }} assignee_email: analyst@example.com ``` ## `core.cases.add_case_tag` Add a tag to a case by tag ID or ref. ### Inputs The ID of the case to add a tag to. The tag identifier (ID or ref) to add to the case. If true, create the tag if it does not exist. Default: `false`. ### Examples **Add a case tag** ```yaml theme={null} - ref: add_case_tag action: core.cases.add_case_tag args: case_id: ${{ TRIGGER.case_id }} tag: credential-theft create_if_missing: true ``` ## `core.cases.remove_case_tag` Remove a tag from a case by tag ID or ref. ### Inputs The ID of the case to remove a tag from. The tag identifier (ID or ref) to remove from the case. ### Examples **Remove a case tag** ```yaml theme={null} - ref: remove_case_tag action: core.cases.remove_case_tag args: case_id: ${{ TRIGGER.case_id }} tag: needs-triage ``` ## `core.cases.delete_case` Delete a case. ### Inputs The ID of the case to delete. ### Examples **Delete a case** ```yaml theme={null} - ref: delete_case action: core.cases.delete_case args: case_id: ${{ TRIGGER.case_id }} ``` ## `core.cases.get_case_metrics` Get case metrics as OTEL-aligned time-series for the provided case IDs. Enterprise Edition ### Inputs List of case IDs to get case metrics for. ### Examples **Read case metrics** ```yaml theme={null} - ref: case_metrics action: core.cases.get_case_metrics args: case_ids: - ${{ TRIGGER.case_id }} - ${{ TRIGGER.related_case_id }} ```