Documentation | 2025.1

# Activity : Swarm Activity List

From Swarm 2022.2, Swarm no longer supports APIs older than v9.

## List Activity Entries

### Summary

List Activity Entries

GET /api/v9/activity

### Description

Retrieve the Activity List.

- Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Core Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
- Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

### Parameters

Parameter | Description | Type | Parameter Type | Required | Default Value
--- | --- | --- | --- | --- | ---
change | Optionally filter activity entries by associated Changelist ID. This only includes records for which there is an activity entry in Swarm. | integer | form | No |
stream | Optional activity stream to query for entries. This can include user-initiated actions (`user-alice`), activity relating to a user’s followed projects/users (`personal-alice`), review streams (`review-1234`), and project streams (`project-exampleproject`). | string | form | No |
type | Type of activity, for example, `change`, `comment`, `job`, or `review`. | string | form | No |
after | An activity ID to seek to. Activity entries up to and including the specified ID are excluded from the results and do not count towards `max`. Useful for pagination. Commonly set to the `lastSeen` property from a previous query. | integer | query | No |
max | Maximum number of activity entries to return. This does not guarantee that `max` entries are returned. It does guarantee that the number of entries returned won’t exceed `max`. Server-side filtering may exclude some activity entries for permissions reasons. | integer | query | No | 100
fields | An optional comma-separated list (or array) of fields to show. Omitting this parameter or passing an empty value shows all fields. | string | query | No |

### Example response

#### Successful Response:

To get the latest activity entry on a review:

    curl -u "username:password" http://myswarm.url/api/v9/activity?stream=review-290&max=1

Swarm responds with an array of activity entities, and a `lastSeen` value that can be used for pagination:

    HTTP/1.1 200 OK

    {
      "activity": [
        {
          "id": 619,
          "action": "updated files in",
          "behalfOf": null,
          "behalfOfExists": false,
          "behalfOfFullName": "",
          "change": 290,
          "comments": [
            0,
            0
          ],
          "date": "2019-01-23T02:46:59-08:00",
          "depotFile": null,
          "description": "Start of Project Blue Book.",
          "details": [

          ],
          "followers": [

          ],
          "link": [
            "review",
            {
              "review": "290",
              "version": 2
            }
          ],
          "preposition": "for",
          "projectList": {
            "blue-book": [
              "main"
            ]
          },
          "projects": {
            "blue-book": [
              "main"
            ]
          },
          "streams": {
            "0": "review-290",
            "1": "user-allison.clayborne",
            "2": "personal-allison.clayborne",
            "3": "project-blue-book",
            "7": "group-triage",
            "8": "personal-alex.randolph",
            "9": "personal-jack.boone"
          },
          "target": "review 290 (revision 2)",
          "time": 1548240419,
          "topic": "reviews/290",
          "type": "review",
          "url": "/main/reviews/290/v2/",
          "user": "allison.clayborne",
          "userExists": true,
          "userFullName": "Allison Clayborne"
        }
      ],
      "lastSeen": 618
    }

### Examples of usage

#### Fetching review activity

To get the latest activity entries on a review:

In this example, the review has more than 2 activities but the request has been made to limit the response to a max of 2 activities. This will return the most recent activities unless lastseen is included in the request. This allows for pagination of your results, see Activity pagination.

    curl -u "username:password" http://myswarm.url/api/v9/activity?stream=review-1234&fields=id,action,date,description,type&max=2

You can tweak `max` and `fields` to fetch the data that works best for you.

Swarm responds with an array of activity entities, and a `lastSeen` value that can be used for pagination:

    HTTP/1.1 200 OK

    {
      "activity": [
        {
          "id": 619,
          "action": "updated files in",
          "date": "2019-01-23T02:46:59-08:00",
          "description": "Start of Project Blue Book.",
          "type": "review"
        },
        {
          "id": 618,
          "action": "commented on",
          "date": "2019-01-23T02:46:19-08:00",
          "description": "This is a short comment.",
          "type": "comment"
        }
      ],
      "lastSeen": 618
    }

