Items (UGC)

Reminder: All queries on this page require the WORKSPACE-ID header. See Getting Started for setup.

Items are the content archived in your workspace — posts, reels, stories, and videos created by your creators. In Archive, this is the UGC (User-Generated Content) that your brand collects and tracks across social platforms. This is the same content you browse in the Media Deck in the Archive UI.

Learn more: What types of UGC does Archive collect? | Understanding UGC Metrics

Each item includes the original caption, publication date, engagement metrics, a link to the original post, and additional metadata like hashtags, mentions, and location.

Terminology: Item is the canonical API term. You may see the same concept referred to as UGC, content, or posts in the Archive UI and in these docs — they all mean the same thing.

All available item fields

Every item returned from the items query can include these fields:

Field	Type	Description
`id`	ID	Unique item identifier
`caption`	String	Post caption text
`type`	Enum	Content format returned in responses: `POST` (feed posts, TikTok videos, YouTube videos), `REEL` (Instagram Reels), `STORY` (Instagram Stories), `SHORT` (YouTube Shorts). Note: when filtering, use `YOUTUBE_SHORT` (not `SHORT`) — see the filter table below.
`provider`	Enum	Platform: `INSTAGRAM`, `TIKTOK`, `YOUTUBE`, `INTERNAL` (manually imported content)
`takenAt`	DateTime	Publication date
`originalUrl`	String	Link to the original post on the platform
`externalId`	ID	Platform’s native ID (e.g., Instagram shortcode)
`mediaItemId`	ID	Internal media item reference
`hashtags`	String[]	Hashtags on the post
`mentions`	String[]	Mentions on the post
`customAttributes`	JSON	Item-level custom attributes
`location`	Object	Content location: `name`, `city`, `country`, `state`, `formatted`
`currentEngagement.likes`	BigInt (string)	Number of likes
`currentEngagement.comments`	BigInt (string)	Number of comments
`currentEngagement.shares`	BigInt (string)	Number of shares (TikTok only)
`currentEngagement.views`	BigInt (string)	Views — platform-reported for Reels/TikTok/YouTube, estimated for Posts/Stories
`currentEngagement.impressions`	BigInt (string)	Number of views, plays, or estimated impressions depending on the platform and content type
`currentEngagement.earnedMediaValue`	BigInt (string)	EMV in cents — divide by 100 for dollars
`currentEngagement.linearViralityScore`	Enum	Virality: `HIGH`, `MEDIUM`, `LOW`, `NOT_VIRAL`
`socialProfile`	Object	The social profile that posted this content
`creator`	Object	The full creator from your CRM (with customAttributes and all socialProfiles)
`transcriptions`	Array	Video transcriptions inline

Query items

List recent items

The query below requests every available field. Use it as a reference and remove the fields you don’t need:


query ListItems {
  items(
    first: 20
    sorting: { sortKey: TAKEN_AT, sortOrder: DESC }
  ) {
    nodes {
      id
      caption
      type
      provider
      takenAt
      originalUrl
      externalId
      mediaItemId
      hashtags
      mentions
      customAttributes
      location {
        name
        city
        country
        state
        formatted
      }
      currentEngagement {
        likes
        comments
        shares
        views
        impressions
        earnedMediaValue
        linearViralityScore
      }
      socialProfile {
        id
        accountName
        fullName
        provider
        followers
        following
        verified
        proAccount
        private
        avatar
        originalUrl
        email
        phoneNumbers
      }
      creator {
        id
        customAttributes
        socialProfiles {
          accountName
          provider
          followers
        }
      }
      transcriptions {
        mediaContentId
        transcript
      }
    }
    pageInfo { hasNextPage endCursor hasPreviousPage startCursor }
    totalCount
  }
}

Example response:


