Query Activity

Retrieve the activities recorded against an asset.

Request

GET ~/api/ActivityStream/:streamName

Where :streamName is an Oid token such as Story:1220, or a workitem number such as S-01047. See stream names.

Request

curl "https://{host}/{instance}/api/ActivityStream/Story:1220?maxCount=25&direction=Back" \
  -H "Authorization: Bearer <access-token>" \
  -H "Accept: application/json"

See query parameters for anchorDate, direction, maxCount and verbs.

Response

A JSON array. Each element wraps a body object describing one activity.

200 OK

[
  {
    "body": {
      "actor": {
        "id": "Member:1065",
        "assetType": "Member",
        "displayName": "Tammy Coder",
        "username": "tammy",
        "email": "tammy.coder@company.com",
        "avatar": "Image:1936"
      },
      "verb": "Updated",
      "object": {
        "id": "Story:1220",
        "assetType": "Story",
        "displayName": "Delete RMA",
        "number": "S-01047",
        "assetState": "Active",
        "scope": "Scope:1258"
      },
      "time": "2014-04-22T14:11:01.1175003Z",
      "summary": "Tammy Coder Updated Story 'Delete RMA'",
      "provider": {
        "stream": "MetaStream",
        "commitSeq": "237",
        "commitId": "01a7b036-01f9-47a1-86b0-17a9c4c25544"
      },
      "target": [
        {
          "name": "Timebox",
          "newValue": {
            "id": "Timebox:1785",
            "assetType": "Timebox",
            "displayName": "Sprint 6",
            "assetState": "Future"
          },
          "oldValue": "",
          "verb": "Set",
          "summary": "Timebox was Set to 'Sprint 6'"
        },
        {
          "name": "Estimate",
          "newValue": "3.00",
          "oldValue": "2.00",
          "verb": "Set",
          "summary": "Estimate was Set to '3.00'"
        },
        {
          "name": "Priority",
          "newValue": "Medium",
          "oldValue": "High",
          "verb": "Set",
          "summary": "Priority was Set to 'Medium'"
        },
        {
          "name": "Risk",
          "newValue": "Low",
          "oldValue": "High",
          "verb": "Set",
          "summary": "Risk was Set to 'Low'"
        }
      ]
    }
  }
]

body

Field	Type	Description
actor	object	The member who performed the action.
verb	string	What was done. See the verb list.
object	object	The asset the action was performed on.
time	string	UTC timestamp, ISO 8601. Use this as the next page's anchorDate.
summary	string	Pre-rendered, localized human-readable sentence.
provider	object	Where the activity came from in the event store.
target	array	The individual changes that made up this activity. May be empty.

actor

Field	Description
id	Oid token of the member, e.g. Member:1065.
assetType	Always Member.
displayName	The member's display name.
username	The member's login name.
email	The member's email address.
avatar	Oid token of the avatar image, e.g. Image:1936 — not a URL.

object

Field	Description
id	Oid token of the affected asset.
assetType	Asset type system name, e.g. Story.
displayName	The asset's name at the time the feed was rendered.
number	The user-visible number, e.g. S-01047. Absent on types without one.
assetState	Asset state as a name (Active), not the numeric code.
scope	Oid token of the owning project.

note

assetState is a name here, a number elsewhere

The activity stream reports "assetState": "Active". The same concept on the asset itself is the numeric AssetState attribute (64). See asset states for the mapping.

provider

Field	Description
stream	The originating event stream, e.g. MetaStream.
commitSeq	Monotonic sequence number of the commit that produced this activity.
commitId	GUID of the commit. Activities sharing a commitId came from one save.

commitId is the reliable way to group changes made together in a single save — more reliable than grouping on time, since several activities can share a timestamp.

target[]

One entry per attribute changed.

Field	Type	Description
name	string	The attribute definition name, e.g. Estimate.
oldValue	string | object	Previous value. Empty string when there was none.
newValue	string | object	New value.
verb	string	The change verb for this specific attribute, e.g. Set.
summary	string	Pre-rendered, localized sentence for this change.

warning

oldValue and newValue are polymorphic

For a scalar attribute they are strings — note that numbers arrive as strings too ("3.00", not 3.00). For a relation they are objects carrying id, assetType, displayName and assetState, as with Timebox in the example above.

Type your client to accept either. A parser that assumes string will break the first time someone reassigns a sprint.

Also note that target[].verb (Set) is a different vocabulary from body.verb (Updated). The body verb describes the activity; the target verb describes what happened to that one attribute.

Notes

• summary fields are localized for the caller. Do not pattern-match on them; parse target[] instead.
• The response is not wrapped in a paging envelope — there is no total. Use anchor-date paging, or /count if you need the total.
• An asset with no recorded activity returns []. An unresolvable stream name returns 404.

Related Topics

• Activity stream overview — parameters, verbs and caveats
• rest-1.v1 — asset history, for a complete change record
• Webhooks — get pushed the change instead of polling