GET /v2/events

On this page:

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 RBAC 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. 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. 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"}]}'

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\""
    }
  ]
},

Related information

Event types reported by the activity service