{
  "data": {
    "items": {
      "totalCount": 1052,
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "eyJpZCI6Ii4uLiJ9",
        "hasPreviousPage": false,
        "startCursor": "eyJpZCI6Ii4uLiJ9"
      },
      "nodes": [
        {
          "id": "a4b1c2d3-e5f6-7890-abcd-ef1234567890",
          "caption": "Summer linen set — obsessed with this look for travel",
          "type": "REEL",
          "provider": "INSTAGRAM",
          "takenAt": "2026-03-28T14:30:00Z",
          "originalUrl": "https://www.instagram.com/reel/example123/",
          "externalId": "ABC123def456",
          "mediaItemId": "1b24fdeb-6a96-4485-9890-da470bd92ce1",
          "hashtags": ["summerstyle", "linenlook"],
          "mentions": ["lauramendez"],
          "customAttributes": {
            "post_summary": "Creator shares a summer linen look for travel",
            "sentiment": null
          },
          "location": {
            "name": "Miami Beach",
            "city": "Miami",
            "country": "United States",
            "state": "Florida",
            "formatted": "Miami Beach, Miami, Florida, United States"
          },
          "currentEngagement": {
            "likes": "8420",
            "comments": "213",
            "shares": "47",
            "views": "94000",
            "impressions": "110500",
            "earnedMediaValue": "12300",
            "linearViralityScore": "MEDIUM"
          },
          "socialProfile": {
            "id": "4829301",
            "accountName": "lauramendez",
            "fullName": "Laura Méndez",
            "provider": "INSTAGRAM",
            "followers": 312000,
            "following": 840,
            "verified": false,
            "proAccount": true,
            "private": false,
            "avatar": "https://cdn.archive.com/avatars/lauramendez.jpg",
            "originalUrl": "https://instagram.com/lauramendez",
            "email": "contact@lauramendez.com",
            "phoneNumbers": []
          },
          "creator": {
            "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
            "customAttributes": {
              "full_name": "Laura Méndez",
              "location": "Miami, United States",
              "emails": ["contact@lauramendez.com"]
            },
            "socialProfiles": [
              { "accountName": "lauramendez", "provider": "INSTAGRAM", "followers": 312000 },
              { "accountName": "lauramendez.style", "provider": "TIKTOK", "followers": 890000 }
            ]
          },
          "transcriptions": [
            {
              "mediaContentId": "9182736",
              "transcript": "Okay so I finally got my hands on this linen set..."
            }
          ]
        }
      ]
    }
  }
}

About externalId: This is the platform’s native ID for the content (e.g., the Instagram shortcode DRyckrbDdWw). Useful for cross-referencing with platform URLs.

About creator: Each item has both a socialProfile (the specific account that posted) and a creator (the person in your CRM, with all their custom attributes and linked social profiles). Use creator when you need the full CRM context for each piece of content.

Important notes about engagement values:

All engagement values are returned as strings — parse them as numbers before doing math.

earnedMediaValue is returned in cents. Divide by 100 to get the dollar amount (e.g., "12300" = $123.00).

Some fields may be null if the platform doesn’t provide them — see the Metrics by content type table below.

Engagement data is not real-time. Archive takes snapshots at approximately 2 hours, 24 hours, 3 days, and 7 days after publication. After 7 days, updates slow down significantly unless the post continues to receive high engagement.

Using with AI:

“Show me the most recent content in my workspace” “How many items do I have in total?”

Filtering items

