Events endpoints

Use the events endpoints to retrieve activity service events.

GET /v1/events

Fetch information about events the activity service tracks. Web session authentication is required.

Request format

When Forming activity service API requests to this endpoint, the request is a basic call with authentication and one or more query parameters, such as:
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):4433/activity-api/v1/events?service_id=classifier"

curl --header "$auth_header" "$uri"
The following parameters are supported. You must append the service_id parameter. Other parameters are optional or conditionally required.
Parameter Value
service_id Required. The ID of the service you want to query.
subject_type Limit the activity query to a specific subject type (which is the actor of the activity). Use subject_id to further limit the query to specific IDs within the specified type. For example, you can query all user activities or specific users' activities.
subject_id A comma-separated list of IDs associated with the defined subject type. Optional, but, if supplied, then subject_type is required.
object_type Limit the activity query to a specific object type (which is the target of activities). Use object_id to further limit the query to specific IDs within the specified type.
object_id A comma-separated list of IDs associated with the defined object type. Optional, but, if supplied, then object_type is required.
offset Specify a zero-indexed integer to retrieve activity records starting from the offset point. If omitted, the default is 0. This parameter is useful for omitting initial, irrelevant results, such as test data.
order Specify, as a string, whether records are returned in ascending (asc) or descending (desc) order. If omitted, the default is desc. Sorting is based on the activity record's submission time.
limit Specify a positive integer to limit the number of user records returned. If omitted, the default is 1000 events.
after_service_commit_time Specify a timestamp in ISO-8601 format if you want to fetch results after a specific service commit time. Optional.
Tip: For more nuanced queries and additional query parameters, use the GET /v2/events endpoint.

Response format

The response contains a series of JSON objects representing event records. The response also reports the total-rows, which represents the total number of records matching the supplied query.

For example, this response was based on a request that queried the classifier service (service_id=classifier), and events performed by a specific user (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
}
As another example, this response was based on a request that queried the classifier service (service_id=classifier), and events that targeted a specific node group (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

Fetch information about events the activity service tracks in a flat CSV format. Token-based authentication is required.

Request format

When Forming activity service API requests to this endpoint, the request is a basic call with authentication and one or more query parameters, such as:
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):4433/activity-api/v1/events.csv?service_id=classifier&limit=50"

curl --header "$auth_header" "$uri"
The following parameters are supported. You must append the service_id parameter. Other parameters are optional or conditionally required.
Parameter Definition
service_id Required. The ID of the service you want to query.
subject_type Limit the activity query to a specific subject type (which is the actor of the activity). Use subject_id to further limit the query to specific IDs within the specified type. For example, you can query all user activities or specific users' activities.
subject_id A comma-separated list of IDs associated with the defined subject type. Optional, but, if supplied, then subject_type is required.
object_type Limit the activity query to a specific object type (which is the target of activities). Use object_id to further limit the query to specific IDs within the specified type.
object_id A comma-separated list of IDs associated with the defined object type. Optional, but, if supplied, then object_type is required.
offset Specify a zero-indexed integer to retrieve activity records starting from the offset point. If omitted, the default is 0. This parameter is useful for omitting initial, irrelevant results, such as test data.
order Specify, as a string, whether records are returned in ascending (asc) or descending (desc) order. If omitted, the default is desc. Sorting is based on the activity record's submission time.
limit Specify a positive integer to limit the number of user records returned. If omitted, the default is 1000 events.
Tip: For more nuanced queries and additional query parameters, use the GET /v2/events.csv endpoint.

Response format

The response contains all returned records in a flat CSV format. For example:
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 information about events the activity service tracks. Allows filtering through query parameters and supports multiple objects for filtering results. Requires token-based authentication.

Request format

When Forming activity service API requests to the /v2/events endpoint, you can provide multiple optional parameters for filtering results. Parameters are either appended to the URI path or supplied in a JSON body.

You can append the following parameters to the URI path:
Parameter Definition
service_id The ID of the service you want to query. If omitted, all services are queried.
offset Specify a zero-indexed integer to retrieve activity records starting from the offset point. If omitted, the default is 0. This parameter is useful for omitting initial, irrelevant results, such as test data.
order Specify, as a string, whether records are returned in ascending (asc) or descending (desc) order. If omitted, the default is desc. Sorting is based on the activity record's submission time.
limit Specify a positive integer to limit the number of user records returned. If omitted, the default is 1000 events.
You can append additional parameters in the JSON-formatted query array. If you use the query array, you must append all parameters with --data-urlencode, instead of appending them to the URL. Each item in the query array is an object consisting of a single parameter and a value, or a pair of related parameters and values. Some parameters can be repeated to specify multiple values in the same category. For example:
--data-urlencode '{"query": [{"object_id": "3", "object_type":"users"}, \
                                {"subject_type": "node_groups"}, \
                                {"subject_type": "roles"}, \
                                {"start": "2019-11-01T21:32:39Z", "end": "2019-12-01T00:00:00Z"}]}'
Parameters you can use in the query array include:
Parameter Definition
subject_id Required. Limit the query to the subject (a user) with the specified ID. If subject_type is omitted, the type is assumed to be users. Currently, users is the only available subject_type.

