> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt)

# Search Login Records

API documentation for the FusionAuth Search Login Records API.

# Search Login Records

version

Available Since Version 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

### Using GET parameters

[!Global API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#global-api-key-authentication)

Searches for Login Records given search criteria

GET/api/system/login-record/search?applicationId={applicationId}&start={start}&end={end}&userId={userId}

When calling the API using a `GET` request you will send the search criteria on the URL using request 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 request parameters to the URL.

#### Request Parameters

`applicationId`UUIDoptional

The unique Id of the Application used to narrow the search results to logins for a particular application.

`end`Longoptional

The end [instant](https://fusionauth.io/docs/reference/data-types.md#instants) of the date/time range to search within.

`numberOfResults`IntegeroptionalDefaults to 25

The number of results to return from the search.

`retrieveTotal`BooleanoptionalDefaults to false

Set 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.

`start`Longoptional

The start [instant](https://fusionauth.io/docs/reference/data-types.md#instants) of the date/time range to search within.

`startRow`IntegeroptionalDefaults to 0

The offset into the total results. In order to paginate the results, increment this value by the **numberOfResults** for subsequent requests.

`userId`Stringoptional

The unique Id of the User used to narrow the search results to login records for a particular user.

### Using a request body

[!Global API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#global-api-key-authentication)

Searches for Login Records given search criteria

POST/api/system/login-record/search

OpenAPI Spec

When calling the API using a `POST` request you will send the search criteria in a JSON request body.

#### Request Body

`retrieveTotal`BooleanoptionalDefaults to false

Set 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`UUIDoptional

The unique Id of the Application used to narrow the search results to logins for a particular application.

`search.end`Longoptional

The end [instant](https://fusionauth.io/docs/reference/data-types.md#instants) of the date/time range to search within.

`search.numberOfResults`IntegeroptionalDefaults to 25

The number of results to return from the search.

`search.start`Longoptional

The start [instant](https://fusionauth.io/docs/reference/data-types.md#instants) of the date/time range to search within.

`search.startRow`IntegeroptionalDefaults to 0

The offset into the total results. In order to paginate the results, increment this value by the **numberOfResults** for subsequent requests.

`search.userId`UUIDoptional

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](https://fusionauth.io/docs/apis/errors.md) 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](https://fusionauth.io/docs/apis/authentication.md). |
| 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

`logins`Array

The list of Login Records returned by the search.

`logins[x].applicationId`UUID

The unique Id of the application.

`logins[x].applicationName`String

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`String

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`StringAvailable since 1.59.0

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`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) when the login occurred.

`logins[x].ipAddress`String

The recorded IP address for this login record.

`logins[x].userId`UUID

The unique Id of the user.

`total`Long

The total number of login records available. This will only be provided in the response when **retrieveTotal** was set to `true` on the request.

*Example JSON Response*

```json
{
  "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
}
```