Filter	Type	Description
`ids`	ID[]	Filter to specific item IDs
`provider`	Enum	Filter by source platform: `INSTAGRAM`, `TIKTOK`, `YOUTUBE`, `INTERNAL` (manually imported content — uploaded via file or UGC link)
`itemTypes`	Enum[]	Filter by item type: `POST`, `REEL`, `STORY`, `TIKTOK`, `YOUTUBE`, `YOUTUBE_SHORT`
`contentTypes`	Enum[]	Filter by media content type: `IMAGE`, `VIDEO`
`takenAt`	Date range	Filter by publication date range (`from` / `to` in UTC, must end with `Z`)
`engagement`	Object[]	Filter by engagement metric ranges — likes, comments, views, shares, engagement rate, impressions rate, EMV (see By engagement range)
`viralityScore`	Enum[]	Filter by virality score categories: `HIGH`, `MEDIUM`, `LOW` — note: `NOT_VIRAL` appears in response data but cannot be used as a filter value
`tagsNames`	String[]	Filter by hashtag or mention tag names
`sourcesIds`	ID[]	Filter by source IDs (connected social accounts or tracked hashtags)
`importType`	Enum	Filter by how the item was imported: `MANUAL` or `AUTOMATIC`
`shopifyProductsIds`	String[]	Filter by associated Shopify product IDs
`socialProfileIds`	ID[]	Filter by social profile IDs
`accountNames`	String[]	Filter by social profile account names/handles
`followersCount`	Int range	Filter by social profile follower count range (`from` / `to`)
`verified`	Boolean[]	Filter by social profile verification status
`creatorLocation`	Object	Filter by creator location — city, state, or country (`query: "New York"`)
`ugcLocation`	Object	Filter by content location — name, city, state, or country (`query: "Los Angeles"`)
`tiktokSparkCodeStatus`	Enum[]	Filter by TikTok Spark Code request status: `APPROVED`, `EXPIRED`, `IN_QUEUE`, `REJECTED`, `REQUESTED`
`instagramWhitelistingStatus`	Enum[]	Filter by Instagram whitelisting request status: `APPROVED`, `EXPIRED`, `IN_QUEUE`, `REJECTED`, `REQUESTED`
`usageRightsStatus`	Enum[]	Filter by usage rights request status: `APPROVED`, `EXPIRED`, `IN_QUEUE`, `REJECTED`, `REQUESTED`
`superSearch`	Object	Visual or semantic search — by caption text, transcription, visual similarity, or image URL

By platform and content type


query InstagramReels {
  items(
    first: 20
    filter: {
      provider: INSTAGRAM
      itemTypes: [REEL]
    }
  ) {
    totalCount
    nodes { id caption type provider takenAt }
  }
}

Example response:


{
  "data": {
    "items": {
      "totalCount": 29,
      "nodes": [
        {
          "id": "a4b1c2d3-e5f6-7890-abcd-ef1234567890",
          "caption": "New soju spirit tasting in NYC — what a night!",
          "type": "REEL",
          "provider": "INSTAGRAM",
          "takenAt": "2026-03-28T14:30:00Z"
        }
      ]
    }
  }
}

Using with AI:

“Show me all Instagram Reels” “List only TikTok content” “Find all YouTube Shorts in my workspace”

Combine with: takenAt (date range), accountNames (specific creators), followersCount, viralityScore, tagsNames (hashtags), engagement (metric ranges)

By date range

Dates must be in UTC format (ending with Z):


query ItemsByDate {
  items(
    first: 20
    filter: {
      takenAt: {
        from: "2026-03-01T00:00:00Z"
        to: "2026-04-01T00:00:00Z"
      }
    }
  ) {
    totalCount
    nodes { id caption type provider takenAt }
  }
}

Example response:


{
  "data": {
    "items": {
      "totalCount": 47,
      "nodes": [
        {
          "id": "b5c2d3e4-f6a7-8901-bcde-fa2345678901",
          "caption": "March was all about this collection",
          "type": "POST",
          "provider": "INSTAGRAM",
          "takenAt": "2026-03-15T18:00:00Z"
        }
      ]
    }
  }
}

Using with AI:

“Show me all content from March 2026” “Find posts from the last 30 days” “List items from Q1 2026”

Combine with: provider, itemTypes, accountNames, viralityScore, engagement

By creator handle


query ItemsByCreator {
  items(
    first: 20
    filter: {
      accountNames: ["lauramendez"]
    }
  ) {
    totalCount
    nodes { id caption type provider takenAt }
  }
}

Example response:


{
  "data": {
    "items": {
      "totalCount": 8,
      "nodes": [
        {
          "id": "a4b1c2d3-e5f6-7890-abcd-ef1234567890",
          "caption": "Summer linen set — obsessed with this look for travel",
          "type": "REEL",
          "provider": "INSTAGRAM",
          "takenAt": "2026-03-28T14:30:00Z"
        }
      ]
    }
  }
}

Using with AI:

“Show me all content from @lauramendez” “List posts from creators lauramendez and tomaszwski.fit”

