# refetchEngagementBulk

Mutation

Queue a bulk engagement data refresh for the specified items.

Available to agents as MCP tool `refetchEngagementBulk` — see [Write tools](/api/v2/docs/mcp/write-tools#refetch-engagement-bulk).

## Arguments

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `itemIds` | `[ID!]!` | Yes | — | IDs of items to refresh engagement data for. Items belonging to other workspaces are silently ignored. Instagram stories are automatically excluded. |

## Returns

| Name | Type | Description |
| --- | --- | --- |
| `operationId` | `ID` | Unique identifier of the background operation created to process the refresh. Null when no items were processable (all filtered or deduplicated). Use this ID to track operation progress. |
| `processedCount` | `Int` | Number of items accepted and queued for engagement refresh. Credits are charged only for this count. |
| `skippedItemIds` | `[ID!]` | IDs of items skipped because they are already enqueued in another active refresh operation for this workspace. Instagram stories are silently excluded and not listed here. |
| `userErrors` | [`[UserError!]!`](/api/v2/docs/types/user-error) | Errors that prevented the mutation from executing. Common error: insufficient credits. |

## Examples

### Refresh engagement for items

Queue a background job to refresh engagement metrics for the given items.

```graphql
mutation RefetchEngagementBulkDefault($itemIds: [ID!]!) {
  refetchEngagementBulk(itemIds: $itemIds) {
    operationId
    processedCount
    skippedItemIds
    userErrors {
      field
      message
    }
  }
}
```

Variables:

```json
{
  "itemIds": [
    "63c311c4-32f0-5d8c-ac02-78b160f2290a",
    "a78ec1f9-5c4b-5c8a-b3b1-e028e575b606"
  ]
}
```

Response — HTTP 200:

```json
{
  "data": {
    "refetchEngagementBulk": {
      "operationId": "046a8f4e-686e-5773-9374-eb91cfd0c54c",
      "processedCount": 2,
      "skippedItemIds": [],
      "userErrors": []
    }
  }
}
```