#### Activity pagination

To get the second page of activity entries for a review (based on the previous example):

    curl -u "username:password" "https://myswarm.url/api/v9/activity?stream=review-1234&fields=id,date,description,type&max=2&after=618"

Swarm again responds with a list of activity entities and an `lastSeen` value:

    HTTP/1.1 200 OK

    {
      "activity": [
        {
          "id": 617,
          "action": "commented on",
          "date": "2018-12-30T12:12:12-07:00",
          "description": "This is the first test comment.",
          "type": "comment"
        },
        {
          "id": 616,
          "action": "commented on",
          "date": "2018-12-27T12:13:14-07:00",
          "description": "Start of Project Blue Book.",
          "type": "review"
        }
      ],
      "lastSeen": 616
    }

## Create Activity Entry

### Summary

Create Activity Entry

POST /api/v9/activity

### Description

Creates an entry in the Activity List.

The authenticated user must match the user provided unless the authenticated user has minimum admin-level privileges in which case any user may be specified.

- Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Core Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
- Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
type | Type of activity, used for filtering activity streams (values can include `change`, `comment`, `job`, `review`). | string | form | Yes
user | User who performed the action. | string | form | Yes
action | Action that was performed - past-tense, for example, `created` or `commented on`. | string | form | Yes
target | Target that the action was performed on, for example, `issue 1234`. | string | form | Yes
topic | Optional topic for the activity entry. Topics are essentially comment thread IDs. Examples: `reviews/1234` or `jobs/job001234`. | string | form | No
description | Optional description of object or activity to provide context. | string | form | No
change | Optional changelist ID this activity is related to. Used to filter activity related to restricted changes. | integer | form | No
streams[] | Optional array of streams to display on. This can include user-initiated actions (`user-alice`), activity relating to a user’s followed projects/users (`personal-alice`), review streams (`review-1234`), and project streams (`project-exampleproject`). | array (of strings) | form | No
link | Optional URL for `target`. | string | form | No

### Examples of usage

#### Creating an activity entry

To create a plain activity entry:

    curl -u "username:password"
         -X POST
         -d "type=job"
         -d "user=jira"
         -d "action=punted"
         -d "target=review 123" \
         "https://myswarm.url/api/v9/activity"

JSON Response:

    HTTP/1.1 200 OK

    {
      "activity":{
        "id":620,
        "action":"punted",
        "behalfOf":null,
        "change":null,
        "depotFile":null,
        "description":null,
        "details":[

        ],
        "followers":[

        ],
        "link":null,
        "preposition":"for",
        "projects":[

        ],
        "streams":[

        ],
        "target":"review 123",
        "time":1560783425,
        "topic":null,
        "type":"job",
        "user":"jira"
      }
    }

#### Linking an activity entry to a review

Linking activity entries to reviews is useful. This involves providing `link`, `streams`, and `topic` fields in the activity data. The `link` field is used to make the `review 123` string in the activity entry clickable. The `stream` field is needed so that the activity entry can be attached to the review in the Swarm interface. The `topic` field is used to link the activity entry to the comment thread for that topic, in the event that a user wants to comment on the activity.

To create a fully linked activity entry:

    curl -u "username:password"
         -X POST
         -d "type=job"
         -d "user=jira"
         -d "action=punted"
         -d "target=review 123" \
         -d "streams[]=review-123" \
         -d "link=reviews/123" \
         -d "topic=reviews/123" \
         "https://myswarm.url/api/v9/activity"

Swarm responds with an activity entity:

    HTTP/1.1 200 OK

    {
      "activity": {
        "id": 1375,
        "action": "punted",
        "behalfOf": null,
        "change": null,
        "depotFile": null,
        "description": null,
        "details": [

        ],
        "followers": [

        ],
        "link": "reviews/123",
        "preposition": "for",
        "projects": [

        ],
        "streams": [
          "review-123"
        ],
        "target": "review 123",
        "time": 1461607739,
        "topic": "reviews/123",
        "type": "job",
        "user": "jira"
      }
    }

Your search for returned results