--- title: Reporting description: You can use the reporting capability to generate reports containing user and MFA device details, using a number of device-related filters. component: pingone-api page_id: pingone-api:mfa:users/mfa-reports canonical_url: https://developer.pingidentity.com/pingone-api/mfa/users/mfa-reports.html section_ids: mfa-reports-data-model: MFA reports data model getting-the-report-results: Getting the report results --- # Reporting You can use the reporting capability to generate reports containing user and MFA device details, using a number of device-related filters. For example, you can generate a report listing all email devices or a report containing all of the devices whose phone number starts with a certain country code. You can use synchronous requests to get back the matching data as entries in the JSON response or use asynchronous requests to have the data provided in a CSV or JSON file. Note that when using the synchronous approach, you may have to make multiple requests if there is a large amount of data. The request for generating reports uses the `dataExplorations` endpoint: `{{apiPath}}/v1/environments/{{envID}}/dataExplorations` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | * The data exploration objects created with the `dataExplorations` endpoint are saved only for a short time so you must send a POST request each time you want to generate a report. * You cannot call the `dataExplorations` endpoint more than once per 5 seconds for the same environment. * The database that serves as the source of the reports is updated once every fifteen minutes. So the content of a report may not reflect the exact device data at the time of generation. * When results are returned in files, the generated files are cached for two hours. During this period, if the results are requested again, the cached file is returned, rather than generating the report again. This applies both to the results for an existing `dataExploration` object and the results for any additional `dataExploration` object created with the exact same settings within this period. | ## MFA reports data model | Property | Type | Required? | Mutable? | Description | | ---------------------------- | ------ | --------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `dataExplorationTemplate.id` | String | Required | Immutable | The ID of the report template that should serve as the base for the report. Currently, the only supported value is db632bfd-7054-4bde-b108-a384aac2d513 | | `deliverAs` | String | Optional | Immutable | How the results should be returned. The valid values are ENTRIES (get the results as a collection of entries in the response) and ASYNC\_FILE (get the results in a CSV or JSON file). If the parameter is not included, ENTRIES is used. | | `fields[]` | Array | Optional | Immutable | The fields you want to include in the report. Array of name-value objects, where the name is always `"name"`, for example, `"fields":[{"name":"username"},{"name":"phone"}]`. The values that can be included are: `userId`, `environmentId`, `populationId`, `username`, `givenName`, `familyName`, `mfaEnabled`, `bypassUntil`, `userCreatedAt`, `userUpdatedAt`, `deviceId`, `deviceOrder`, `deviceNickname`, `deviceType`, `deviceStatus`, `deviceIntegrityStateCompromised`, `deviceIntegrityStateReason`, `deviceIntegrityStateTimestamp`, `deviceIntegrityStateAdvice`, `phone`, `extension`, `email`, `deviceBlocked`, `blockedAt`, `deviceLocked`, `lockExpiration`, `fidoBackupEligibility`, `fidoBackupState`, `fidoUserVerification`,`fidoMinPinLength`, `sdkVersion`, `manufacturer`, `deviceName`, `modelName`, `osType`, `osVersion`, `appId`, `appVersion`, `mobileUnitId`, `installedApplicationId`, `rpId`, `deviceCreatedAt`, `deviceUpdatedAt`, `lastDeviceTrxTime`, `serialNumber` Note that if you do not include the `fields` parameter, the report will include all of the fields available. | | `filter` | String | Optional | Immutable | You can filter the results by: `email`, `phone`, `deviceType`, `userId`, or `mfaEnabled`. The filters are used with the operators `eq` and `sw`. `eq` requires an exact match (including case-sensitivity). `sw` ("starts with") provides greater flexibility by matching only part of the string and performing a check that is not case-sensitive. The `sw` option can ony be used with the filters `email` and `phone`. When using the `deviceType` filter, you can use any of the values listed for `type` in the "Device properties" table under [MFA devices](#mfa-devices). Examples: \` "filter": "(deviceType eq "EMAIL")"\[.code]``, `"filter": "(phone sw "+972")"``, \` "filter": "(mfaEnabled eq "true")"\`\
If you do not include the `filter` parameter, the report will include all users and their devices. | | `sync` | String | Optional | Immutable | Set to "true" if you are using the `expand` query parameter. | ## Getting the report results You can receive the report data as entries in the JSON response or as a file (CSV or JSON). There are a number of ways you can get the report results. The recommended approaches for the most common scenarios are as follows: * For cases where you anticipate a fairly small number of records in the results: * Run a POST request using the `expand` query parameter. This will create the `dataExplorations` object and also return the results as entries in the response. `{{apiPath}}/v1/environments/{{envID}}/dataExplorations?expand=entries` For more information on the use of the `expand` query parameter, refer to "Link expansion" under [Conventions](/pingone/main/v1/api/#conventions). * For cases where you expect a large number of records, but would like to receive them as entries in the body of the response: 1. Run a POST request to create the `dataExplorations` object. 2. Run a GET request with `/entries` in the URL: `{{apiPath}}/v1/environments/{{envID}}/dataExplorations/{{dataExplorationID}}/entries` 3. If there are too many results to include in one response, the `_links` section in the response will include a `next` object. Follow the `next` link, then using the same access token, run another GET request using the the `next` link as the URL. 4. Continue until the response no longer includes a `next` object. For more information on pagination, refer to [Paging and ordering collections](/pingone/platform/v1/api/#conventions-paging-ordering-and-filtering-collections). * For cases where you want to receive the results as a file: 1. Run the request to create a report and get the results as a file: `POST {{apiPath}}/v1/environments/{{envID}}/dataExplorations`. In the body of the request, make sure that `deliverAs` is set to ASYNC\_FILE. 2. The response to the report creation request will include a `status` field whose value is `IN_PROGRESS`. 3. Run the polling request `GET {{apiPath}}/v1/environments/{{envID}}/dataExplorations/{{dataExplorationID}}`, using the ID that was returned when you created the report, until the `status` field in the response equals `SUCCESS`. 4. When the response contains the status `SUCCESS`, it will also include a link for downloading a zipped csv file, a link for downloading a zipped JSON file, and a password for opening the zip files. Use this information to download and unzip the report. 5. The report itself is cached for two hours, but the links are good for only five minutes. 6. If more than five minutes has elapsed from the time of the request that returned the links, get updated links by again running the request `GET {{apiPath}}/v1/environments/{{envID}}/dataExplorations/{{dataExplorationID}}` using the ID that was returned when you created the report. 7. If more than two hours has elapsed since the report was created, run the report creation request again.