--- id: activity-stream-query slug: /apis/activity-stream/query title: 'Query Activity' description: 'Retrieve the activity feed for an asset, with a field-by-field walkthrough of the response.' sidebar_label: 'Query Activity' sidebar_position: 2 tags: ['api', 'activity-stream', 'query'] --- Retrieve the activities recorded against an asset. ## Request ```text GET ~/api/ActivityStream/:streamName ``` Where `:streamName` is an [Oid token](/apis/conventions/terminology#oid) such as `Story:1220`, or a workitem number such as `S-01047`. See [stream names](/apis/activity-stream#endpoint). ```bash title="Request" curl "https://{host}/{instance}/api/ActivityStream/Story:1220?maxCount=25&direction=Back" \ -H "Authorization: Bearer " \ -H "Accept: application/json" ``` See [query parameters](/apis/activity-stream#query-parameters) for `anchorDate`, `direction`, `maxCount` and `verbs`. ## Response A JSON **array**. Each element wraps a `body` object describing one activity. ```json title="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](/apis/activity-stream#verbs). | | `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](/apis/conventions/terminology#asset-state) 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](/apis/activity-stream#paging-through-a-stream), or [`/count`](/apis/activity-stream#counting-a-stream) if you need the total. - An asset with no recorded activity returns `[]`. An unresolvable stream name returns `404`. ## Related Topics - [Activity stream overview](/apis/activity-stream) — parameters, verbs and caveats - [rest-1.v1](/apis/rest-1) — asset history, for a complete change record - [Webhooks](/apis/webhooks) — get pushed the change instead of polling