Common Workflows

Real-world examples of what you can do with the Archive API. These workflows combine multiple queries and mutations to accomplish common tasks.

Using with AI: Each workflow includes example prompts you can use with Claude. If you’ve set up the AI System Prompt, Claude can execute these workflows for you automatically.

Look up items by URL

If you have a spreadsheet or list of post URLs and need to work with them in the API, use itemIdsByUrl to translate them into Archive item IDs. Supports Instagram, TikTok, and YouTube.

Ask Claude:

“Here are 10 Instagram URLs — look them up and give me their engagement data” “Look up these TikTok URLs and add the matching items to my collection”

How it works:

Step 1 — Translate URLs to item IDs:


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

Step 2 — Use the returned item IDs with any other query (engagement history, media files, add to collection, etc.)

This is especially useful for teams that track content in spreadsheets by URL rather than by Archive item ID. Not supported for Stories (no permanent URL).

Using with AI: You can’t get engagement history in a single query — the API always requires two steps (URL → item ID → history). But if you ask Claude, it handles both steps automatically. Just say: “Get the engagement history for these URLs: [paste URLs]” and Claude will look up the IDs and fetch the history for each one.

Pull engagement history for all items in a Content View

Get the historical engagement data for every item in a saved view — useful for building performance reports over time.

Ask Claude:

“Pull the engagement history for all items in my ‘Influencer-Generated Content’ view and show me how likes and views grew over time” “Give me a performance timeline for every post in my ‘Unboxing’ view”

How it works:

Step 1 — Get all item IDs from the view:


query ViewItems {
  items(first: 100, presetId: "your-view-id") {
    nodes {
      id
      caption
      takenAt
      socialProfile { accountName }
    }
    pageInfo { hasNextPage endCursor }
  }
}

Step 2 — For each item, pull its engagement history:


query ItemEngagement {
  engagementHistory(itemId: "item-id-here", first: 50) {
    nodes {
      at
      likes
      comments
      shares
      views
      impressions
      earnedMediaValue
      followers
      linearViralityScore
    }
  }
}

You can also filter the engagement history by date range: filter: { capturedAt: { from: "2026-03-01T00:00:00Z", to: "2026-04-01T00:00:00Z" } }

Note: engagementHistory only accepts one itemId at a time. Claude will loop through all items automatically and compile the results.

Pull engagement history for all items in a Collection

Same as above, but using a collection instead of a view.

Ask Claude:

“Pull the engagement history for everything in my ‘Q1 Campaign Content’ collection” “Show me a day-by-day breakdown of likes for all posts in my ‘Best of March’ collection”

How it works:

Step 1 — Get all item IDs from the collection:


query CollectionItems {
  items(first: 100, presetId: "your-collection-id") {
    nodes {
      id
      caption
      takenAt
      socialProfile { accountName }
    }
    pageInfo { hasNextPage endCursor }
  }
}

Step 2 — Same as above: call engagementHistory for each item.

Tip: When asking Claude, you can request specific analysis like “total EMV growth over time”, “which post had the fastest growth in the first 7 days”, or “compare engagement velocity across creators”. Claude will fetch the data and calculate it for you.

Move all items from a Content View to a Collection

This is useful when you need content in a Collection for features like Reports that don’t support filtering by Content Views or Magic Fields.

The workflow:

Fetch all item IDs from the Content View using presetId + pagination
For each item, run addItemToCollections to add it to the target collection

Ask Claude:

“Get all items from my ‘Influencer-Generated Content’ view and add them to a collection called ‘Q1 Report’”

How it works behind the scenes:

Step 1 — Fetch items from the view (repeat until hasNextPage is false):


query FetchViewItems {
  items(first: 100, presetId: "your-view-id") {
    nodes { id }
    pageInfo { hasNextPage endCursor }
  }
}

Step 2 — Add each item to the collection:


mutation AddToCollection {
  addItemToCollections(
    itemId: "item-id-here"
    collectionNames: ["Q1 Report"]
    autoCreate: true
  ) {
    item { id }
    userErrors { field message }
  }
}

