Mutation

addItemsToCollection

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:).

MCP: addItemsToCollection

Arguments

Object, input and enum types open in place — use + to reveal their fields. A type that is already open above the row stops at a ↻ circular marker, and anything nested past the depth limit links out to its own page instead.

collectionId ID! required: 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!]: Add every item matching these custom-attribute conditions (AND), as items(customAttributeConditions:) would list them. Combine with filter; omit itemIds.
field String! required: Key of the custom attribute to filter on, as returned by customAttributeSchemas (e.g. "sentiment").
operator FilterOperator! required: Comparison operator. The valid set depends on the attribute type; see FilterOperator.
BETWEEN: Inclusive range match for number and date types; value is { from, to }.
CONTAINS: For text-like types: substring match. For multi-select and list types: matches records containing ANY of the provided values (OR semantics).
CONTAINS_ALL: For multi-select custom attributes: matches records whose value array contains ALL of the provided values (AND semantics).
DOES_NOT_CONTAIN: For text-like types: excludes substring matches. For multi-select and list types: excludes records containing any of the provided values.
ENDS_WITH: Suffix match, for text-like types.
EQUAL: Equality, for number and date types.
IS: Exact match. For text and single-select types (for selects, value is the option ID) and BOOLEAN (value is true/false).
IS_EMPTY: Matches records with no value set. Value is ignored; pass null.
IS_NOT: Exact non-match, for text and single-select types.
IS_NOT_EMPTY: Matches records with any value set. Value is ignored; pass null.
IS_RELATIVE_TO_TODAY: Matches date values in a period relative to today; value is { relation: "past"|"this"|"next", period: "day"|"week"|"month"|"year" } (offset optional: a whole number of periods, at most 100 years; tz optional: an IANA time zone).
LESS_THAN: Strictly less than, for number and date types.
LESS_THAN_OR_EQUAL: Less than or equal, for number and date types.
MORE_THAN: Strictly greater than, for number and date types.
MORE_THAN_OR_EQUAL: Greater than or equal, for number and date types.
NOT_EQUAL: Inequality, for number and date types.
STARTS_WITH: Prefix match, for text-like types.
type CustomAttributeType! required: Type of the custom attribute, as returned by customAttributeSchemas. Determines the expected value shape and the valid operators.
BOOLEAN: True/false value.
BOOLEAN_LIST: List of true/false values.
DATE: Calendar date value (ISO 8601, no time component).
DATETIME: Date-and-time value (ISO 8601).
DATETIME_LIST: List of date-and-time values (ISO 8601).
DATE_LIST: List of calendar date values (ISO 8601, no time component).
EMAIL: Email address value.
MULTIPLE_SELECT: Multiple choices from a predefined option list; the stored value is an array of option IDs.
MULTIPLE_SELECT_V2: Multiple choices from a predefined option list; the stored value is an array of option IDs. Successor revision of MULTIPLE_SELECT with identical filtering behavior.
NUMBER: Numeric value.
NUMBER_LIST: List of numeric values.
PHONE: Phone number value.
SHIPPING_ADDRESS: Structured shipping address. Not filterable: conditions with this type are rejected with a validation error; read the value from the record's customAttributes instead.
SINGLE_SELECT_V2: Single choice from a predefined option list; the stored value is an option ID.
SINGLE_SELECT_V3: Single choice from a predefined option list; the stored value is an option ID. Successor revision of SINGLE_SELECT_V2 with identical filtering behavior.
TEXT: Free-form text value.
TEXT_LIST: List of free-form text values.
URL: URL value.
value JSON: Comparison value; the shape depends on type: a string for text-like types, an option ID for single-selects, a number for NUMBER, an ISO 8601 string for dates, true/false for BOOLEAN, an array for multi-select and list types. BETWEEN takes { from, to }. Pass null for IS_EMPTY / IS_NOT_EMPTY.
filter ItemFilterInput: 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.
accountNames [String!] default []: Filter by social profile account names/handles.
brandRelatedOnly Boolean: When true, apply the workspace's brand-related-content setting exactly as the app's Content page does (product-detection or campaign membership); has no effect when the workspace setting is off. Omitted, null or false leaves results unscoped.
campaignsIds [ID!] default []: Filter to items associated with any of the given campaign IDs.
collectionsIds [ID!] default []: Filter to items that belong to any of the given collection IDs in the current workspace. Pass the IDs the collections query returns; the ID values in Item.customAttributes.collections are accepted too. An empty list (the default) applies no collection filter, like every other list filter here; an ID that names no collection matches no items.
contentTypes [MediaContentType!]: Filter by media content type (IMAGE, VIDEO).
IMAGE: Static image content (for example photos, thumbnails, frames).
VIDEO: Video content (for example Reels, TikToks, Stories, YouTube videos).
creatorIds [ID!] default []: Filter to items authored by any of the given creator IDs (the id the creators query returns; maximum 1000). An empty list (the default) applies no creator filter.
creatorLocations [LocationCanonicalInput!]: Filter by the creator's location. Format: an array of objects, each with optional country, region, city (canonical names from Archive's Geo normalization pipeline; case-sensitive exact match, e.g. "United States", "California", "Los Angeles"). Within a single entry, populated components are AND-ed together. Multiple entries OR together, which is useful for disambiguating same-named cities (e.g. Portland, Oregon vs. Portland, Maine). Omit a component to leave it unconstrained. Example: [{ country: "United States", region: "California" }, { city: "London" }] matches creators in California, USA OR in any city named "London".
city String: Canonical city name (e.g. "Portland"). Matches creator.city_canonical exactly.
country String: Canonical country name (e.g. "United States"). Matches creator.country_canonical exactly.
group String: Region group code from locationGroups (e.g. "european_union", "dach"). The entry matches every member country of the group and country/region/city are ignored in it; an unknown code matches nothing.
region String: Canonical region/state name (e.g. "Oregon"). Matches creator.region_canonical exactly.
engagement [FilterEngagementRangeInput!]: Filter by engagement metric ranges (likes, comments, views, etc.).
field FilterEngagementField! required: Engagement metric to filter on.
COMMENT_COUNT: Total number of comments.
EARNED_MEDIA_VALUE: Estimated earned media value (EMV) in cents.
ENGAGEMENTS_RATE: Engagement rate: total engagements divided by the creator's follower count. Bounds are whole percent (5 = 5%); values below 1% are not expressible.
IMPRESSIONS_RATE: Impressions rate: views, plays, or estimated impressions divided by the creator's follower count. Bounds are whole percent (5 = 5%); values below 1% are not expressible.
LIKE_COUNT: Total number of likes.
MERGED_VIEW_PLAY_COUNT: Number of views, plays, or estimated impressions.
SHARE_COUNT: Total number of shares.
range FilterIntegerRangeInput! required: Inclusive numeric range the metric value must fall within.
from Int: Inclusive lower bound. Omit for no lower bound.
to Int: Inclusive upper bound. Omit for no upper bound.
excludeCollectionsIds [ID!] default []: Drop items that belong to any of the given collection IDs in the current workspace. Accepts the same IDs as collectionsIds and combines with it (AND): pass both to keep items in one collection but not another. An empty list (the default) excludes nothing; an ID that names no collection excludes no items.
followersCount FilterIntegerRangeInput: Filter by social profile follower count range.
from Int: Inclusive lower bound. Omit for no lower bound.
to Int: Inclusive upper bound. Omit for no upper bound.
ids [ID!] default []: Filter to specific item IDs (maximum 1000).
importType FilterImportType: Filter by how the item was imported (manual or automatic).
AUTOMATIC: Item was captured automatically (e.g. by social listening).
MANUAL: Item was imported on request by a user.
instagramWhitelistingStatus [FilterContractStatus!]: Filter by Instagram whitelisting request status.
APPROVED: Contract has been approved by the creator.
EXPIRED: Contract approval has expired.
IN_QUEUE: Contract request is queued for processing.
REJECTED: Contract request was rejected by the creator.
REQUESTED: Contract has been requested but not yet responded to.
itemTypes [FilterItemType!]: Filter by item type (POST, REEL, STORY, TIKTOK, TIKTOK_STORY, YOUTUBE, YOUTUBE_SHORT). Each value names a platform and a format together, unlike Item.type: a TikTok post reads type: POST but matches TIKTOK here, and POST matches Instagram feed posts only.
POST: Instagram feed post.
REEL: Instagram Reel.
STORY: Instagram Story.
TIKTOK: TikTok video post.
TIKTOK_STORY: TikTok Story.
YOUTUBE: YouTube video.
YOUTUBE_SHORT: YouTube Short.
provider Provider: Filter by source platform (INSTAGRAM, TIKTOK, YOUTUBE, INTERNAL).
INSTAGRAM: Instagram platform integration, including posts, reels, stories, and profile data.
INTERNAL: Internal Archive-managed source used for synthetic or system-generated content.
TIKTOK: TikTok platform integration, including videos and creator profile data.
YOUTUBE: YouTube platform integration, including Shorts, videos, thumbnails, and profile data.
shopifyProductsIds [String!] default []: Filter by associated Shopify product IDs.
socialProfileAccountTypes [SocialProfileAccountType!] default []: Filter by the social profile's account type. Values currently reflect Instagram-only typing (Personal / Creator / Business); profiles on platforms without a comparable concept are excluded when this filter is supplied. Mirrors Influencer.account_type. OR semantics across multiple values; empty/omitted skips the filter.
BUSINESS: Instagram Business account (business features and insights enabled).
CREATOR: Instagram Creator account (creator features enabled, distinct from Business).
PERSONAL: Personal Instagram account (consumer profile, no business/creator features).
socialProfileIds [ID!] default []: Filter by social profile IDs.
sourcesIds [ID!] default []: Filter by source IDs.
sourcesIdsOperator FilterOperator: How sourcesIds matches. Accepted values: CONTAINS, CONTAINS_ALL, DOES_NOT_CONTAIN, IS_EMPTY, IS_NOT_EMPTY; any other FilterOperator is refused with INVALID_INPUT. Omitted means CONTAINS (any of the listed values). CONTAINS_ALL requires every listed value; DOES_NOT_CONTAIN drops items carrying any listed value; IS_EMPTY / IS_NOT_EMPTY match items with no / at least one value and ignore the list. CONTAINS, CONTAINS_ALL and DOES_NOT_CONTAIN with an empty list apply no filter.
BETWEEN: Inclusive range match for number and date types; value is { from, to }.
CONTAINS: For text-like types: substring match. For multi-select and list types: matches records containing ANY of the provided values (OR semantics).
CONTAINS_ALL: For multi-select custom attributes: matches records whose value array contains ALL of the provided values (AND semantics).
DOES_NOT_CONTAIN: For text-like types: excludes substring matches. For multi-select and list types: excludes records containing any of the provided values.
ENDS_WITH: Suffix match, for text-like types.
EQUAL: Equality, for number and date types.
IS: Exact match. For text and single-select types (for selects, value is the option ID) and BOOLEAN (value is true/false).
IS_EMPTY: Matches records with no value set. Value is ignored; pass null.
IS_NOT: Exact non-match, for text and single-select types.
IS_NOT_EMPTY: Matches records with any value set. Value is ignored; pass null.
IS_RELATIVE_TO_TODAY: Matches date values in a period relative to today; value is { relation: "past"|"this"|"next", period: "day"|"week"|"month"|"year" } (offset optional: a whole number of periods, at most 100 years; tz optional: an IANA time zone).
LESS_THAN: Strictly less than, for number and date types.
LESS_THAN_OR_EQUAL: Less than or equal, for number and date types.
MORE_THAN: Strictly greater than, for number and date types.
MORE_THAN_OR_EQUAL: Greater than or equal, for number and date types.
NOT_EQUAL: Inequality, for number and date types.
STARTS_WITH: Prefix match, for text-like types.
superSearch FilterSuperSearchInput: Visual or semantic search parameters.
fileName String deprecated: Ignored: no search reads it, so it has no effect on results. Has no effect. For visual similarity search use imageUrl or similarMediaContentId.
imageUrl String: URL of an external image to use for visual similarity search. Must be a public http(s) URL; private or local hosts, a malformed URL, or an image that cannot be downloaded return an INVALID_INPUT error.
mode FilterSuperSearchMode: Search mode determining how the query is processed. Defaults to EMBEDDING_CONTENT when omitted. The FUZZY modes search text only, so they need searchQuery.
EMBEDDING_CONTENT: Search by visual/semantic similarity using content embeddings.
FUZZY_CAPTION: Search by fuzzy matching against post captions.
FUZZY_TRANSCRIPTION: Search by fuzzy matching against video/audio transcriptions.
searchQuery String: Text query to search captions, transcriptions, or semantic content. A blank value is no search query. The text is matched as written (semantic similarity for EMBEDDING_CONTENT, fuzzy text match for FUZZY_CAPTION / FUZZY_TRANSCRIPTION); it is never turned into structured filters the way the Archive app's natural-language search can be. To narrow by hashtags, handles, dates, platform or engagement, set tagsNames, accountNames, takenAt, provider / itemTypes or engagement on the filter yourself.
similarMediaContentId ID: ID of a media content to find visually similar items (the numeric MediaContent.id). Any other value returns an INVALID_INPUT error.
tagsNames [String!] default []: Filter by hashtag or mention tag names (maximum 100).
tagsNamesOperator FilterOperator: How tagsNames matches. Accepted values: CONTAINS, CONTAINS_ALL, DOES_NOT_CONTAIN, IS_EMPTY, IS_NOT_EMPTY; any other FilterOperator is refused with INVALID_INPUT. Omitted means CONTAINS (any of the listed values). CONTAINS_ALL requires every listed value; DOES_NOT_CONTAIN drops items carrying any listed value; IS_EMPTY / IS_NOT_EMPTY match items with no / at least one value and ignore the list. CONTAINS, CONTAINS_ALL and DOES_NOT_CONTAIN with an empty list apply no filter. A name that matches no tag in the workspace is ignored by DOES_NOT_CONTAIN.
BETWEEN: Inclusive range match for number and date types; value is { from, to }.
CONTAINS: For text-like types: substring match. For multi-select and list types: matches records containing ANY of the provided values (OR semantics).
CONTAINS_ALL: For multi-select custom attributes: matches records whose value array contains ALL of the provided values (AND semantics).
DOES_NOT_CONTAIN: For text-like types: excludes substring matches. For multi-select and list types: excludes records containing any of the provided values.
ENDS_WITH: Suffix match, for text-like types.
EQUAL: Equality, for number and date types.
IS: Exact match. For text and single-select types (for selects, value is the option ID) and BOOLEAN (value is true/false).
IS_EMPTY: Matches records with no value set. Value is ignored; pass null.
IS_NOT: Exact non-match, for text and single-select types.
IS_NOT_EMPTY: Matches records with any value set. Value is ignored; pass null.
IS_RELATIVE_TO_TODAY: Matches date values in a period relative to today; value is { relation: "past"|"this"|"next", period: "day"|"week"|"month"|"year" } (offset optional: a whole number of periods, at most 100 years; tz optional: an IANA time zone).
LESS_THAN: Strictly less than, for number and date types.
LESS_THAN_OR_EQUAL: Less than or equal, for number and date types.
MORE_THAN: Strictly greater than, for number and date types.
MORE_THAN_OR_EQUAL: Greater than or equal, for number and date types.
NOT_EQUAL: Inequality, for number and date types.
STARTS_WITH: Prefix match, for text-like types.
takenAt FilterDateRangeInput: Filter by publication date range.
from DateTime: Inclusive lower bound (ISO 8601). Omit for no lower bound.
to DateTime: Inclusive upper bound (ISO 8601). Omit for no upper bound.
tiktokSparkCodeStatus [FilterContractStatus!]: Filter by TikTok Spark Code request status.
APPROVED: Contract has been approved by the creator.
EXPIRED: Contract approval has expired.
IN_QUEUE: Contract request is queued for processing.
REJECTED: Contract request was rejected by the creator.
REQUESTED: Contract has been requested but not yet responded to.
tiktokWhitelistingEligibility FilterTikTokWhitelistingEligibility: Filter to items authored by TikTok creators eligible for whitelisting.
ALL: Match items authored by TikTok creators reachable via manual DM for whitelisting.
ugcLocations [LocationCanonicalInput!]: Filter by the location tagged on the content itself (UGC location). Format: same as creatorLocations: an array of objects with optional country, region, city (canonical, case-sensitive exact match). Within a single entry the populated components AND together; multiple entries OR together. Example: [{ country: "United Kingdom", city: "London" }] matches items whose tagged location resolves to London, UK.
city String: Canonical city name (e.g. "Portland"). Matches creator.city_canonical exactly.
country String: Canonical country name (e.g. "United States"). Matches creator.country_canonical exactly.
group String: Region group code from locationGroups (e.g. "european_union", "dach"). The entry matches every member country of the group and country/region/city are ignored in it; an unknown code matches nothing.
region String: Canonical region/state name (e.g. "Oregon"). Matches creator.region_canonical exactly.
usageRightsStatus [FilterContractStatus!]: Filter by usage rights request status.
APPROVED: Contract has been approved by the creator.
EXPIRED: Contract approval has expired.
IN_QUEUE: Contract request is queued for processing.
REJECTED: Contract request was rejected by the creator.
REQUESTED: Contract has been requested but not yet responded to.
verified [Boolean!]: Filter by social profile verification status.
viralityScore [FilterViralityScore!] default []: Filter by virality score categories.
HIGH: Content that significantly outperforms its expected reach. Typically corresponds to a view-to-follower ratio of 4.0 or higher.
LOW: Content performing close to expected baseline relative to audience size. Typically corresponds to a view-to-follower ratio between ~1.0 and 2.0.
MEDIUM: Content performing above average relative to audience size. Typically corresponds to a view-to-follower ratio between ~2.0 and 4.0.
NOT_VIRAL: Content performing below expected reach, with low relative visibility. Typically corresponds to a view-to-follower ratio below ~1.0.
itemIds [ID!]: 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

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!]!: 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.
field [String!]: Path to the input field that caused the error.
message String!: The error message.

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

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