Cases - Tracecat Docs

`core.cases.create_case`

Create a new case.

Inputs

string

required

The description of the case.

string

required

The summary of the case.

boolean

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.

object | null

Custom fields for the case.Default: null.

object | null

Payload for the case.Default: null.

string

The priority of the case.Default: "unknown".Allowed values: unknown, low, medium, high, critical, other.

string

The severity of the case.Default: "unknown".Allowed values: unknown, informational, low, medium, high, critical, fatal, other.

string

The status of the case.Default: "unknown".Allowed values: unknown, new, in_progress, on_hold, resolved, closed, other.

array[string] | null

List of tag identifiers (IDs or refs) to add to the case.Default: null.

Examples

Create a case

- 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

string

required

The ID of the case to retrieve.

Examples

Get a case

- ref: get_case
  action: core.cases.get_case
  args:
    case_id: ${{ TRIGGER.case_id }}

`core.cases.update_case`

Update an existing case.

Inputs

string

required

The ID of the case to update.

boolean

If true, append the provided description to the existing description when it is not empty.Default: false.

boolean

If true, create any tags that do not already exist.Default: false.

string | null

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.

object | null

Updated custom fields for the case.Default: null.

object | null

Updated payload for the case.Default: null.

string | null

The updated priority of the case.Default: null.

string | null

The updated severity of the case.Default: null.

string | null

The updated status of the case.Default: null.

string | null

The updated summary of the case.Default: null.

array[string] | 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

- 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

string | null

Pagination cursor used to fetch a specific page when paginate=true.Default: null.

integer

Maximum number of cases to return.Default: 100.

string | null

The field to order the cases by.Default: null.

boolean

If true, return cursor pagination metadata along with items.Default: false.

boolean

Reverse pagination direction when paginate=true.Default: false.

string | null

The direction to order the cases by.Default: null.

Examples

List cases

- 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

string | array[string] | null

Filter by assignee ID or ‘unassigned’.Default: null.

string | 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.

string | null

Filter cases created before this time.Default: null.

integer

Maximum number of cases to return.Default: 100.

string | null

The field to order the cases by.Default: null.

boolean

If true, return cursor pagination metadata along with items.Default: false.

string | array[string] | null

Filter by case priority.Default: null.

boolean

Reverse pagination direction when paginate=true.Default: false.

string | null

Text to search for in case summary and description.Default: null.

string | array[string] | null

Filter by case severity.Default: null.

string | null

Filter by case short_id.Default: null.

string | null

The direction to order the cases by.Default: null.

string | null

Filter cases created after this time.Default: null.

string | array[string] | null

Filter by case status.Default: null.

array[string] | null

Filter by tag IDs or refs (AND logic).Default: null.

string | null

Filter cases updated after this time.Default: null.

string | null

Filter cases updated before this time.Default: null.

Examples

Search cases

- 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. The example counts new and in_progress cases by priority and day. It includes cases created on or after August 1, 2026 whose priority is high or critical, or whose region is emea. Before running it, create a TEXT custom case field named region. Use ACTIONS.cases_by_priority_per_day.result.groups to read the results. Each item contains a priority, a date, and a case count. If ACTIONS.cases_by_priority_per_day.result.truncated is true, the result reached the group limit and omitted some groups.

Inputs

array[string | object]

required

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.

array[object] | null

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.

object | 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.

integer | 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.

integer | null

Only return groups with at least this many cases (minimum 1).Default: null.

string | 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.

string | 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

- 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-08-01T00:00:00Z"
        - or:
            - field: priority
              op: gte
              value: high
            - field: fields.region
              op: eq
              value: emea
    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

string

required

The ID of the case to get events for.

Examples

List case events

- 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

string

required

The ID of the user to assign to the case.

string

required

The ID of the case to assign a user to.

Examples

Assign a user by ID

- 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

string

required

The email of the user to assign to the case.

string

required

The ID of the case to assign a user to.

Examples

Assign a user by email

- 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

string

required

The ID of the case to add a tag to.

string

required

The tag identifier (ID or ref) to add to the case.

boolean

If true, create the tag if it does not exist.Default: false.

Examples

Add a case tag

- 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

string

required

The ID of the case to remove a tag from.

string

required

The tag identifier (ID or ref) to remove from the case.

Examples

Remove a case tag

- 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

string

required

The ID of the case to delete.

Examples

Delete a case

- 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

array[string]

required

List of case IDs to get case metrics for.

Examples

Read case metrics

- ref: case_metrics
  action: core.cases.get_case_metrics
  args:
    case_ids:
      - ${{ TRIGGER.case_id }}
      - ${{ TRIGGER.related_case_id }}

​core.cases.create_case

​Inputs

​Examples

​core.cases.get_case

​Inputs

​Examples

​core.cases.update_case

​Inputs

​Examples

​core.cases.list_cases

​Inputs

​Examples

​core.cases.search_cases

​Inputs

​Examples

​core.cases.aggregate_cases

​Inputs

​Examples

​core.cases.list_case_events

​Inputs

​Examples

​core.cases.assign_user

​Inputs

​Examples

​core.cases.assign_user_by_email

​Inputs

​Examples

​core.cases.add_case_tag

​Inputs

​Examples

​core.cases.remove_case_tag

​Inputs

​Examples

​core.cases.delete_case

​Inputs

​Examples

​core.cases.get_case_metrics

​Inputs

​Examples

`core.cases.create_case`

Inputs

Examples

`core.cases.get_case`

Inputs

Examples

`core.cases.update_case`

Inputs

Examples

`core.cases.list_cases`

Inputs

Examples

`core.cases.search_cases`

Inputs

Examples

`core.cases.aggregate_cases`

Inputs

Examples

`core.cases.list_case_events`

Inputs

Examples

`core.cases.assign_user`

Inputs

Examples

`core.cases.assign_user_by_email`

Inputs

Examples

`core.cases.add_case_tag`

Inputs

Examples

`core.cases.remove_case_tag`

Inputs

Examples

`core.cases.delete_case`

Inputs

Examples

`core.cases.get_case_metrics`

Inputs

Examples