Events endpoints

We've updated our documentation to remove harmful terminology.
Sections

Use the events endpoints to retrieve activity service events.

GET /v1/events

Fetches activity service events. Web session authentication is required.

Request format

The /v1/events endpoint supports filtering through query parameters.
Parameter Value
service_id The ID of the service. Required.
subject_type The subject who performed the activity. Required only when subject_id is provided.
subject_id Comma-separated list of IDs associated with the defined subject type. Optional.
object_type The object affected by the activity. Required only when the object_id is provided.
object_id Comma-separated list of IDs associated with the defined object type. Optional.
offset Number of commits to skip before returning events. Optional.
limit Maximum number of events to return. Default is 1000 events. Optional.
after_service_commit_time Return results after a specific service commit time. ISO 8601. Optional.

Response format

Responses are returned in a structured JSON format.

GET /v1/events?service_id=classifier&subject_type=users&subject_id=kai

{
  "commits": [
    {
      "object": {
        "id": "415dfsvdf-dfgd45dfg-4dsfg54d",
        "name": "Default Node Group"
      },
      "subject": {
        "id": "dfgdfc145-545dfg54f-fdg45s5s",
        "name": "Kai Evans"
      },
      "timestamp": "2014-06-24T04:00:00Z",
      "events": [
        {
          "message": "Create Node"
        },
        {
          "message": "Create Node Class"
        }
      ]
    }
  ],
  "total-rows": 1
}

GET /v1/events?service_id=classifier&object_type=node_groups&object_id=2

{
  "commits": [
    {
      "object": {
        "id": "415dfsvdf-dfgd45dfg-4dsfg54d",
        "name": "Default Node Group"
      },
      "subject": {
        "id": "dfgdfc145-545dfg54f-fdg45s5s",
        "name": "Kai Evans"
      },
      "timestamp": "2014-06-24T04:00:00Z",
      "events": [
        {
          "message": "Create Node"
        },
        {
          "message": "Create Node Class"
        }
      ]
    }
  ],
  "total-rows": 1
}

GET /v1/events.csv

Fetches activity service events and returns in a flat CSV format. Token-based authentication is required.

Request format

The /v1/events.csv endpoint supports accepts the following parameters.
Paramter Definition
service_id The ID of the service. Required.
subject_type The subject who performed the activity. Required only when subject_id is provided.
subject_id Command-separated list of IDs associated with the defined subject type. Optional.
object_type The object affected by the activity. Required only when the object_id is provided.
object_id Comma-separated list of IDs associated with the defined object type. Optional.
offset Number of commits to skip before returning events. Optional.
limit Maximum number of events to return. Default is 10000 events. Optional.

Response format

Responses are returned in a flat CSV format. Example return:

