Azure Active Directory sign-in activity report API reference

Tip

Check out the new Microsoft Graph API for reporting, which will eventually replace this API.

This article is part of a collection of articles about the Azure Active Directory (Azure AD) reporting API. Azure AD reporting provides you with an API that enables you to access audit data using code or related tools. The scope of this article is to provide you with reference information about the audit API.

See:

Who can access the API data?

  • Users and Service Principals in the Security Admin or Security Reader role
  • Global Admins
  • Any app that has authorization to access the API (app authorization can be set up only based on Global Admin’s permission)

To configure access for an application to access security APIs such as sign-in events, use the following PowerShell to add the applications Service Principal into the Security Reader role

Connect-MsolService
$servicePrincipal = Get-MsolServicePrincipal -AppPrincipalId "<app client id>"
$role = Get-MsolRole | ? Name -eq "Security Reader"
Add-MsolRoleMember -RoleObjectId $role.ObjectId -RoleMemberType ServicePrincipal -RoleMemberObjectId $servicePrincipal.ObjectId

Prerequisites

To access this report through the reporting API, you must have:

Accessing the API

You can either access this API through the Graph Explorer or programmatically using, for example, PowerShell. Use the backtick (aka: grave accent) character to “escape” the $ character to ensure that PowerShell can interpret the OData filter syntax used in AAD Graph REST calls. The backtick character serves as PowerShell’s escape character, allowing PowerShell to do a literal interpretation of the $ character, and avoid confusing it as a PowerShell variable name (for example, $filter).

The focus of this topic is on the Graph Explorer. For a PowerShell example, see this PowerShell script.

API Endpoint

You can access this API using the following base URI:

https://graph.windows.net/contoso.com/activities/signinEvents?api-version=beta  

Due to the volume of data, this API has a limit of 1,000,000 returned records.

This call returns the data in batches. Each batch has a maximum of 1000 records. To get the next batch of records, use the Next link. Get the skiptoken information from the first set of returned records. The skip token will be at the end of the result set.

https://graph.windows.net/$tenantdomain/activities/signinEvents?api-version=beta&%24skiptoken=-1339686058

Supported filters

You can narrow down the number of records that are returned by an API call in form of a filter.
For sign-in API-related data, the following filters are supported:

  • $top=<number of records to be returned> - to limit the number of returned records. This is an expensive operation. Don't use this filter if you want to return thousands of objects.
  • $filter=<your filter statement> - to specify, on the basis of supported filter fields, the type of records you care about

Supported filter fields and operators

To specify the type of records you care about, you can build a filter statement that can contain either one or a combination of the following filter fields:

  • signinDateTime - defines a date or date range
  • userId - defines a specific user based the user's ID.
  • userPrincipalName - defines a specific user based the user's user principal name (UPN)
  • appId - defines a specific app based the app's ID
  • appDisplayName - defines a specific app based the app's display name
  • loginStatus - defines the status of the logins (success / failure)

Note

When using Graph Explorer, you the need to use the correct case for each letter is your filter fields.

To narrow down the scope of the returned data, you can build combinations of the supported filters and filter fields. For example, the following statement returns the top 10 records between July 1 2016 and July 6 2016:

https://graph.windows.net/contoso.com/activities/signinEvents?api-version=beta&$top=10&$filter=signinDateTime+ge+2016-07-01T17:05:21Z+and+signinDateTime+le+2016-07-07T00:00:00Z

signinDateTime

Supported operators: eq, ge, le, gt, lt

Example:

Using a specific date

$filter=signinDateTime+eq+2016-04-25T23:59:00Z    

Using a date range

$filter=signinDateTime+ge+2016-07-01T17:05:21Z+and+signinDateTime+le+2016-07-07T17:05:21Z

Notes:

The datetime parameter should be in the UTC format


userId

Supported operators: eq

Example:

$filter=userId+eq+’00000000-0000-0000-0000-000000000000’

Notes:

The value of userId is a string value


userPrincipalName

Supported operators: eq

Example:

$filter=userPrincipalName+eq+'audrey.oliver@wingtiptoysonline.com' 

Notes:

The value of userPrincipalName is a string value


appId

Supported operators: eq

Example:

$filter=appId+eq+’00000000-0000-0000-0000-000000000000’

Notes:

The value of appId is a string value


appDisplayName

Supported operators: eq

Example:

$filter=appDisplayName+eq+'Azure+Portal' 

Notes:

The value of appDisplayName is a string value


loginStatus

Supported operators: eq

Example:

$filter=loginStatus+eq+'1'  

Notes:

There are two options for the loginStatus: 0 - success, 1 - failure


Next steps