# engagementHistory

Query

Paginated history of engagement metric snapshots for a specific item, ordered newest first.

Available to agents as MCP tool `getEngagementHistory` — see [Read tools](/api/v2/docs/mcp/read-tools#get-engagement-history).

## Arguments

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `after` | `String` | No | `null` | Cursor for fetching the next page of results. |
| `filter` | [`EngagementHistoryFilterInput`](/api/v2/docs/types/engagement-history-filter-input) | No | `null` | Filter criteria for engagement history entries. |
| `first` | `Int` | No | `20` | Number of entries to return (page size). |
| `itemId` | `ID!` | Yes | — | The ID of the item to fetch engagement history for. |

## Returns

A paginated connection of [`EngagementHistoryEntry`](/api/v2/docs/types/engagement-history-entry) nodes. See [Pagination](/api/v2/docs/types/pagination) for the connection shape.

## Examples

### List an item's engagement history

Paginate an item's engagement metric snapshots, newest first.

```graphql
query EngagementHistoryDefault($itemId: ID!, $first: Int) {
  engagementHistory(itemId: $itemId, first: $first) {
    totalCount
    edges {
      node {
        at
        likes
        comments
        views
        shares
        earnedMediaValue
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

Variables:

```json
{
  "itemId": "63c311c4-32f0-5d8c-ac02-78b160f2290a",
  "first": 5
}
```

Response — HTTP 200:

```json
{
  "data": {
    "engagementHistory": {
      "totalCount": 3,
      "edges": [
        {
          "node": {
            "at": "2025-01-01T00:00:00Z",
            "likes": "100",
            "comments": "10",
            "views": null,
            "shares": "5",
            "earnedMediaValue": "200"
          }
        },
        {
          "node": {
            "at": "2024-12-31T23:00:00Z",
            "likes": "100",
            "comments": "10",
            "views": null,
            "shares": "5",
            "earnedMediaValue": "200"
          }
        },
        {
          "node": {
            "at": "2024-12-31T22:00:00Z",
            "likes": "100",
            "comments": "10",
            "views": null,
            "shares": "5",
            "earnedMediaValue": "200"
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "Z2lkOi8vYXJjaGl2ZS9FbmdhZ2VtZW50SGlzdG9yeUVudHJ5LzJkYTYyMTI4LTY1YTctNThhZi1hOGI2LTMwMWM3NTdlMjA4Zg=="
      }
    }
  }
}
```

### Filter engagement history by capture window

Return an item's engagement snapshots captured within a window.

```graphql
query EngagementHistoryFiltered($itemId: ID!, $filter: EngagementHistoryFilterInput, $first: Int) {
  engagementHistory(itemId: $itemId, filter: $filter, first: $first) {
    totalCount
    edges {
      node {
        at
        likes
        views
        earnedMediaValue
      }
    }
  }
}
```

Variables:

```json
{
  "itemId": "63c311c4-32f0-5d8c-ac02-78b160f2290a",
  "filter": {
    "capturedAt": {
      "from": "2024-12-25T00:00:00Z",
      "to": "2025-01-01T00:00:00Z"
    }
  },
  "first": 10
}
```

Response — HTTP 200:

```json
{
  "data": {
    "engagementHistory": {
      "totalCount": 3,
      "edges": [
        {
          "node": {
            "at": "2025-01-01T00:00:00Z",
            "likes": "100",
            "views": null,
            "earnedMediaValue": "200"
          }
        },
        {
          "node": {
            "at": "2024-12-31T23:00:00Z",
            "likes": "100",
            "views": null,
            "earnedMediaValue": "200"
          }
        },
        {
          "node": {
            "at": "2024-12-31T22:00:00Z",
            "likes": "100",
            "views": null,
            "earnedMediaValue": "200"
          }
        }
      ]
    }
  }
}
```