Submit Time,Subject Type,Subject Id,Subject Name,Object Type,Object Id,Object Name,Type,What,Description,Message
YYYY-MM-DD 18:52:27.76,users,6868e4af-2996-46c6-8e42-1ae873f8a0ba,kai.evens,node_groups,b55c209d-e68f-4096-9a2c-5ae52dd2500c,web_servers,delete,node_group,delete_node_group,"Deleted the ""web_servers"" group with id b55c209d-e68f-4096-9a2c-5ae52dd2500c"
YYYY-MM-DD 18:52:02.391,users,6868e4af-2996-46c6-8e42-1ae873f8a0ba,kai.evens,node_groups,b55c209d-e68f-4096-9a2c-5ae52dd2500c,web_servers,create,node_group,create_node_group,"Created the ""web_servers"" group with id b55c209d-e68f-4096-9a2c-5ae52dd2500c"
YYYY-MM-DD 18:52:02.391,users,6868e4af-2996-46c6-8e42-1ae873f8a0ba,kai.evens,node_groups,b55c209d-e68f-4096-9a2c-5ae52dd2500c,web_servers,edit,node_group_description,edit_node_group_description,"Changed the description to """""
YYYY-MM-DD 18:52:02.391,users,6868e4af-2996-46c6-8e42-1ae873f8a0ba,kai.evens,node_groups,b55c209d-e68f-4096-9a2c-5ae52dd2500c,web_servers,edit,node_group_environment,edit_node_group_environment,"Changed the environment to ""production"""
YYYY-MM-DD 18:52:02.391,users,6868e4af-2996-46c6-8e42-1ae873f8a0ba,kai.evens,node_groups,b55c209d-e68f-4096-9a2c-5ae52dd2500c,web_servers,edit,node_group_environment_override,edit_node_group_environment_override,Changed the environment override setting to false
YYYY-MM-DD 18:52:02.391,users,6868e4af-2996-46c6-8e42-1ae873f8a0ba,kai.evens,node_groups,b55c209d-e68f-4096-9a2c-5ae52dd2500c,web_servers,edit,node_group_parent,edit_node_group_parent,Changed the parent to ec519937-8681-43d3-8b74-380d65736dba
YYYY-MM-DD 00:41:18.944,users,6868e4af-2996-46c6-8e42-1ae873f8a0ba,kai.evens,node_groups,ec519937-8681-43d3-8b74-380d65736dba,PE Orchestrator,edit,node_group_class_parameter,delete_node_group_class_parameter_puppet_enterprise::profile::orchestrator_use_application_services,"Removed the ""use_application_services"" parameter from the ""puppet_enterprise::profile::orchestrator"" class"
YYYY-MM-DD 00:41:10.631,users,6868e4af-2996-46c6-8e42-1ae873f8a0ba,kai.evens,node_groups,ec519937-8681-43d3-8b74-380d65736dba,PE Orchestrator,edit,node_group_class_parameter,add_node_group_class_parameter_puppet_enterprise::profile::orchestrator_use_application_services,"Added the ""use_application_services"" parameter to the ""puppet_enterprise::profile::orchestrator"" class"
YYYY-MM-DD 20:41:30.223,users,6868e4af-2996-46c6-8e42-1ae873f8a0ba,kai.evens,node_groups,46e34005-28e4-4009-bc48-4813221e9ffb,PE Agent,schedule_deploy,node_group,schedule_puppet_agent_on_node_group,Schedule puppet agent run on nodes in this group to be run at 2019-01-16T08:00:00Z

GET /v2/events

Fetches events in a structured JSON format. Allows filtering through query parameters and supports multiple objects for filtering results. Requires token based authentication.

Request format

The /v2/events endpoint allows multiple optional objects for filtering results. You can specify as many parameters as you want to filter results. Filtering uses "or" logic, except for the timestamp ranges which use "and" logic.
Parameter Definition
service_id The ID of the service. Optional.
offset Number of commits to skip before returning events. Optional.
limit Maximum number of events to return. Default is 1000 events. Optional.
query A JSON-encoded array of optional objects used to filter the results. You can specify multiple objects of the same or different types with the exception of ip_address. You can only specify one ip_address. Results returned based on this logic: (and (or , , ) (or ))]. Optional.
The query parameter supports one or more of following:
Parameter Definition
subject_id ID associated with the defined subject type. Must be paired with subject_type. Optional.
subject_type The subject who performed the activity. Defaults to users. Required only when subject_id is provided.
object_id ID associated with the defined object type. If used, it must be paired with object_type. Optional.
object_type The object affected by the activity. Optional.
ip_address Specifies the ip address. Partial string match. Optional.
start ISO 8601 timestamp for start time. Uses "and" logic and must be paired with end. Optional.
end ISO 8601 timestamp for end time. Uses "and" logic and must be paired with start. Optional.
For example, this curl request returns all events performed by users 42bf351c-f9ec-40af-84ad-e976fec7f4bd and 95c6159e-dfa3-4f34-b884-45e2ba39d24b from 01 November 2019 through 01 December 2019.
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):4433/activity-api/v2/events?service_id=classifier"
data='query=[{"object_id": "db2caca1-d6a4-4145-8240-9de9b4e654d1","object_type": "users"},
        {"subject_id": "db2caca1-d6a4-4145-8240-9de9b4e654d1"},
        {"object_id": "5d5ab481-7614-4324-bfea-e9eeb0b22ce8", "object_type":"users"},
        {"subject_id": "5d5ab481-7614-4324-bfea-e9eeb0b22ce8"},
        {"start": "2019-11-01T21:32:39Z", "end": "2019-12-01T00:00:00Z"}]'
curl --insecure --header "$auth_header" --request GET "$uri" --data "$data"

See Usage notes for curl examples for information about forming curl commands.

Response format

Responses are returned in a structured JSON format.

