User activities


User activities

The User Activities API tracks and aggregates user-activity information on user sign on attempts, password reset attempts, and total active user counts. The service uses stream processors that listen to the users, login_attempts, and password_resets events. These events are collected and presented by time period. The service supports a query filtering parameter to request user-activity information for a specific date range and sample size.

Filtering data

For large collections, filtering expressions can be added to the request URL to limit the response data by date. For example, this SCIM filter returns user activity data from the start date of “2019-01-01” and an end date of “2019-02-31”:

https://api.pingone.com/v1/environments/{environmentid}/userActivities?filter=startDate gt "2019-01-01T00:00:00Z" AND EndDate lt "2019-02-31T23:59:00Z"

These SCIM parameters are applicable:

  • startDate

    A date-time String for the starting date of the data to include (ISO 8601 format). An endDate value must be specified.

  • endDate

    A date-time String for the ending date of the data to include (ISO 8601 format). A startDate value must be specified.

  • sampleSize

    Determines how the data is sized when returned. This can be HOUR, DAY, WEEK. The default value is determined based on the date range used. If the date range is less than or equal to 5 days, HOUR is used. If the date range is greater than 5 or less than or equal to 60, DAY is used. If the date range is greater than 60, WEEK is used. The following operators are supported in the filter expression:\n" +

These SCIM operators are supported in the filtering expression:

  • eq (equals)

    The attribute and operator values must be identical.

  • gt (greater than)

    This is a chronological comparison.

  • lt (less than)

    This is a chronological comparison.

  • ge (greater than or equal to)

    This is a chronological comparison.

  • le (less than or equal to)

    This is a chronological comparison.

  • in (includes)

    Matches one or more values.

  • sw (starts with)

    The entire operator value must be a substring of the attribute value, starting at the beginning of the attribute value.

  • ew (ends with)

    The entire operator value must be a substring of the attribute value, matching at the end of the attribute value.

  • co (contains)

    The entire operator value must be a substring of the attribute value for a match.

  • pr (present)

    The attribute has a non-empty or non-null value.\n" +

  • and (logical AND)

    Logical AND for building compound expressions in which both expressions are true.

  • or (logical OR)

    Logical OR for building compound expressions if either expression is true.

  • not (logical NOT)

    Logical NOT for building compound expressions if the expression evaluates to false.