Combine with: provider, itemTypes, takenAt, sorting (to rank by engagement), engagement

By hashtag or mention


query ItemsByHashtag {
  items(
    first: 20
    filter: {
      tagsNames: ["nycfoodie"]
    }
  ) {
    totalCount
    nodes { id caption type provider takenAt }
  }
}

Example response:


{
  "data": {
    "items": {
      "totalCount": 4,
      "nodes": [
        {
          "id": "c6d3e4f5-a7b8-9012-cdef-ab3456789012",
          "caption": "Asian inspired food at this amazing NYC spot",
          "type": "POST",
          "provider": "INSTAGRAM",
          "takenAt": "2026-03-16T04:40:00Z"
        }
      ]
    }
  }
}

Using with AI:

“Find all posts with the hashtag #nycfoodie” “Show me content that mentions our brand”

Combine with: provider, itemTypes, takenAt, accountNames, sorting

By follower count range


query ItemsByFollowers {
  items(
    first: 20
    filter: {
      followersCount: { from: 100000, to: 500000 }
    }
  ) {
    totalCount
    nodes {
      id type provider
      socialProfile { accountName followers }
    }
  }
}

Example response:


{
  "data": {
    "items": {
      "totalCount": 16,
      "nodes": [
        {
          "id": "d7e4f5a6-b8c9-0123-defa-bc4567890123",
          "type": "REEL",
          "provider": "INSTAGRAM",
          "socialProfile": {
            "accountName": "lauramendez",
            "followers": 312000
          }
        }
      ]
    }
  }
}

Using with AI:

“Show me content from creators with 100K to 500K followers” “Find UGC from micro-influencers (under 50K followers)”

Combine with: provider, itemTypes, takenAt, verified, creatorLocation

By engagement range

Filter items where a specific engagement metric falls within a range:


query HighEngagement {
  items(
    first: 20
    filter: {
      engagement: [
        { field: LIKE_COUNT, range: { from: 100, to: 50000 } }
      ]
    }
  ) {
    totalCount
    nodes {
      id type provider
      currentEngagement { likes comments views }
      socialProfile { accountName }
    }
  }
}

Example response:


{
  "data": {
    "items": {
      "totalCount": 48,
      "nodes": [
        {
          "id": "a4b1c2d3-e5f6-7890-abcd-ef1234567890",
          "type": "POST",
          "provider": "INSTAGRAM",
          "currentEngagement": {
            "likes": "3728",
            "comments": "70",
            "views": null
          },
          "socialProfile": { "accountName": "lauramendez" }
        }
      ]
    }
  }
}

Available engagement fields: LIKE_COUNT, COMMENT_COUNT, MERGED_VIEW_PLAY_COUNT, SHARE_COUNT, ENGAGEMENTS_RATE, IMPRESSIONS_RATE, EARNED_MEDIA_VALUE

Using with AI:

“Find posts with more than 1000 likes” “Show me content with EMV between 500 and 10000” “Find all posts with high engagement rate”

Combine with: provider, itemTypes, takenAt, accountNames, followersCount, sorting

By creator location

Filter items based on the creator’s profile location:


query ItemsByCreatorLocation {
  items(
    first: 20
    filter: {
      creatorLocation: { query: "New York" }
    }
  ) {
    totalCount
    nodes {
      id type provider caption
      socialProfile { accountName }
    }
  }
}

Example response:


{
  "data": {
    "items": {
      "totalCount": 8,
      "nodes": [
        {
          "id": "a4b1c2d3-e5f6-7890-abcd-ef1234567890",
          "type": "REEL",
          "provider": "INSTAGRAM",
          "caption": "NYC vibes this weekend",
          "socialProfile": { "accountName": "lauramendez" }
        }
      ]
    }
  }
}

You can also use ugcLocation to filter by the location tagged on the content itself (instead of the creator’s profile location).

Using with AI:

“Show me content from creators based in New York” “Find UGC from creators located in France” “Filter items by content location tagged in Los Angeles”

Combine with: provider, itemTypes, takenAt, followersCount, accountNames

By usage rights status


