Events

Events are automatically created when significant actions take place within Octopus by users.

Examples are adding environments, modifying projects, deploying releases, canceling tasks, and so on. Events can be used to provide an audit trail of what has happened in the system.

The HTTP API cannot be used to add, modify or delete events.

List Events

GET /api/{spaceId}/events

Also reachable at /api/events, /api/spaces/{spaceIdentifier}/events.

A list of all audit events collected to date, ordered by the date of the event in descending order. Events can be filtered by various criteria and can be returned as a csv file when the optional parameter ‘asCsv’ is set to true.

Path Parameters

spaceId string (required)

Query Parameters

asCsv boolean
Returns list of events as a csv file when set to true.
documentTypes array of string
The document types to be matched, provided as a comma separated list of strings.
environments array of string
The environment ids to be matched, provided as a comma separated list of strings.
eventAgents array of string
The event agents to be matched, provided as a comma separated list of strings.
eventCategories array of string
The event categories to be matched, provided as a comma separated list of strings.
eventGroups array of string
The event groups to be matched, provided as a comma separated list of strings.
excludeDifference boolean
Omits the change details of all events when set to true.
from string
Filter events that occurred after this datetime. Format date-time.
fromAutoId integer
Filter events after specified autoId.
ids string
The event ids to be matched, provided as a comma separated list of strings.
includeInternalEvents boolean
Exclude the machine-related CRUD events that were added for auto-deploy events.
projectGroups array of string
The project group ids to be matched, provided as a comma separated list of strings.
projects array of string
The project ids to be matched, provided as a comma separated list of strings.
regarding array of string
The related document ids to be matched, provided as a comma separated list of strings.
regardingAny array of string
The related document ids to be matched, provided as a comma separated list of strings.
skip integer
Number of items to skip. Defaults to zero. Minimum 0.
tags array of string
The canonical tag ids to be matched, provided as a comma separated list of strings.
take integer
Number of items to take. Defaults to 30. Minimum 0.
tenants array of string
The tenant ids to be matched, provided as a comma separated list of strings.
to string
Filter events that occurred before this datetime. Format date-time.
toAutoId integer
Filter events before specified autoId.
user string
users array of string
The user ids to be matched, provided as a comma separated list of strings.

Response

200 — A paginated list of events, unless AsCsv is true, in which case a text/csv file is returned

Id string
Gets or sets a unique identifier for this resource.
ItemType string
The type of item in this list.
Items array of object
- ApiKeyHint string
  Gets or sets the obfuscated hint of the API key used to authenticate the request, if applicable.
- ApiKeyId string
  Gets or sets the ID of the API key used to authenticate the request, if applicable.
- Category string
  Gets or sets the event category.
- ChangeDetails object
- Comments string
  Gets or sets any user-provided comments that were recorded with the event.
- Details string
  Gets or sets the details of the event. For events representing a modification to a document use the ChangeDetails property.
- Id string
  Gets or sets a unique identifier for this resource.
- IdentityEstablishedWith string
  Gets or sets a description of how the user performing the event identified themselves to Octopus.
- IpAddress string
  The IP address of the user that created the event.
- IsService boolean
  Gets or sets whether the user who created the event is a service user or an interactive user.
- LastModifiedBy string
  Gets or sets the username of the user who last modified this resource.
- LastModifiedOn string
  Gets or sets the date/time that this resource was last modified. Format date-time.
- Links object
  Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.
- Message string
  Gets or sets the message text that summarizes the event.
- MessageHtml string
  Gets or sets the message text that summarizes the event, HTML formatted with links to the related documents.
- MessageReferences array of object
  Gets or sets an array of document ID’s and indexes where they are mentioned in the message text.
- Occurred string
  Gets or sets the date/time that the event took place. Format date-time.
- RelatedDocumentIds array of string
  Gets or sets a collection of document ID’s that this event relates to. Note that the document ID’s may no longer exist.
- SpaceId string
  Gets or sets the SpaceId of the event. This represents the space in which the event was raised.
- UserAgent string
  Gets or sets the user agent header value from the request that triggered the event.
