Search the Octopus audit log
find_eventsSearch the Octopus Deploy audit log to find deployments, releases, modifications, user logins, and other recorded actions. Filter by user, project, environment, date range, and more.
Instructions
Search the Octopus Deploy audit log (also called the Events log) — every meaningful action recorded against a space: deployments, release creations, modifications, user logins, machine registrations, variable edits, tenant changes, and so on.
Modes (the mode arg):
search(default) — query the audit log. RequiresspaceName. Supports rich filtering by user, project, environment, tenant, document type, date range, category, group, and agent.listCategories— enumerate every event category (e.g.DeploymentSucceeded).listGroups— enumerate event groups (e.g.Created,Modified,Deleted,Deployment). Each group lists the categories inside it.listAgents— enumerate user-agent strings recorded by the audit subsystem.listDocumentTypes— enumerate entity-prefix metadata (Projects-,Releases-, ...).
Search modes (within mode='search', picked by argument shape):
eventId→ fetch that single event. Mutually exclusive with list and pagination filters;excludeDifferenceis still honoured.otherwise → list events matching the filters, paginated.
Performance tip: the per-event ChangeDetails field (the before/after diff for Modified events) is by far the heaviest payload field. Pass excludeDifference: true whenever scanning many events; fetch a single event without the flag when you need the diff.
Filter semantics:
regarding— AND semantics: event must reference EVERY listed document ID.regardingAny— OR semantics: event must reference ANY listed document ID.All other multi-value filters (users, projects, environments, tenants, eventCategories, eventGroups, ...) are OR semantics within the field.
from(inclusive) andto(exclusive) accept ISO 8601 datetimes.
Permissions: requires EventView on the calling user's space scope. The server filters results further based on per-document permissions.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | What to return. Defaults to 'search' (the audit log itself). Metadata modes enumerate valid filter values: listCategories returns every event category (e.g. DeploymentSucceeded, ReleaseCreated); listGroups returns category groupings (Created/Modified/Deleted/Deployment/Interruption/...); listAgents returns the user-agent strings seen by the audit subsystem; listDocumentTypes returns entity-prefix metadata (Projects-, Releases-, ...). Use a metadata mode first when you need to construct an eventCategories/eventGroups/documentTypes filter and don't know the valid values. Metadata modes ignore every other argument. | |
| spaceName | No | Space name. Required for mode='search'. Ignored by metadata modes (they are server-wide). | |
| eventId | No | Fetch a single event by ID (form 'Events-NNN'). Mutually exclusive with list and pagination filters (regarding, regardingAny, users, projects, environments, tenants, projectGroups, eventCategories, eventGroups, eventAgents, documentTypes, tags, from, to, skip, take). Compatible with excludeDifference (still honoured) and includeInternalEvents (no-op for single fetches). | |
| regarding | No | Document IDs the event must relate to. AND semantics: event must reference EVERY id listed. Use regardingAny for OR semantics. | |
| regardingAny | No | Document IDs the event may relate to. OR semantics: event references ANY id listed. | |
| users | No | User IDs who triggered the event (OR semantics within the list). | |
| projects | No | Project IDs the event relates to (OR semantics). | |
| environments | No | Environment IDs the event relates to (OR semantics). | |
| tenants | No | Tenant IDs the event relates to (OR semantics). | |
| projectGroups | No | Project group IDs. Events for any project inside these groups are included. | |
| eventCategories | No | Event category names, e.g. ['DeploymentSucceeded','DeploymentFailed']. Use mode='listCategories' to discover the full set. | |
| eventGroups | No | Event group names, e.g. ['Created','Modified','Deleted','Deployment','Interruption']. Each group is expanded server-side to the categories it contains. Use mode='listGroups' to discover the full set. | |
| eventAgents | No | User-agent strings of the clients that triggered the events. Use mode='listAgents' to discover the values present in this instance. | |
| documentTypes | No | Document type prefixes, e.g. ['Projects-','Releases-']. Use mode='listDocumentTypes' to discover the full set. | |
| tags | No | Canonical tenant tag IDs of the form 'TagSetName/TagName'. Filters events whose related tenants carry these tags. | |
| from | No | ISO 8601 datetime. Inclusive lower bound on Occurred (Occurred >= from). | |
| to | No | ISO 8601 datetime. Exclusive upper bound on Occurred (Occurred < to). | |
| includeInternalEvents | No | Default true. Set false to suppress per-target MachineAdded / MachineDeleted / MachineDeploymentRelatedPropertyWasUpdated noise that floods machine-heavy instances. | |
| excludeDifference | No | Set true to omit the ChangeDetails field (the before/after diff). ChangeDetails is by far the heaviest field per event — recommended for any scan of more than a few events. | |
| skip | No | Pagination offset (search mode only). | |
| take | No | Pagination page size (search mode only). Server default is 30. |