Search Login Records API
On this page
1.7.0
This API allows you to search and paginate through the Login Records. Login Records are created in the following scenarios:
- A login is completed using any Login API (normal, one-time, passwordless, Identity Provider, Connector).
- A User is created with a password, whether self service or using the Registration API.
- A Refresh Token is exchanged for a JWT.
- A 2FA login is completed.
You can limit the number of Login Records retained by navigating to Settings -> System -> Advanced -> Login record settings and configuring automatic deletion of Login Records after a certain number of days.
Request#
When calling the API using a GET request you will send the search criteria on the URL using query parameters. In order to simplify the example URL above, not every possible parameter is shown, however using the provided pattern you may add any of the documented query parameters to the URL.
Use a POST request to instead send the search criteria in a JSON request body.
OpenAPI Spec
Query Parameters#
applicationIdThe unique Id of the Application used to narrow the search results to logins for a particular application.
endThe end instant of the date/time range to search within.
numberOfResultsThe number of results to return from the search.
retrieveTotalSet this to true if you want the total possible results returned in the response. With a very large number of login records settings this value to true will increase the response time of this request.
startThe start instant of the date/time range to search within.
startRowThe offset into the total results. In order to paginate the results, increment this value by the numberOfResults for subsequent requests.
userIdThe unique Id of the User used to narrow the search results to login records for a particular user.
Request Body#
retrieveTotalSet this to true if you want the total possible results returned in the response. With a very large number of login records settings this value to true will increase the response time of this request.
search.applicationId The unique Id of the Application used to narrow the search results to logins for a particular application.
search.end The end instant of the date/time range to search within.
search.numberOfResults The number of results to return from the search.
search.start The start instant of the date/time range to search within.
search.startRow The offset into the total results. In order to paginate the results, increment this value by the numberOfResults for subsequent requests.
search.userId The unique Id of the User used to narrow the search results to login records for a particular user.
Response#
The response for this API will contain all login records matching the search criteria in paginated format.
Response Codes| Code | Description |
|---|---|
| 200 | The request was successful. The response will contain a JSON body. |
| 400 | The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
| 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
| 404 | The object you requested doesn't exist. The response will be empty. |
| 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |
| 503 | The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. |
Response Body#
loginsThe list of Login Records returned by the search.
logins[x].applicationId The unique Id of the application.
logins[x].applicationName The name of the application. Because the application name may be modified after the login event occurred, only the applicationId should be considered immutable for historical purposes when identifying the application.
logins[x].loginId The identity used to log in. Because an identity may be modified after the login event occurred, only the userId should be considered immutable for historical purposes when identifying the user.
In version 1.59.0 and later, the loginId is stored in the login record when the correct value can be identified. In these cases the loginIdType will be populated.
logins[x].loginIdType The type of identity used to log in. A missing value on the response indicates the login was not associated with a specific identity, or the login record was created prior to version 1.59.0.
logins[x].instant The instant when the login occurred.
logins[x].ipAddress The recorded IP address for this login record.
logins[x].userId The unique Id of the user.
totalThe total number of login records available. This will only be provided in the response when retrieveTotal was set to true on the request.
{
"logins": [
{
"applicationId": "2edd54c6-695d-409e-b8af-2d3ebf73711a",
"applicationName": "Pied Piper Admin Portal",
"loginId": "richard@piedpiper.com",
"instant": 1562608320303,
"ipAddress": "42.42.42.42",
"userId": "d7be5e1e-0020-4f6f-a9dc-0f9230650042"
},
{
"applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
"applicationName": "FusionAuth",
"loginId": "monica@piedpiper.com",
"loginIdType": "email",
"instant": 1562608320901,
"ipAddress": "192.168.1.1",
"userId": "af8fb4d8-df6b-41c6-9843-813da943b005"
},
{
"applicationId": "2edd54c6-695d-409e-b8af-2d3ebf73711a",
"applicationName": "Pied Piper Admin Portal",
"loginId": "richard@piedpiper.com",
"instant": 1562608399639,
"ipAddress": "42.42.42.42",
"userId": "d7be5e1e-0020-4f6f-a9dc-0f9230650042"
}
],
"total": 3
}Related
API documentation for the FusionAuth Login API.
API documentation for the FusionAuth Authenticate a User API.
API documentation for the FusionAuth Authenticate a User with a One Time Password API.
API documentation for the FusionAuth Complete Multi-Factor Authentication API.