Note: The API only supports adding items one at a time — there is no bulk mutation. For large volumes (thousands of items), this requires scripting a loop. Claude can handle this automatically — it will paginate through all items and add each one sequentially.

Scale: We’ve tested this workflow with 14,000+ items without encountering rate limits or errors.

Export data as CSV

The Archive API doesn’t have a native CSV export endpoint — but you can build one by querying the API and formatting the results. If you’re using Claude, it can handle the full workflow automatically.

Ask Claude:

“Export all creators with their name, email, Instagram handle, and follower count as a CSV” “Create a CSV with all items from my ‘Q1 Campaign’ collection including caption, post date, likes, views, and EMV” “Export the engagement history for all posts in my ‘Unboxing’ view as a CSV”

What Claude does behind the scenes:

Queries the API (paginating through all results automatically)
Extracts the fields you asked for
Generates a CSV file you can download or copy

Example — Export creators:


query ExportCreators {
  creators(first: 100) {
    nodes {
      id
      customAttributes
      socialProfiles {
        accountName
        provider
        followers
      }
    }
    pageInfo { hasNextPage endCursor }
    totalCount
  }
}

Example — Export items from a collection with engagement:


query ExportCollectionItems {
  items(first: 100, presetId: "your-collection-id") {
    nodes {
      id
      caption
      type
      provider
      takenAt
      originalUrl
      currentEngagement {
        likes
        comments
        shares
        views
        earnedMediaValue
      }
      socialProfile { accountName followers }
    }
    pageInfo { hasNextPage endCursor }
  }
}

Tip: You can combine any query with a CSV export. Just tell Claude what fields you want and from which data source (all creators, a specific view, a collection, filtered items, etc.). Remember that EMV values in the CSV will be in cents — ask Claude to convert to dollars if needed.

Find top-performing content from a specific creator

Ask Claude:

“Show me the top 10 posts from @lauramendez sorted by likes, with engagement data”

How it works:


query TopContent {
  items(
    first: 10
    filter: { accountNames: ["lauramendez"] }
    sorting: { sortKey: LIKE_COUNT, sortOrder: DESC }
  ) {
    nodes {
      id
      caption
      type
      provider
      takenAt
      currentEngagement {
        likes
        comments
        shares
        views
        earnedMediaValue
      }
    }
  }
}

Get a performance summary for a Content View

Pull all items from a view and calculate aggregate metrics.

Ask Claude:

“Give me a performance summary of my ‘Unboxing’ view — total items, total likes, average EMV, top 5 posts”

Claude will:

Fetch all items from the view using pagination
Calculate totals and averages from the engagement data
Remember that EMV is in cents and convert to dollars
Present a clean summary

Find creators by location and export their profiles

Ask Claude:

“Find all creators based in the United States and show me their name, email, Instagram handle, and follower count”

How it works:


query CreatorsByLocation {
  creators(
    first: 100
    customAttributeConditions: [
      { field: "location", operator: CONTAINS, type: TEXT, value: "United States" }
    ]
  ) {
    nodes {
      id
      customAttributes
      socialProfiles {
        accountName
        provider
        followers
      }
    }
    pageInfo { hasNextPage endCursor }
    totalCount
  }
}

Compare engagement across content types

Ask Claude:

“Compare the average likes and EMV for Instagram Reels vs TikTok videos in my workspace this quarter”

Claude will:

Query items filtered by provider: INSTAGRAM, itemTypes: [REEL] with a date range
Query items filtered by provider: TIKTOK with the same date range
Calculate averages for each
Present a comparison

Good to know

No bulk mutations: The API adds/removes items from collections one at a time. For large operations, Claude will loop through items automatically.
Workspace search: The workspaces query doesn’t support filtering by name — it only supports pagination. If you have access to many workspaces, ask Claude to search through all pages for the one you need.
Content Views are read-only: You can read items from a view, but you can’t create or modify views via the API. Use the Archive UI for that.