# addItemsToCollection

Mutation

Add up to 1,000 listed items, or every item a filter matches, to one Collection in the background; returns an operationId to poll with `operation(id:)`.

Available to agents as MCP tool `addItemsToCollection` — see [Write tools](/api/v2/docs/mcp/write-tools#add-items-to-collection).

## Arguments

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `collectionId` | `ID!` | Yes | — | The Collection to add the items to, as returned by the `collections` query. A workspace whose Collections use the legacy format is refused with a userError on `["collectionId"]`. |
| `customAttributeConditions` | [`[CustomAttributeConditionInput!]`](/api/v2/docs/types/custom-attribute-condition-input) | No | — | Add every item matching these custom-attribute conditions (AND), as `items(customAttributeConditions:)` would list them. Combine with `filter`; omit `itemIds`. |
| `filter` | [`ItemFilterInput`](/api/v2/docs/types/item-filter-input) | No | — | Add every item this filter matches, as `items(filter:)` would list them. Combine with `customAttributeConditions`; omit `itemIds`. More than 10000 matching items is a userError on `["filter"]` and adds nothing. |
| `itemIds` | `[ID!]` | No | — | Item ids to add, as returned by `items`. At least 1 and at most 1000. An id that does not resolve in this workspace is skipped and returned in `skippedItemIds`. Omit it to add by `filter` / `customAttributeConditions` instead. |

## Returns

| Name | Type | Description |
| --- | --- | --- |
| `acceptedCount` | `Int!` | Number of distinct items scheduled. |
| `operationId` | `ID` | The background operation; poll it with `operation(id:)` and its per-item outcomes with `operationRecords`. Null when `scheduled` is false. |
| `scheduled` | `Boolean!` | True when an operation was scheduled. False when userErrors is non-empty or when no item resolved in this workspace. |
| `skippedItemIds` | `[ID!]!` | Submitted item ids that do not resolve in this workspace and were not scheduled. Always empty for a filter. |
| `userErrors` | [`[UserError!]!`](/api/v2/docs/types/user-error) | Errors that refused the whole request: an empty or oversized id list, a filter matching too many items, an unknown or unwritable collection, a legacy-format workspace, or a workspace with no user to attribute the operation to. Empty on success. |

## Examples

### Add items to a collection

Schedule a background operation that adds every item a filter matches to one collection.

```graphql
mutation AddItemsToCollectionDefault($collectionId: ID!, $filter: ItemFilterInput) {
  addItemsToCollection(collectionId: $collectionId, filter: $filter) {
    scheduled
    operationId
    acceptedCount
    skippedItemIds
    userErrors {
      field
      message
    }
  }
}
```

Variables:

```json
{
  "collectionId": "122321ce-843e-5b07-9f56-94323c0ae39e",
  "filter": {
    "provider": "INSTAGRAM"
  }
}
```

Response — HTTP 200:

```json
{
  "data": {
    "addItemsToCollection": {
      "scheduled": true,
      "operationId": "94b14f94-2226-5d42-a80e-78a99db753c4",
      "acceptedCount": 12,
      "skippedItemIds": [],
      "userErrors": []
    }
  }
}
```