Active identity counts


Active identity counts

Active identity counts gather information about identities that have completed one of the following actions successfully during a specified period of time:

  • Authentication

    The identity has completed at least one authentication flow successfully.

  • Password check

    The identity has completed at least one password check successfully.

This service uses authentication and password-evaluation user events to determine whether an identity is active within a specified sampling period.

Filtering result data

The GET request for active identity counts requires a SCIM filter to specify start date and sampling period values. The end date is set automatically to the current date; it cannot be set manually in the request. For example, this SCIM filter returns active identity counts divided into time periods of one hour from the start date of “2019-01-01” for the specified sampling period. The response lists 10 records (periods) per page:

https://api.pingone.com/v1/environments/{environmentId}/activeIdentityCounts?limit=10&filter=startDate ge "2019-01-01T00:00:00Z" AND samplingPeriod eq 1

These SCIM operators can be applied to the following attributes:

  • eq (equals)

    Supported attributes: samplingPeriod

  • ge (greater than or equal to)

    Supported attributes: startDate

  • and (logical AND)

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

For more information about SCIM syntax and operators, see Conventions. For information about paging, ordering, and limiting collections, see Paging, ordering, and filtering collections.

Active identity counts API operations

The active identity counts endpoint supports the following operations:

For hands-on experience with the active identity counts 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.

Active identity counts data model

Property Description
cumulative An integer that represents the cumulative count of unique active identities from the startDate specified in the request to the endDate of the current samplingPeriod.
endDate The date and time active identity count data collection ends (ISO 8601 format).
startDate The date and time active identity count data collection starts (ISO 8601 format).
value An integer that specifies the active identity count for the specified time period.

Response codes

Code Message
200 Successful operation.
400 The request could not be completed.
401 You do not have access to this resource.
403 You do not have permissions or are not licensed to make this request.
404 The requested resource was not found.
500 Internal server error.

Endpoint examples

Get active identity counts

You can get active identity counts for a selected environment over a specified time period. The GET /environments/{environmentId}/activeIdentityCounts request must specify a SCIM filtering expression that designates a start date and a sampling period value in the request URL.

The following sample shows the GET /environments/{environmentId}/activeIdentityCounts?filter=startDate ge "2019-05-01T19:00:00Z" and samplingPeriod eq "10"&limit=10&order=-startDate" operation to return active identity counts for the designated number of sampling periods from the specified start date.