For example, the above request produces the following response:
{
  "commits": [
    {
      "objects": [
        {
          "id": "5a359d65-a8e5-41f5-b99d-3f0e6b5d668d",
          "name": "PE Agent",
          "type": "node_groups"
        }
      ],
      "subject": {
        "id": "db2caca1-d6a4-4145-8240-9de9b4e654d1",
        "name": "kai.evans"
      },
      "timestamp": "2019-11-19T16:40:12Z",
      "events": [
        {
          "message": "Added the \"package_inventory_enabled\" parameter to the \"puppet_enterprise::profile::agent\" class",
          "type": "edit",
          "what": "node_group_class_parameter",
          "description": "add_node_group_class_parameter_puppet_enterprise::profile::agent_package_inventory_enabled"
        }
      ]
    },
    {
      "objects": [
        {
          "id": "6977ec72-5be3-4e0e-975e-a8d144b9f7ea",
          "name": "test",
          "type": "node_groups"
        }
      ],
      "subject": {
        "id": "5d5ab481-7614-4324-bfea-e9eeb0b22ce8",
        "name": "jean.jackson"
      },
      "timestamp": "2019-11-18T19:43:51Z",
      "events": [
        {
          "message": "Changed the rule to nil",
          "type": "edit",
          "what": "node_group_rule",
          "description": "edit_node_group_rule"
        }
      ]
    },
    {
      "objects": [
        {
          "id": "6977ec72-5be3-4e0e-975e-a8d144b9f7ea",
          "name": "test",
          "type": "node_groups"
        }
      ],
      "subject": {
        "id": "5d5ab481-7614-4324-bfea-e9eeb0b22ce8",
        "name": "jean.jackson"
      },
      "timestamp": "2019-11-18T19:42:21Z",
      "events": [
        {
          "message": "Added the \"content\" parameter to the \"motd\" class",
          "type": "edit",
          "what": "node_group_class_parameter",
          "description": "add_node_group_class_parameter_motd_content"
        },
        {
          "message": "Changed the rule to [\"and\" [\"~\" [\"fact\" \"os\" \"release\" \"major\"] \"\"]]",
          "type": "edit",
          "what": "node_group_rule",
          "description": "edit_node_group_rule"
        }
      ]
    },
    {
      "objects": [
        {
          "id": "6977ec72-5be3-4e0e-975e-a8d144b9f7ea",
          "name": "test",
          "type": "node_groups"
        }
      ],
      "subject": {
        "id": "5d5ab481-7614-4324-bfea-e9eeb0b22ce8",
        "name": "jean.jackson"
      },
      "timestamp": "2019-11-18T19:41:39Z",
      "events": [
        {
          "message": "Changed the rule to nil",
          "type": "edit",
          "what": "node_group_rule",
          "description": "edit_node_group_rule"
        }
      ]
    },
    {
      "objects": [
        {
          "id": "6977ec72-5be3-4e0e-975e-a8d144b9f7ea",
          "name": "test",
          "type": "node_groups"
        }
      ],
      "subject": {
        "id": "5d5ab481-7614-4324-bfea-e9eeb0b22ce8",
        "name": "jean.jackson"
      },
      "timestamp": "2019-11-18T19:38:39Z",
      "events": [
        {
          "message": "Added the \"motd\" class",
          "type": "edit",
          "what": "node_group_class",
          "description": "add_node_group_class_motd"
        },
        {
          "message": "Changed the rule to [\"and\" [\"~\" [\"trusted\" \"certname\"] \"\"]]",
          "type": "edit",
          "what": "node_group_rule",
          "description": "edit_node_group_rule"
        }
      ]
    },   
    {
      "objects": [
        {
          "id": "5d355a45-cf05-4466-97e4-a1e82a5642b0",
          "name": "Remote Access",
          "type": "node_groups"
        }
      ],
      "subject": {
        "id": "5d5ab481-7614-4324-bfea-e9eeb0b22ce8",
        "name": "jean.jackson"
      },
      "timestamp": "2019-11-01T21:51:03Z",
      "events": [
        {
          "message": "Added the \"profile::client_configs\" class",
          "type": "edit",
          "what": "node_group_class",
          "description": "add_node_group_class_profile::client_configs"
        },
        {
          "message": "Added the \"profile::remote_mgmt\" class",
          "type": "edit",
          "what": "node_group_class",
          "description": "add_node_group_class_profile::remote_mgmt"
        },
        {
          "message": "Added the \"profile::sssd_ldap\" class",
          "type": "edit",
          "what": "node_group_class",
          "description": "add_node_group_class_profile::sssd_ldap"
        },
        {
          "message": "Changed the rule to [\"or\" [\"=\" \"name\" \"pe-next.p9.puppet.net\"]]",
          "type": "edit",
          "what": "node_group_rule",
          "description": "edit_node_group_rule"
        }
      ]
    }
  ],
  "pagination": {
    "total": 9,
    "limit": 1000,
    "offset": 0
  }
}