For more information about SCIM syntax and operators, see [https://apidocs.pingidentity.com/pingone/customer/v1/api/ref/p1_conventions/).

User activities API operations

The user activities endpoints support the following operations:

For hands-on experience with the user activities API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

User activities data model

Property Description
startDate The start date for the activity period.
endDate The end date for the activity period.
environment.id A string that specifies the environment resource’s unique identifier.
totalActiveUsers An integer that specifies the total number of active users for the activity period.
userSignOns.successes An integer that specifies the total number of successful user sign ons for the activity period.
userSignOns.failures An integer that specifies the total number of failed user sign ons for the activity period.
passwordResets An integer that specifies the total number of password resets for the activity period.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request could not be completed.
401 You do not have access to this resource.
404 The requested resource was not found.

Endpoint examples

Get user activities

You can get all user-activity events for a selected environment. If a startDate and endDate filtering parameter is not specified, the request returns all user activity information for the past 30 days. If a sampleSize filtering parameter is not specified, the default sample size value is DAY.

The GET /environments/{environmentId}/userActivities operation returns all user-activity events for the specified environment.

curl -X "GET" "https://api.pingone.com/v1/environments/{environmentId}/userActivities" \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/userActivities"
        }
    },
    "_embedded": {
        "userActivities": [
            {
                "startDate": "2018-09-15T00:00:00Z",
                "endDate": "2018-09-16T00:00:00Z",
                "totalActiveUsers": 0,
                "userSignOns": {
                    "successes": 0,
                    "failures": 0
                },
                "passwordResets": 0
            },
            {
                "startDate": "2018-09-16T00:00:00Z",
                "endDate": "2018-09-17T00:00:00Z",
                "totalActiveUsers": 0,
                "userSignOns": {
                    "successes": 0,
                    "failures": 0
                },
                "passwordResets": 0
            },
            {
                "startDate": "2018-09-17T00:00:00Z",
                "endDate": "2018-09-18T00:00:00Z",
                "totalActiveUsers": 0,
                "userSignOns": {
                    "successes": 0,
                    "failures": 0
                },
                "passwordResets": 0
            },
            {
                "startDate": "2018-09-18T00:00:00Z",
                "endDate": "2018-09-19T00:00:00Z",
                "totalActiveUsers": 0,
                "userSignOns": {
                    "successes": 0,
                    "failures": 0
                },
                "passwordResets": 0
            },
            {
                "startDate": "2018-09-19T00:00:00Z",
                "endDate": "2018-09-20T00:00:00Z",
                "totalActiveUsers": 0,
                "userSignOns": {
                    "successes": 0,
                    "failures": 0
                },
                "passwordResets": 0
            },
            {
                "startDate": "2018-09-20T00:00:00Z",
                "endDate": "2018-09-21T00:00:00Z",
                "totalActiveUsers": 0,
                "userSignOns": {
                    "successes": 0,
                    "failures": 0
                },
                "passwordResets": 0
            },
            {
                "startDate": "2018-09-21T00:00:00Z",
                "endDate": "2018-09-22T00:00:00Z",
                "totalActiveUsers": 0,
                "userSignOns": {
                    "successes": 0,
                    "failures": 0
                },
                "passwordResets": 0
            },
            {
                "startDate": "2018-09-22T00:00:00Z",
                "endDate": "2018-09-23T00:00:00Z",
                "totalActiveUsers": 0,
                "userSignOns": {
                    "successes": 0,
                    "failures": 0
                },
                "passwordResets": 0
            },
            {
                "startDate": "2018-09-23T00:00:00Z",
                "endDate": "2018-09-24T00:00:00Z",
                "totalActiveUsers": 0,
                "userSignOns": {
                    "successes": 0,
                    "failures": 0
                },
                "passwordResets": 0
            },
            {
                "startDate": "2018-09-24T00:00:00Z",
                "endDate": "2018-09-25T00:00:00Z",
                "totalActiveUsers": 0,
                "userSignOns": {
                    "successes": 0,
                    "failures": 0
                },
                "passwordResets": 0
            },
            {
                "startDate": "2018-09-25T00:00:00Z",
                "endDate": "2018-09-26T00:00:00Z",
                "totalActiveUsers": 0,
                "userSignOns": {
                    "successes": 0,
                    "failures": 0
                },
                "passwordResets": 0
            },
            {
                "startDate": "2018-09-26T00:00:00Z",
                "endDate": "2018-09-27T00:00:00Z",
                "totalActiveUsers": 0,
                "userSignOns": {
                    "successes": 0,
                    "failures": 0
                },
                "passwordResets": 0
            },
            {
                "startDate": "2018-09-27T00:00:00Z",
                "endDate": "2018-09-28T00:00:00Z",
                "totalActiveUsers": 0,
                "userSignOns": {
                    "successes": 0,
                    "failures": 0
                },
                "passwordResets": 0
            },
            {
                "startDate": "2018-09-28T00:00:00Z",
                "endDate": "2018-09-29T00:00:00Z",
                "totalActiveUsers": 0,
                "userSignOns": {
                    "successes": 0,
                    "failures": 0
                },
                "passwordResets": 0
            },
            {
                "startDate": "2018-09-29T00:00:00Z",
                "endDate": "2018-09-30T00:00:00Z",
                "totalActiveUsers": 0,
                "userSignOns": {
                    "successes": 0,
                    "failures": 0
                },
                "passwordResets": 0
            }
        ]
    }
}

To fine-tune the result data, you can specify a SCIM filtering expression to designate specific date ranges and sample sizes. In the following sample, the SCIM filter (URL-encoded) returns data showing the user-activities that occurred from a startDate of 2/17/2018, an endDate of 2/23/2018.

The GET environments/{environmentId}/userActivities?{filter} operation returns the user activities for the time period starting on 2/17/2018 ending on 2/23/2018.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/userActivities?filter=startDate%20eq%20%222018-02-17T09:10:12-04:00%22%20and%20endDate%20eq%20%222018-02-23T09:10:12-04:00%22" \
-H "Authorization: Bearer jwtToken"

If your startDate and endDate filter values are less than or equal to five days, then the result data defaults to a sampleSize value of HOURS.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/userActivities?filter=startDate%20eq%20%222018-02-17T09:10:12-04:00%22%20and%20endDate%20eq%20%222018-02-23T09:10:12-04:00%22" \
-H "Authorization: Bearer jwtToken"

The response data shows the collected user-activities event list for each hour interval.

{

                "startDate": "2018-02-18T10:00:00-04:00",
                "endDate": "2018-02-18T11:00:00-04:00",
                "totalActiveUsers": 0,
                "userSignOns": {
                    "successes": 4978,
                    "failures": 0
                },
                "passwordResets": 0
            },
            {
                "startDate": "2018-02-18T11:00:00-04:00",
                "endDate": "2018-02-18T12:00:00-04:00",
                "totalActiveUsers": 0,
                "userSignOns": {
                    "successes": 4969,
                    "failures": 0
                },
                "passwordResets": 0
            }