query ApprovedUsageRights {
  items(
    first: 20
    filter: {
      usageRightsStatus: [APPROVED]
    }
  ) {
    totalCount
    nodes { id type provider caption }
  }
}

Statuses: APPROVED, EXPIRED, IN_QUEUE, REJECTED, REQUESTED

Separate filters are also available for tiktokSparkCodeStatus and instagramWhitelistingStatus.

Using with AI:

“Show me all content with approved usage rights” “Find items where usage rights are still pending” “List content with expired usage rights”

Combine with: provider, itemTypes, takenAt, accountNames, tiktokSparkCodeStatus, instagramWhitelistingStatus

Use a saved preset (Content Views and Collections)

The presetId parameter lets you query items from a Content View or a Collection you’ve already created in the Archive UI — without having to rebuild the filters each time.

Content Views (accessor: MEDIA_DECK) are dynamic saved filters that update automatically as new content comes in
Collections (accessor: COLLECTIONS) are static groups of items you’ve manually curated

Both share the same presetId parameter in the items query. Get your IDs from the filterPresets query:


query ListPresets {
  filterPresets {
    id
    name
    accessor
  }
}

Then use the ID in your items query:


query ItemsByPreset {
  items(first: 20, presetId: "your-preset-id") {
    totalCount
    nodes { id caption type provider takenAt }
  }
}

When using presetId, any filter parameters you pass are ignored — only sorting works on top of a preset. See Content Views and Collections for more.

Using with AI:

“Show me all items in my ‘Unboxing’ Content View” “Fetch items from my ‘Q1 Campaign Content’ collection”

Sorting items

Use sorting to order results. Combine with any filter:


query MostLiked {
  items(
    first: 10
    sorting: { sortKey: LIKE_COUNT, sortOrder: DESC }
  ) {
    nodes {
      id caption type provider
      currentEngagement { likes views }
      socialProfile { accountName }
    }
  }
}

Example response:


{
  "data": {
    "items": {
      "nodes": [
        {
          "id": "e8f5a6b7-c9d0-1234-efab-cd5678901234",
          "caption": "Can't get enough of this look",
          "type": "POST",
          "provider": "INSTAGRAM",
          "currentEngagement": {
            "likes": "21390",
            "views": null
          },
          "socialProfile": {
            "accountName": "lauramendez"
          }
        }
      ]
    }
  }
}

Available sort keys

Key	Description	Example use
`TAKEN_AT`	Publication date (default)	Latest content first
`LIKE_COUNT`	Most liked	Top performing content
`COMMENT_COUNT`	Most commented	Most discussed content
`SHARE_COUNT`	Most shared	Most viral on TikTok
`MERGED_VIEW_PLAY_COUNT`	Most viewed/played	Highest reach
`EARNED_MEDIA_VALUE`	Highest EMV	Best ROI content
`LINEAR_VIRALITY`	Linear virality score	Trending content
`EXPONENTIAL_VIRALITY`	Exponential virality score	Fast-growing content
`FOLLOWERS_COUNT`	Creator’s follower count	Content from biggest creators first
`ACCOUNT_NAME`	Alphabetical by account name	Ordered by creator handle

Query examples:


# Top 10 most liked posts
query TopLiked {
  items(first: 10, sorting: { sortKey: LIKE_COUNT, sortOrder: DESC }) {
    nodes { id caption provider currentEngagement { likes } socialProfile { accountName } }
  }
}


# Highest EMV content this month
query HighestEMV {
  items(
    first: 10
    filter: { takenAt: { from: "2026-04-01T00:00:00Z", to: "2026-04-30T23:59:59Z" } }
    sorting: { sortKey: EARNED_MEDIA_VALUE, sortOrder: DESC }
  ) {
    nodes { id caption provider currentEngagement { earnedMediaValue } socialProfile { accountName followers } }
  }
}


# Most viewed Reels — combine sorting with a filter
query MostViewedReels {
  items(
    first: 10
    filter: { provider: INSTAGRAM, itemTypes: [REEL] }
    sorting: { sortKey: MERGED_VIEW_PLAY_COUNT, sortOrder: DESC }
  ) {
    nodes { id caption currentEngagement { views impressions } socialProfile { accountName } }
  }
}