Place subject_id and subject_type within the same object, separated by a comma.
subject_type Optional, but if included, you must also include subject_id. Refer to subject_id for more information.
object_type Limit the activity query to a specific object type (which is the target of activities).

Use object_id to further limit the query to a specific ID within the specified type.

Place object_type within an object. If you also specify object_id, place it within the same object, separated by a comma.
object_id An ID associated with a defined object type. If supplied, then object_type is required.

Place object_id and object_type within the same object, separated by a comma.
ip_address Specifies an IP address associated with activities. Supports partial string matching.
start Supply a timestamp in ISO-8601 format. Must be used with end to fetch results within a specific service commit time range.

Place start and end within the same object, separated by a comma.

Tip: Whereas other parameters use or logic, the timestamp parameters use and logic.
end Supply a timestamp in ISO-8601 format. Must be used with start to fetch results within a specific service commit time range.

Place start and end within the same object, separated by a comma.

Tip: Whereas other parameters use or logic, the timestamp parameters use and logic.
For example, the following request returns 10 classifier events performed by two specific users from 01 November 2019 through 01 December 2019:
curl -k -X GET -H "X-Authentication: $(puppet-access show)" \
-G "https://$(puppet config print server):4433/activity-api/v2/events" \
--data-urlencode 'service_id=classifier' \
--data-urlencode 'limit=10' \
--data-urlencode '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"}]}'
Tip: If you supply the JSON-fomatted query array, make sure your request uses -G, --data-urlencode, and other such valid arguments to allow the GET request to convey the JSON content.

Response format

The response contains a series of JSON objects representing event records, as well as pagination information based on the submitted query.

For example, a request to the classifier service (service_id=classifier) about actions performed on a specific node group (query=[{"object_id": "415", "object_type":"node_group"}]) might produce a response similar to:
{
  "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"}
}
Responses containing information about orchestrator events, including Puppet agent runs and task runs, can return these keys:
  • start_timestamp: A timestamp in ISO-8601 format reporting the job start time.
  • finish_timestamp: A timestamp in ISO-8601 format reporting the job end time.
  • duration: The job's elapsed run time, in seconds.
  • state: One of new, ready, running, stopping, stopped, finished, or failed.
Failed and in-progress jobs do not return the finish_timestamp or duration keys.
For example, this partial response contains information about one commit for a Puppet run:
{
  "objects": [
    {
      "id": "example.delivery.puppetlabs.net",
      "name": "example.delivery.puppetlabs.net",
      "type": "node"
    }
  ],
  "subject": {
    "id": "11bf351c-f1ec-11af-11ad-e111fec1a1bd",
    "name": "admin"
  },
  "timestamp": "2022-08-08T23:18:52Z",
  "ip_address": "<IP_ADDRESS>",
  "events": [
    {
      "description": "request_puppet_agent_on_node",
      "finish_timestamp": "2022-08-08T23:18:52Z",
      "start_timestamp": "2022-08-08T23:18:47Z",
      "name": "puppet agent",
      "type": "puppet_agent",
      "duration": 4.898,
      "state": "finished",
      "what": "node",
      "message": "Request \"puppet agent\" run on \"example.delivery.puppetlabs.net\" over \"pcp\" via orchestrator job \"11\""
    }
  ]
},
This partial response example contains information about one commit for a task run:
{
  "objects": [
    {
      "id": "example.delivery.puppetlabs.net",
      "name": "example.delivery.puppetlabs.net",
      "type": "node"
    }
  ],
  "subject": {
    "id": "11bf351c-f1ec-11af-11ad-e111fec1a1bd",
    "name": "admin"
  },
  "timestamp": "2022-08-08T23:19:01Z",
  "ip_address": "<IP_ADDRESS>",
  "events": [
    {
      "description": "request_facter_on_node",
      "finish_timestamp": "2022-08-08T23:19:00Z",
      "start_timestamp": "2022-08-08T23:18:58Z",
      "name": "req_facter",
      "type": "run_task",
      "duration": 2.324,
      "state": "finished",
      "what": "node",
      "message": "Request \"req_facter\" task on \"example.delivery.puppetlabs.net\" over \"pcp\" via orchestrator job \"12\""
    }
  ]
},

GET /v2/events.csv

Fetch information about events the activity service tracks in a flat CSV format. Allows filtering through query parameters and supports multiple objects for filtering results. Token-based authentication is required.

Request format

Requests to the /v2/events.csv endpoint are formed in the same way as the GET /v2/events endpoint, except that the URI path contains events.csv instead of events. For example:
curl -k -X GET -H "X-Authentication: $(puppet-access show)" \
-G "https://$(puppet config print server):4433/activity-api/v2/events.csv" \
--data-urlencode 'service_id=classifier' \
--data-urlencode 'query=[{"object_id": "3","object_type": "users"}, \
{"start": "2019-11-01T21:32:39Z", "end": "2019-12-01T00:00:00Z"}]}'

Response format

The response contains all returned records in a flat CSV format. For example:
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