- UserId string
  Gets or sets the ID of the user who created the event.
- Username string
  Gets or sets the name of the user who created the event.
ItemsPerPage integer
LastModifiedBy string
Gets or sets the username of the user who last modified this resource.
LastModifiedOn string
Gets or sets the date/time that this resource was last modified. Format date-time.
LastPageNumber integer
Links object
Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.
NumberOfPages integer
TotalResults integer

{
  "Id": "string",
  "ItemType": "Event",
  "Items": [
    {
      "ApiKeyHint": null,
      "ApiKeyId": null,
      "Category": "Modified",
      "ChangeDetails": {
        "Differences": [
          {
            "path": "/IsDisabled",
            "op": "replace",
            "value": true
          }
        ],
        "DocumentContext": {
          "Id": "Tenants-1",
          "Name": "ExampleTenant"
        }
      },
      "Comments": "string",
      "Details": "string",
      "Id": "string",
      "IdentityEstablishedWith": "Session cookie",
      "IpAddress": "127.0.0.1",
      "IsService": false,
      "LastModifiedBy": "string",
      "LastModifiedOn": "2020-01-01T00:00:00.000Z",
      "Links": {
        "Self": "/api/..."
      },
      "Message": "Tenant ExampleTenant was modified",
      "MessageHtml": "Tenant ExampleTenant was modified",
      "MessageReferences": [
        {}
      ],
      "Occurred": "2020-01-01T00:00:00.000Z",
      "RelatedDocumentIds": [
        "Tenants-1"
      ],
      "SpaceId": "Spaces-1",
      "UserAgent": "OctopusClient-js/2026.3.15581",
      "UserId": "Users-1",
      "Username": "MyUserName"
    }
  ],
  "ItemsPerPage": 30,
  "LastModifiedBy": "string",
  "LastModifiedOn": "2020-01-01T00:00:00.000Z",
  "LastPageNumber": 1,
  "Links": {
    "Self": "/api/..."
  },
  "NumberOfPages": 2,
  "TotalResults": 42
}

List Event Agents

GET /api/{spaceId}/events/agents

Also reachable at /api/events/agents, /api/spaces/{spaceIdentifier}/events/agents.

An Event Agent represents a source of events. Agents are either well known, or remote.

Well-known agents are represented in the response list by an Id and Name:

{ "Id": "Server", "Name": "Octopus Server task" }

Remote agents are represented in the response list by their HTTP User-Agent:

{ "Id": "curl/8.7.1", "Name": "curl/8.7.1" }

Path Parameters

spaceId string (required)
Ignored. All Event Agents known to the system are returned.

Response

200 — The requested event agents

Id string
A well-known identifier for a source of Events, or the HTTP User-Agent of a remote client which generated one or more events.
Links object
The Links property is not set but exists for backwards compatibility.
Name string
A well-known name for a source of Events, or the HTTP User-Agent of a remote client which generated one or more events.

[
  {
    "Id": "curl/8.7.1",
    "Links": null,
    "Name": "curl/8.7.1"
  }
]

List Event Categories

GET /api/{spaceId}/events/categories

Also reachable at /api/events/categories, /api/spaces/{spaceIdentifier}/events/categories.

Path Parameters

spaceId string (required)
Ignored.

Query Parameters

appliesTo string
Limits the results to event categories that apply to a particular document type.

Response

200 — The requested Event Categories

Id string
The ID of the Event Category.
Links object
The Links property is not set but exists for backwards compatibility.
Name string
The display name of the Event Category.

[
  {
    "Id": "Created",
    "Links": null,
    "Name": "Document created"
  }
]

List Document Types

GET /api/{spaceId}/events/documenttypes

Also reachable at /api/events/documenttypes, /api/spaces/{spaceIdentifier}/events/documenttypes.

The list of document types that you can use for the documentTypes parameter when searching for events. Use the Document Type Id.

Path Parameters

spaceId string (required)
Ignored.

Response

200 — List of event document types.

Id string
Document Type Identifier.
Name string
Display name for the Document Type.

[
  {
    "Id": "ProjectGroups",
    "Name": "Project Group"
  }
]