# Oldest content first (ascending)
query OldestFirst {
  items(first: 20, sorting: { sortKey: TAKEN_AT, sortOrder: ASC }) {
    nodes { id caption takenAt provider }
  }
}

Using with AI:

“Show me the top 10 most liked posts” “What’s our highest EMV content this month?” “Rank content by views” “Show me the most shared TikTok videos from the last 30 days”

Note: The sortKey and sortOrder fields are required. The official API docs contain a typo using direction instead of sortOrder — use sortOrder as shown in the examples above.

Search content semantically

This section exposes Super Search — Archive’s AI-powered search that understands images and text the way people do. Instead of matching exact keywords, it analyzes content using meaning-based matching and finds the most relevant UGC in your library.

Learn more: All About Super Search

Three search modes:

Mode	What it searches	Example query
`FUZZY_CAPTION`	Post caption text	`"summer travel outfit"`
`FUZZY_TRANSCRIPTION`	Video transcription text	`"discount code"`
`EMBEDDING_CONTENT`	Visual/semantic similarity	`"people unboxing products"`, or visually similar to another item

Note on EMBEDDING_CONTENT result count: When using visual search mode, the result count always shows 1,250 — this is a built-in cap on how many results the search engine surfaces at once, not a count of exact matches. FUZZY_CAPTION and FUZZY_TRANSCRIPTION return exact match counts.


query SemanticSearch {
  items(
    first: 10
    filter: {
      superSearch: {
        searchQuery: "summer travel outfit"
        mode: FUZZY_CAPTION
      }
    }
  ) {
    nodes { id caption provider takenAt }
  }
}

Modes:

FUZZY_CAPTION — search caption text
FUZZY_TRANSCRIPTION — search video transcriptions
EMBEDDING_CONTENT — semantic/visual similarity

Visual search parameters (use with EMBEDDING_CONTENT):

Parameter	Description
`similarMediaContentId`	Find content visually similar to an existing archived item
`imageUrl`	Find content visually similar to an external image URL
`fileName`	Find content by uploaded file name


query VisualSearch {
  items(
    first: 10
    filter: {
      superSearch: {
        similarMediaContentId: "9182736"
        mode: EMBEDDING_CONTENT
      }
    }
  ) {
    nodes { id caption provider takenAt }
  }
}

Using with AI:

“Find all content where creators talk about summer travel outfits” “Search for videos where creators mention a discount code” “Find content visually similar to this post”

Find item IDs from URLs

If you have post URLs and need the Archive item IDs, use the itemIdsByUrl query. This is useful when you’re tracking posts in a spreadsheet or external system by URL.

Supported URL formats:

Instagram Posts (instagram.com/p/...)
Instagram Reels (instagram.com/reel/...)
TikTok Videos (tiktok.com/@handle/video/...)
YouTube Videos (youtube.com/watch?v=...)
YouTube Shorts (youtube.com/shorts/...)

Not supported: Instagram Stories do not have permanent URLs (they expire after 24 hours), so URL lookup is not available for Stories.


query LookupByUrl {
  itemIdsByUrl(urls: [
    "https://instagram.com/p/DRyckrbDdWw",
    "https://www.tiktok.com/@handle/video/7630795555001683222",
    "https://www.youtube.com/watch?v=abc123"
  ]) {
    url
    status
    itemId
  }
}

Example response:


{
  "data": {
    "itemIdsByUrl": [
      {
        "url": "https://instagram.com/p/DRyckrbDdWw",
        "status": "FOUND",
        "itemId": "6fa002d2-f89e-4310-98db-d0bbfeb7180f"
      },
      {
        "url": "https://instagram.com/reel/ABC123",
        "status": "NOT_FOUND",
        "itemId": null
      }
    ]
  }
}

Statuses:

FOUND — the URL matched an item in your workspace
NOT_FOUND — no matching item found (the content may not be tracked in your workspace)
INVALID_URL — the URL format is not recognized