curl -vX GET "https://api.pingone.com/v1/environments/{environmentId}/activeIdentityCounts?filter=startDate%20ge%20%222019-05-01T19:00:00Z%22%20and%20samplingPeriod%20eq%20%2210%22&limit=10&order=-startDate" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
    "_links": {
        "next": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/activeIdentityCounts?cursor=ewogICJzdGFydFBlcmlvZCIgOiAiMjAxOS0wNy0wNFQyMzowMFoiLAogICJlbmRQZXJpb2QiIDogIjIwMTktMDYtMzBUMTk6MDBaIiwKICAiZW5kRGF0ZSIgOiAiMjAxOS0wNy0wOFQxNzoxMDo1OS4xODNaIiwKICAibGFzdEN1bXVsYXRpdmUiIDogMCwKICAiZGVzY2VuZGluZyIgOiB0cnVlLAogICJsaW1pdCIgOiAxMCwKICAic3RhcnREYXRlIiA6ICIyMDE5LTA1LTAxVDE5OjAwWiIsCiAgInNhbXBsaW5nUGVyaW9kIiA6IDEwCn0%3D"
        },
        "self": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/activeIdentityCounts?filter=startDate%20ge%20%222019-05-01T19%3A00%3A00Z%22%20and%20samplingPeriod%20eq%20%2210%22&limit=10&order=-startDate"
        }
    },
    "_embedded": {
        "activeIdentityCounts": [
            {
                "_links": {
                    "activities": {
                        "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/activities?filter=recordedat%20gt%20%222019-07-08T17%3A00%3A00Z%22%20AND%20recordedat%20lt%20%222019-07-08T17%3A10%3A58.183Z%22%20AND%20%28action.type%20eq%20%22SESSION.UPDATED%22%20OR%20action.type%20eq%20%22SESSION.CREATED%22%20OR%20action.type%20eq%20%22PASSWORD.CHECK_SUCCEEDED%22%29"
                    }
                },
                "value": 0,
                "cumulative": 1,
                "startDate": "2019-07-08T17:00:00Z",
                "endDate": "2019-07-08T17:10:58.183Z"
            },
            {
                "_links": {
                    "activities": {
                        "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/activities?filter=recordedat%20gt%20%222019-07-08T07%3A00%3A00Z%22%20AND%20recordedat%20lt%20%222019-07-08T16%3A59%3A59Z%22%20AND%20%28action.type%20eq%20%22SESSION.UPDATED%22%20OR%20action.type%20eq%20%22SESSION.CREATED%22%20OR%20action.type%20eq%20%22PASSWORD.CHECK_SUCCEEDED%22%29"
                    }
                },
                "value": 0,
                "cumulative": 1,
                "startDate": "2019-07-08T07:00:00Z",
                "endDate": "2019-07-08T16:59:59Z"
            },
            {
                "_links": {
                    "activities": {
                        "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/activities?filter=recordedat%20gt%20%222019-07-07T21%3A00%3A00Z%22%20AND%20recordedat%20lt%20%222019-07-08T06%3A59%3A59Z%22%20AND%20%28action.type%20eq%20%22SESSION.UPDATED%22%20OR%20action.type%20eq%20%22SESSION.CREATED%22%20OR%20action.type%20eq%20%22PASSWORD.CHECK_SUCCEEDED%22%29"
                    }
                },
                "value": 0,
                "cumulative": 1,
                "startDate": "2019-07-07T21:00:00Z",
                "endDate": "2019-07-08T06:59:59Z"
            },
            {
                "_links": {
                    "activities": {
                        "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/activities?filter=recordedat%20gt%20%222019-07-07T11%3A00%3A00Z%22%20AND%20recordedat%20lt%20%222019-07-07T20%3A59%3A59Z%22%20AND%20%28action.type%20eq%20%22SESSION.UPDATED%22%20OR%20action.type%20eq%20%22SESSION.CREATED%22%20OR%20action.type%20eq%20%22PASSWORD.CHECK_SUCCEEDED%22%29"
                    }
                },
                "value": 0,
                "cumulative": 1,
                "startDate": "2019-07-07T11:00:00Z",
                "endDate": "2019-07-07T20:59:59Z"
            },
            {
                "_links": {
                    "activities": {
                        "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/activities?filter=recordedat%20gt%20%222019-07-07T01%3A00%3A00Z%22%20AND%20recordedat%20lt%20%222019-07-07T10%3A59%3A59Z%22%20AND%20%28action.type%20eq%20%22SESSION.UPDATED%22%20OR%20action.type%20eq%20%22SESSION.CREATED%22%20OR%20action.type%20eq%20%22PASSWORD.CHECK_SUCCEEDED%22%29"
                    }
                },
                "value": 0,
                "cumulative": 1,
                "startDate": "2019-07-07T01:00:00Z",
                "endDate": "2019-07-07T10:59:59Z"
            },
            {
                "_links": {
                    "activities": {
                        "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/activities?filter=recordedat%20gt%20%222019-07-06T15%3A00%3A00Z%22%20AND%20recordedat%20lt%20%222019-07-07T00%3A59%3A59Z%22%20AND%20%28action.type%20eq%20%22SESSION.UPDATED%22%20OR%20action.type%20eq%20%22SESSION.CREATED%22%20OR%20action.type%20eq%20%22PASSWORD.CHECK_SUCCEEDED%22%29"
                    }
                },
                "value": 0,
                "cumulative": 1,
                "startDate": "2019-07-06T15:00:00Z",
                "endDate": "2019-07-07T00:59:59Z"
            },
            {
                "_links": {
                    "activities": {
                        "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/activities?filter=recordedat%20gt%20%222019-07-06T05%3A00%3A00Z%22%20AND%20recordedat%20lt%20%222019-07-06T14%3A59%3A59Z%22%20AND%20%28action.type%20eq%20%22SESSION.UPDATED%22%20OR%20action.type%20eq%20%22SESSION.CREATED%22%20OR%20action.type%20eq%20%22PASSWORD.CHECK_SUCCEEDED%22%29"
                    }
                },
                "value": 0,
                "cumulative": 1,
                "startDate": "2019-07-06T05:00:00Z",
                "endDate": "2019-07-06T14:59:59Z"
            },
            {
                "_links": {
                    "activities": {
                        "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/activities?filter=recordedat%20gt%20%222019-07-05T19%3A00%3A00Z%22%20AND%20recordedat%20lt%20%222019-07-06T04%3A59%3A59Z%22%20AND%20%28action.type%20eq%20%22SESSION.UPDATED%22%20OR%20action.type%20eq%20%22SESSION.CREATED%22%20OR%20action.type%20eq%20%22PASSWORD.CHECK_SUCCEEDED%22%29"
                    }
                },
                "value": 0,
                "cumulative": 1,
                "startDate": "2019-07-05T19:00:00Z",
                "endDate": "2019-07-06T04:59:59Z"
            },
            {
                "_links": {
                    "activities": {
                        "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/activities?filter=recordedat%20gt%20%222019-07-05T09%3A00%3A00Z%22%20AND%20recordedat%20lt%20%222019-07-05T18%3A59%3A59Z%22%20AND%20%28action.type%20eq%20%22SESSION.UPDATED%22%20OR%20action.type%20eq%20%22SESSION.CREATED%22%20OR%20action.type%20eq%20%22PASSWORD.CHECK_SUCCEEDED%22%29"
                    }
                },
                "value": 1,
                "cumulative": 1,
                "startDate": "2019-07-05T09:00:00Z",
                "endDate": "2019-07-05T18:59:59Z"
            },
            {
                "_links": {
                    "activities": {
                        "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/activities?filter=recordedat%20gt%20%222019-07-04T23%3A00%3A00Z%22%20AND%20recordedat%20lt%20%222019-07-05T08%3A59%3A59Z%22%20AND%20%28action.type%20eq%20%22SESSION.UPDATED%22%20OR%20action.type%20eq%20%22SESSION.CREATED%22%20OR%20action.type%20eq%20%22PASSWORD.CHECK_SUCCEEDED%22%29"
                    }
                },
                "value": 0,
                "cumulative": 1,
                "startDate": "2019-07-04T23:00:00Z",
                "endDate": "2019-07-05T08:59:59Z"
            }
        ]
    },
    "count": 164,
    "size": 10
}

Cached responses

A request to retrieve the count of active identities since the start of the parent organization’s licensing period for a given environment is common practice. This request processes large amounts of data and the response can take up to a minute to produce. For this common use case, the response is pre-calculated and cached to return the data quickly. The following request parameters are required to return a cached response:

  • startDate

    This value must be equal to the beginsAt date of the active license for the specified environment’s parent organization. For more information about licenses, see Licensing.

  • samplingPeriod

    This value must be set to 8760 (the number of hours in a year).

  • limit

    This value is set to 1 to return only the current count of active identities since the start of the parent organization’s licensing period.

  • order

    This value is set to -startDate to return the list in descending order, which shows the current cached count.

The cached value for the environment’s count of active identities since the beginning of the license period is calculated and refreshed once per hour.