Other examples

Request:

GET /v2/events?service_id=classifier&query=[{"subject_id": "dfgdfc145-545dfg54f-fdg45s5s", "subject_type": "users"}, {"object_id": "415dfsvdf-dfgd45dfg-4dsfg54d", "object_type": "node_group"}]

Response:

{
  "commits": [
    {
      "objects": [{
        "id": "415dfsvdf-dfgd45dfg-4dsfg54d",
        "name": "Default Node Group"
      }],
      "subject": {
        "id": "dfgdfc145-545dfg54f-fdg45s5s",
        "name": "Kai Evans"
      },
      "timestamp": "2014-06-24T04:00:00Z",
      "events": [
        {
          "message": "Create Node"
        },
        {
          "message": "Create Node Class"
        }
      ]
    }
  ],
  "pagination": {"total": "1", "limit": "1000", "offset: "0"}
}
Request:
GET /v2/events?service_id=classifier&query=[{"object_id": "415dfsvdf-dfgd45dfg-4dsfg54d", "object_type": "node_group"}]
Response:
{
  "commits": [
    {
      "objects": [{
        "id": "415dfsvdf-dfgd45dfg-4dsfg54d",
        "name": "Default Node Group"
      }],
      "subject": {
        "id": "dfgdfc145-545dfg54f-fdg45s5s",
        "name": "Kai Evans"
      },
      "timestamp": "2014-06-24T04:00:00Z",
      "events": [
        {
          "message": "Create Node"
        },
        {
          "message": "Create Node Class"
        }
      ]
    }
  ],
  "pagination": {"total": "1", "limit": "1000", "offset: "0"}
}

GET /v2/events.csv

Fetches events in a flat CSV format. Allows filtering through query parameters and supports multiple objects for filtering results. Requires token based authentication.

Request format

The /v2/events.csv endpoint allows multiple optional objects for filtering results. You can specify as many parameters as you want to filter results. Filtering uses "or" logic, except for the timestamp ranges which use "and" logic.

Parameter Definition
service_id The ID of the service. Optional.
offset Number of commits to skip before returning events. Optional.
limit Maximum number of events to return. Default is 1000 events. Optional.
query A JSON-encoded array of optional objects used to filter the results. Multiple objects of the same or different types can be specified. Results returned based on this logic: (and (or , , ) (or ))]. Optional.
The query parameter supports one or more of following:
Parameter Definition
subject_id ID associated with the defined subject type. Must be paired with subject_type. Optional.
subject_type The subject who performed the activity. Defaults to users. Required only when subject_id is provided.
object_id ID associated with the defined object type. Must be paired with object_type. Optional.
object_type The object affected by the activity. Required only when the object_id is provided.
ip_address Specifies the ip address. Optional.
start ISO 8601 timestamp for start time. Uses "and" logic and must be paired with end. Optional.
end ISO 8601 timestamp for end time. Uses "and" logic and must be paired with start. Optional.

Response format

GET /v2/events.csv?service_id=classifier&query=[{"subject_id": "kai", "subject_type": "users"}]
Submit Time,Subject Type,Subject Id,Subject Name,Object Type,Object Id,Object Name,Type,What,Description,Message,Ip Address
2014-07-17 13:08:09.985221,users,kai,Kai Evans,node\_groups,2,Default Node Group,create,node,create\_node,Create Node,123.123.123.123
2014-07-17 13:08:09.985221,users,kai,Kai Evans,node\_groups,2,Default Node Group,create,node\_class,create\_node\_class,Create Node Class,123.123.123.123
How helpful was this page?

If you leave us your email, we may contact you regarding your feedback. For more information on how Puppet uses your personal information, see our privacy policy.

Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.