You can pass multiple URLs in a single request. Once you have the item IDs, use them with other queries like engagementHistory, mediaContents, or addItemToCollections.

Using with AI:

“Look up these Instagram URLs and tell me their Archive item IDs” “Find the item ID for this Instagram post: https://instagram.com/p/ABC123 ”

Metrics by content type

Not all metrics are available for every content type. Some fields will return null depending on the platform and format:

Metric	Instagram Stories	Instagram Posts	Instagram Reels	TikTok Videos	YouTube Videos/Shorts
`likes`	—	Yes	Yes	Yes	—
`comments`	—	Yes	Yes	Yes	—
`shares`	—	—	—	Yes	—
`views`	Est. Views	Est. Views	Yes	Yes	Yes
`impressions`	Est.	Est.	Yes	Yes	Yes
`earnedMediaValue`	Yes	Yes	Yes	Yes	—
`linearViralityScore`	—	—	Yes	Yes	—

Est. Views / Est. Impressions: For Stories and Feed Posts, views and impressions are estimated based on historical data and follower count — they are not platform-reported. For Reels, TikTok, and YouTube, these numbers come directly from the platform.

EMV (Earned Media Value): Returned in cents. A value of "12300" means $123.00. Divide by 100 to get the dollar amount.

Virality Score: Only available for Reels and TikTok videos. Values: HIGH, MEDIUM, LOW, NOT_VIRAL. First available approximately 2 hours after content is detected.

Get media files

items vs mediaContents: The items query returns metadata — caption, engagement, dates, creator info, and a link to the original post on the platform. It does not return the actual media file. Use mediaContents when you need the hosted file URL (for download, display, or processing) — it returns the CDN-hosted video or image file, thumbnail, dimensions, and duration.


query GetMediaFiles {
  mediaContents(itemIds: ["a4b1c2d3-e5f6-7890-abcd-ef1234567890"]) {
    ... on Image {
      id
      mediaItemId
      fileUrl
      thumbnailUrl
      width
      height
      deleted
      type
    }
    ... on Video {
      id
      mediaItemId
      fileUrl
      thumbnailUrl
      videoDuration
      width
      height
      deleted
      type
    }
  }
}

Example response:


{
  "data": {
    "mediaContents": [
      {
        "id": "9182736",
        "fileUrl": "https://cdn.archive.com/media/2026/03/28/reel-lauramendez.mp4",
        "thumbnailUrl": "https://cdn.archive.com/media/2026/03/28/reel-lauramendez-thumb.jpg",
        "videoDuration": 27,
        "width": 1080,
        "height": 1920,
        "deleted": false,
        "type": "VIDEO"
      }
    ]
  }
}

Always check deleted before using a URL — when deleted is true, both fileUrl and thumbnailUrl will be null.

mediaItemId is the identifier of the parent media item. Use it to group related content (e.g., carousel frames from the same post) that share the same mediaItemId.

Using with AI:

“Get me the video file URL for this item” “Fetch the thumbnail for these 5 items”

Get transcriptions

Learn more: All About Post Summaries

The transcriptions query accepts two different types of ID — you only need to use one:

itemIds (up to 1,000) — pass the item ID (the post or video). The most common approach. Archive looks up the associated media file and returns the transcript.
mediaContentIds (up to 20) — pass the media file ID returned by mediaContents. Use this when you’ve already queried mediaContents and have the file IDs, or when a single item has multiple files (e.g. a carousel with several images) and you want the transcript for a specific file.

The limit is lower for mediaContentIds because it’s a more granular lookup. For most use cases, itemIds is the right choice.

You can get transcriptions in two ways: as a separate query, or inline within an items query using the transcriptions field (see the List recent items example).

By item IDs (up to 1,000)


query GetTranscriptions {
  transcriptions(itemIds: ["a4b1c2d3-e5f6-7890-abcd-ef1234567890"]) {
    mediaContentId
    transcript
  }
}

By media content IDs (up to 20)

If you already have media content IDs from a mediaContents query, you can use those directly:


query GetTranscriptionsByMediaId {
  transcriptions(mediaContentIds: ["9182736", "9182737"]) {
    mediaContentId
    transcript
  }
}

Example response:


{
  "data": {
    "transcriptions": [
      {
        "mediaContentId": "9182736",
        "transcript": "Okay so I finally got my hands on this linen set and honestly I don't think I've taken it off since. It's so breathable, great for travel, and the fit is just perfect. I'm wearing size small. Use my code LAURA15 for fifteen percent off, link in bio."
      }
    ]
  }
}

Items without a transcription are absent from the result. You can pass up to 1,000 itemIds or up to 20 mediaContentIds per request.

Using with AI:

“Get the transcript for this video” “Find all videos where creators mention a discount code and show me the transcripts”

Get engagement history

Note: engagementHistory is a top-level query that takes an itemId as a parameter — it is not a subfield of an item. You call it separately after getting the item ID.

Track how a post’s engagement metrics evolved over time. Learn more: Understanding Engagement Rate

Engagement snapshots are not real-time. Archive captures metrics at approximately 2 hours, 24 hours, 3 days, and 7 days after publication. After 7 days, updates slow down significantly and only occur if the post continues to receive high engagement. Numbers may differ from what you see on the platform.

You can optionally filter by date range using filter: { capturedAt: { from, to } }.

All available fields on each snapshot:

Field	Type	Description
`at`	DateTime	Timestamp of the snapshot
`likes`	BigInt (string)	Likes at this point in time
`comments`	BigInt (string)	Comments at this point in time
`shares`	BigInt (string)	Shares at this point in time (TikTok only)
`views`	BigInt (string)	Views at this point in time
`impressions`	BigInt (string)	Views, plays, or estimated impressions
`earnedMediaValue`	BigInt (string)	EMV in cents — divide by 100 for dollars
`followers`	BigInt (string)	Creator’s follower count at capture time (historical snapshot, not current)
`linearViralityScore`	Enum	Virality: `HIGH`, `MEDIUM`, `LOW`, `NOT_VIRAL`


query GetEngagementHistory {
  engagementHistory(itemId: "a4b1c2d3-e5f6-7890-abcd-ef1234567890", first: 5) {
    totalCount
    nodes {
      at
      likes
      comments
      shares
      views
      impressions
      earnedMediaValue
      followers
      linearViralityScore
    }
    pageInfo { hasNextPage endCursor }
  }
}

Example response:


{
  "data": {
    "engagementHistory": {
      "totalCount": 12,
      "pageInfo": { "hasNextPage": true, "endCursor": "eyJpZCI6Ii4uLiJ9" },
      "nodes": [
        {
          "at": "2026-03-29T08:00:00Z",
          "likes": "9840",
          "comments": "241",
          "views": "110500",
          "impressions": "110500",
          "earnedMediaValue": "14200",
          "followers": "312000",
          "linearViralityScore": "MEDIUM"
        },
        {
          "at": "2026-03-28T20:00:00Z",
          "likes": "7210",
          "comments": "198",
          "views": "94000",
          "impressions": "94000",
          "earnedMediaValue": "12300",
          "followers": "312000",
          "linearViralityScore": "NOT_VIRAL"
        }
      ]
    }
  }
}

linearViralityScore values: HIGH (view-to-follower ratio ≥4.0), MEDIUM (2.0–4.0), LOW (1.0–2.0), NOT_VIRAL (below 1.0)

Using with AI:

“Show me how this post’s likes and views grew over the past week” “What was the earned media value of this item on March 28th?” “Track the performance of our top 5 posts from last month”

For queries that return many results, the API delivers them in pages. See Pagination to learn how to navigate through all your data.

Items (UGC)

All available item fields

Query items

List recent items

Filtering items

All filter options

By platform and content type

By date range

By creator handle

By hashtag or mention

By follower count range

By engagement range

By creator location

By usage rights status

Use a saved preset (Content Views and Collections)

Sorting items

Available sort keys

Search content semantically

Find item IDs from URLs

Metrics by content type

Get media files

Get transcriptions

By item IDs (up to 1,000)

By media content IDs (up to 20)

Get engagement history