List Event Groups

GET /api/{spaceId}/events/groups

Also reachable at /api/events/groups, /api/spaces/{spaceIdentifier}/events/groups.

The list of event groups that you can use when searching for events

Path Parameters

spaceId string (required)
Ignored.

Query Parameters

appliesTo string
Filter results to only include Event Groups which are related to the provided string. eg. ‘Machine’.

Response

200 — A list of subscription event groups.

EventCategories array of string
Id string
Links object
Name string

[
  {
    "EventCategories": [
      "Created",
      "Modified",
      "Deleted"
    ],
    "Id": "Document",
    "Links": null,
    "Name": "Document events"
  }
]

Get a single event by ID

GET /api/{spaceId}/events/{id}

Also reachable at /api/events/{id}, /api/spaces/{spaceIdentifier}/events/{id}.

Path Parameters

id string (required)
The ID of the event.
spaceId string (required)
The ID of the space containing the resource(s).

Response

200 — The requested event

ApiKeyHint string
Gets or sets the obfuscated hint of the API key used to authenticate the request, if applicable.
ApiKeyId string
Gets or sets the ID of the API key used to authenticate the request, if applicable.
Category string
Gets or sets the event category.
ChangeDetails object
- Differences string
- DocumentContext string
Comments string
Gets or sets any user-provided comments that were recorded with the event.
Details string
Gets or sets the details of the event. For events representing a modification to a document use the ChangeDetails property.
Id string
Gets or sets a unique identifier for this resource.
IdentityEstablishedWith string
Gets or sets a description of how the user performing the event identified themselves to Octopus.
IpAddress string
The IP address of the user that created the event.
IsService boolean
Gets or sets whether the user who created the event is a service user or an interactive user.
LastModifiedBy string
Gets or sets the username of the user who last modified this resource.
LastModifiedOn string
Gets or sets the date/time that this resource was last modified. Format date-time.
Links object
Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.
Message string
Gets or sets the message text that summarizes the event.
MessageHtml string
Gets or sets the message text that summarizes the event, HTML formatted with links to the related documents.
MessageReferences array of object
Gets or sets an array of document ID’s and indexes where they are mentioned in the message text.
- Length integer
- ReferencedDocumentId string
- StartIndex integer
Occurred string
Gets or sets the date/time that the event took place. Format date-time.
RelatedDocumentIds array of string
Gets or sets a collection of document ID’s that this event relates to. Note that the document ID’s may no longer exist.
SpaceId string
Gets or sets the SpaceId of the event. This represents the space in which the event was raised.
UserAgent string
Gets or sets the user agent header value from the request that triggered the event.
UserId string
Gets or sets the ID of the user who created the event.
Username string
Gets or sets the name of the user who created the event.

{
  "ApiKeyHint": null,
  "ApiKeyId": null,
  "Category": "Modified",
  "ChangeDetails": {
    "Differences": [
      {
        "path": "/IsDisabled",
        "op": "replace",
        "value": true
      }
    ],
    "DocumentContext": {
      "Id": "Tenants-1",
      "Name": "ExampleTenant"
    }
  },
  "Comments": "string",
  "Details": "string",
  "Id": "string",
  "IdentityEstablishedWith": "Session cookie",
  "IpAddress": "127.0.0.1",
  "IsService": false,
  "LastModifiedBy": "string",
  "LastModifiedOn": "2020-01-01T00:00:00.000Z",
  "Links": {
    "Self": "/api/..."
  },
  "Message": "Tenant ExampleTenant was modified",
  "MessageHtml": "Tenant ExampleTenant was modified",
  "MessageReferences": [
    {
      "Length": 0,
      "ReferencedDocumentId": "string",
      "StartIndex": 0
    }
  ],
  "Occurred": "2020-01-01T00:00:00.000Z",
  "RelatedDocumentIds": [
    "Tenants-1"
  ],
  "SpaceId": "Spaces-1",
  "UserAgent": "OctopusClient-js/2026.3.15581",
  "UserId": "Users-1",
  "Username": "MyUserName"
}