Skip to content

Audit Log ​

The audit log records past events across the domain. Use it for what the instance tools can't answer: instances whose workflow logs have been cleaned up, finding a workflow's past instances, and changes to workflows and other objects. Search it with audit_search.

When to use it ​

  • You know the instance. Call get_instance_status with the workflow ID and the instance ID. It reloads confirmed instances from their workflow logs, so it returns an instance's state, start and completion times, and who confirmed it after the instance has left the queue. Use the audit log for that instance only when get_instance_status reports it not found. If its workflow log has been cleaned up under the workflow's Retain Logs setting, the audit log is the only record. If its workflow has been deleted or is no longer approved, or the user can't see the workflow, only an administrator's search shows its entries.
  • You need to find an instance. "Last night's EOD" or "the one that failed on Tuesday" means finding its instance ID first. Search the audit log for the workflow's instances. Then pass both the workflow ID and the instance ID to the instance tools: get_instance_status, get_root_cause, query_workflow_log, get_workflow_log and the others need both once an instance has left the queue.
  • You need to know what changed. Changes to a workflow, a workflow group, an asset, a user, a Situate group and other objects are recorded under their own entry classes. Only administrators can search the classes other than WorkflowInstance and Workflow.
  • An instance that never reached the queue. An instance that fails before it is queued still has its start and end recorded in the audit log, although it never appears in list_instances.

Parameters ​

ParameterRequiredMeaning
startyesStart of the time window, ISO 8601 with a time zone offset (Z, or +hh:mm or -hh:mm), such as 2026-11-06T09:00:00-05:00. A time without an offset is an error.
endyesEnd of the window, the same form. Must be after start.
entryClassyesOne entry class (see below).
idnoOnly entries for this object. For WorkflowInstance, the instance ID; for Workflow, the workflow ID.
id2noOnly entries with this secondary ID. For WorkflowInstance, the workflow ID: every instance of that workflow whose entries have it set, which older instances' entries don't. Not set for other entry classes.
limitnoEntries per page, 1 to 500. Default 100.
continuationnoThe token from the previous reply, to get the next page. Pass the same start, end, entryClass, id and id2 with it.

Entry classes: WorkflowInstance, Workflow, WorkflowGroup, Asset, AssetGroup, User, SituateGroup, AuthenticationService, Calendar, System, DeployProject, DeployRelease, DeployReleaseInstance.

What comes back ​

  • Entries are returned newest first.
  • Each entry's class-specific values are in its values. The reply's headings names them; an entry whose values have different names has its own headings. Read headings rather than assuming which values an entry has.
  • time, startTime, and the timeApproved, timeSubmitted and timeStarted values are { value, label }: value in ISO 8601 UTC, label in the user's time zone and locale. A time of 0 is { value: 0 }, with no label: none.
  • severity is info, warn or error, and status, when present, is success, failed or canceled. These are not alert levels.
  • groupId is, for a WorkflowInstance or Workflow entry, the ID of the workflow's workflow group, except on the Workflow entry for an approved workflow removed because it had no next execution time, where it is the workflow's ID.
  • If the reply has a continuation, more entries may match. Call again with it to get the next page.
  • total, when present, is the number of rows the page's query read, not the number of matching entries.

Finding instances ​

One instance, by instance ID: entryClass WorkflowInstance, id set to the instance ID. One instance has several entries: when it started, when it completed, when it was confirmed, and when its history was cleaned up.

A workflow's instances: entryClass WorkflowInstance, id2 set to the workflow ID. This finds only instances whose entries have the workflow ID set, which older instances' entries don't. For those, search the time window without id2 and match the workflow ID in each entry's values: it is values[1] (check headings).

Changes to a workflow: entryClass Workflow, id set to the workflow ID.

Searching well ​

  • start and end are always required, each with a time zone offset. They are matched against each entry's logged time (time), not its startTime. Use the narrowest window that answers the question, and widen it step by step if nothing turns up. Read times the user gives, such as "last night", in their time zone, and pass them with its offset.
  • Filter with id or id2 whenever you know the ID. An unfiltered class over a long window returns many unrelated entries.
  • Use IDs, not names, to match entries. Workflow names can change.
  • Users who aren't administrators can search only WorkflowInstance and Workflow, and see only entries for workflows they can see. Entries of a workflow that has been deleted or is no longer approved are left out for them, and the reply doesn't say so. The filter runs after the page is read, so a page can have fewer entries than limit, or none, while continuation is still set: follow it before concluding there's nothing.
  • Page with continuation only as far as the question needs. When you stop with a continuation still in the reply, say that more entries may exist.
  • An instance that's missing from the queue was most likely confirmed, automatically or by an operator. get_instance_status still finds it. Check before concluding that a workflow didn't execute.
  • An instance's confirm entry is flagged newsworthy when its workflow's Alert Behavior is Urgent; audit_search doesn't show the flag.
  • Report what the entries show (who, when and what happened) in plain words, naming instances by workflow and time rather than by ID (prefix, section 1, Naming an instance). Don't paste raw entries.

Workload Automation and Orchestration