activity resource type

Namespace: microsoft.graph

Represents a single activity within an app - for example, a TV show, a document, or a current campaign in a video game. When a user engages with that activity, the engagement is captured as a history item that indicates the start and end time for that activity. As the user re-engages with that activity over time, multiple history items are recorded for a single user activity.

You can use activities in Microsoft Graph to enable users to get back to what they were doing in their app, across multiple devices. Activities that your app creates appear on all users' devices, and are exposed to users as deep links to specific content within your app. You can express specific content within your app as a destination that is showcased in Windows, and accessible on iOS and Android devices through Cortana notifications.

Because every app is different, it's up to you to understand the best way to map actions within your application to user activities that will appear in Cortana and Timeline. For example, games might create an activity for each campaign, document authoring apps might create an activity for each unique document, and line-of-business apps might create an activity for each workflow.

Your user activities will be showcased in Cortana and Windows Timeline user experiences, which are focused on increasing users' productivity and efficiency by helping them get back to content they worked on in the past.


Method Return Type Description
Create or replace activity activity Creates or replaces an existing activity (upsert). The appActivityId needs to be URL-safe (all characters except for RFC 2396 unreserved characters must be converted to their hexadecimal representation), but the original appActivityId does not have to be URL-safe.
Delete an activity No Content Deletes the specified activity for that user from your app.
Get activities Collection of activities Gets the activities for your app for a given user.
Get recent activities Collection of activities Gets the most recent activities for your app for a given user, sorted and based on the most recently created or updated historyItems.


Name Type Description
activationUrl String Required. URL used to launch the activity in the best native experience represented by the appId. Might launch a web-based app if no native app exists.
activitySourceHost String Required. URL for the domain representing the cross-platform identity mapping for the app. Mapping is stored either as a JSON file hosted on the domain or configurable via Windows Dev Center. The JSON file is named cross-platform-app-identifiers and is hosted at root of your HTTPS domain, either at the top level domain or include a sub domain. For example: or but NOT You must have a unique file and domain (or sub domain) per cross-platform app identity. For example, a separate file and domain is needed for Word vs. PowerPoint.
appActivityId String Required. The unique activity ID in the context of the app - supplied by caller and immutable thereafter.
appDisplayName String Optional. Short text description of the app used to generate the activity for use in cases when the app is not installed on the user’s local device.
contentInfo Untyped JSON object Optional. A custom piece of data - JSON-LD extensible description of content according to syntax.
contentUrl String Optional. Used in the event the content can be rendered outside of a native or web-based app experience (for example, a pointer to an item in an RSS feed).
createdDateTime DateTimeOffset Set by the server. DateTime in UTC when the object was created on the server.
expirationDateTime DateTimeOffset Set by the server. DateTime in UTC when the object expired on the server.
fallbackUrl String Optional. URL used to launch the activity in a web-based app, if available.
id String Server-generated ID used for URL addressing.
lastModifiedDateTime DateTimeOffset Set by the server. DateTime in UTC when the object was modified on the server.
status status Set by the server. A status code used to identify valid objects. Values: active, updated, deleted, ignored.
userTimezone String Optional. The timezone in which the user's device used to generate the activity was located at activity creation time; values supplied as Olson IDs in order to support cross-platform representation.
visualElements visualInfo Required. The object containing information to render the activity in the UX.


Relationship Type Description
historyItems activityHistoryItem collection Optional. NavigationProperty/Containment; navigation property to the activity's historyItems.

JSON representation

The following JSON representation shows the resource type.

    "appActivityId": "String",
    "activitySourceHost": "String (host name/domain/URL)",
    "userTimezone": "String",
    "appDisplayName": "String",
    "activationUrl": "String (URL)",
    "contentUrl": "String (URL)",
    "fallbackUrl": "String (URL)",
    "createdDateTime": "DateTimeOffset",
    "lastModifiedDateTime": "DateTimeOffset",
    "expirationDateTime": "DateTimeOffset",
    "id": "String",
    "status": "active | updated | deleted | ignored",
    "contentInfo": { "@odata.type": "microsoft.graph.Json" },
    "visualElements": { "@odata.type": "microsoft.graph.visualInfo" },
    "historyItems": [{ "@odata.type": "microsoft.graph.activityHistoryItem" }]