Split overloaded projects into product, country, and workflow tags without losing project membership.
Projects helped teams organize reporting before tags existed. Many teams used project names for more than one thing at once: product, market, creator cohort, campaign, video hook, or channel. Tags let you split those meanings into separate labels and reuse them across analytics, accounts, videos, and automation.
This guide is for teams that already have projects and want to migrate them carefully. Read more about tags in general here instead.
Set up the MCP, paste the prompt, review the proposed tag map, and approve writes only when the plan looks right.
See which project filters and assignment endpoints are being replaced by tag filters and account-level tag assignments.
Already today, without migrating anything, you can keep using your existing projects as "virtual tags" and continue filtering by them in the UI (API must be updated, see below). But we still recommend migrating them as actual custom & country tags for two reasons:
Soon, Projects will become Products being intentional wrappers for commercial entities.
Projects have historically been used for multiple purposes, due to the lack of alternative, so migrating them to tags will help you better organize your data.
Example: Project AppName · Hook A · Italy is being split into one product AppName, one
custom tag Hook A, and one country tag 🇮🇹 Italy. The prompt below will convert this
automatically for you and preserves all existing account assignments.
Migrating country information from plain text into structured data via tags (e.g. 🇮🇹 Italy)
allows us to render interesting geo-based visualizations and insights in the UI.
For automated migration, we provide a simple prompt that uses your agent to plan and split up your projects into tags. You can use any agent with MCP-compatabilty, but we've made best setup experience using Codex.
In the dashboard, go to API & Automation, open Agents, and pick the MCP setup instructions for the agent you use.
Follow the install or OAuth steps shown in Agent settings so your agent can read tags, projects, and tracked account assignments.
Paste the prompt from this page into a new agent chat. It asks the agent to inspect your current setup and stop with a concise plan.
Check reused tag IDs, tags to create, descriptions to port, project-to-tag mappings, and country system tags before approving anything.
After you approve the plan, let the agent create missing org tags and add account-level tag assignments to the same tracked accounts.
Open Tags and your analytics filters to confirm the new tag combinations work. The original virtual project tags remain available for comparison.
With the viral.app MCP, plan migrating my projects/products into tags.
Only keep/create product tags for actual apps/sites/brands, without extra properties in the product tag name. Split extra properties into separate tags. Also detect and assign country tags, which already exist as system tags.
Projects/products already have respective virtual project/product tags, and those virtual tags are assigned via account-level tag assignments equivalent to the previous project tracked account assignments.
DO NOT modify anything yet. First read the existing tag inventory with `viral_app.list_tags` across `system`, `org`, and `project` scopes, plus current projects/products and tracked account assignments. Present a final concise plan before any writes, including exactly which tags would be reused or created, tag IDs for reused tags, which project/product descriptions would be ported to created tags, and which projects/products map to which tags. I need to approve or modify the plan before any writes.
**Examples**
1. Project/Product `ProductName - Ambassadors - Italy` will:
- Check whether `ProductName` and `Ambassadors` tags exist; create them only if missing.
- Assign `ProductName` and `Ambassadors` to the same accounts via account-level tag assignments, not single-video assignments.
- Assign the already existing `Italy` country system tag to the same accounts via account-level tag assignments.
- If the project/product has a description, port that description to the most directly corresponding created org tag.
2. Project/Product `ITA` will:
- Assign only the already existing `Italy` country system tag to the same accounts via account-level tag assignments.
**Notes**
- “Projects” may already be renamed to “Products”.
- Use `viral_app.list_tags` as the source of truth for existing tags. Org-scope tags are manually created tags; project-scope tags are virtual project/product tags; system-scope country tags must be reused, never created.
- Traditional assign/unassign project endpoints will be deprecated in favor of existing virtual project tag account-level assignments.
- Use account-level tag assignment tools only after approval; do not use single-video tag assignment tools for this migration.
- Never create `All` tags for projects/products because the virtual project tag itself already represents that implicitly.
- Never create country tags. Reuse existing country system tags only.
- Avoid creating broad rollup tags such as `World` unless they represent a real product/app/site/brand. If a `WORLD` project/product is only a legacy rollup, migrate its accounts into the underlying product/channel/country tags instead and omit `World`.
- Do not silently omit ambiguous rollup/container projects/products. If a project/product is not clearly an app/site/brand but has current account assignments, include it in the plan as an explicit approval decision: either create a normalized non-product tag for it, map it to underlying product/channel/country tags, or omit it.
- Prefer deriving broad groupings like “all countries except X/Y” through filters instead of creating rollup tags.
- If applicable, normalize casing, spacing, punctuation, and obvious typos conservatively before deciding final tag names. Treat casing variants as the same tag unless there is strong evidence the casing is intentional brand styling. Prefer normal title/brand casing over all-caps legacy project names; e.g. "PRODUCT" and "Product Ambassadors" should both map to product tag "Product" (with respective virtual tag), not separate "PRODUCT" and "Product" tags. Keep intentional brand casing such as ProductNameLabs when it appears deliberate.
- Try to distinguish products/projects from video hooks/types, where the latter should become tags.
- Try reducing single API/MCP calls (e.g. by increasing page sizes where possible) to prevent rate limiting and improve performance.
Before approving writes, check that the plan lists every existing project or product with current account assignments. It should say which existing tags will be reused, which org tags will be created, which descriptions will be copied, and which account-level assignments will be added.
After approval, the migration should create only missing org tags, reuse system country tags, and add account-level tag assignments to the same tracked accounts. Your virtual project or product tags remain available, so you can compare the old grouping with the new tag combinations while your team updates reports and automations.
Open Tags to start fine-tuning yourself.
Project-based filters are deprecated for analytics, listing, and export endpoints. Use tag filters instead. When you need the old project or product membership, use the corresponding virtual project tag ID as a tag filter.
The deprecated surface is precisely the project filter parameters and the project assignment endpoints listed below — expand[]=projects and projects fields in responses are not deprecated (they change later with the Products rename). Every deprecated endpoint and parameter is marked in the API reference, deprecated endpoints additionally return RFC 9745 Deprecation and Link response headers, and organizations whose API keys keep calling deprecated surface receive at most one warning email per week, summarizing every affected key.
The project assignment mutation endpoints are also deprecated:
POST /api/v1/projects/{projectId}/accounts/{accountId} to add one account to a project.DELETE /api/v1/projects/{projectId}/accounts/{accountId} to remove one account from a project.POST /api/v1/projects/{projectId}/accounts/bulk to add multiple accounts to a project.DELETE /api/v1/projects/{projectId}/accounts/bulk to remove multiple accounts from a project.PUT /api/v1/accounts/tracked/{accountId}/project-hashtags to update project hashtag filters.The legacy per-account hashtag filter is retired outright (September 2026). Every filter that existed on July 5 became a "Legacy hashtag filter" exclusion workflow; the old field no longer affects analytics, payouts, or exports, hashtagsFilter is no longer returned for tracked accounts, and both hashtag endpoints answer 410 Gone:
PUT /api/v1/accounts/tracked/{accountId}/hashtags to update the account hashtag filter. Replace it with a tag workflow ("Hashtags doesn't include …" plus the Excluded action, or a caption rule for creators who tag by mention).Use tag endpoints and account-level tag assignments instead:
For migrations, prefer account-level tag assignments. Do not use single-video tag assignment tools unless you are making a one-off per-video decision.
Soon, we'll be renaming Projects to Products across the platform. They will solely be wrappers for commercial entities (e.g. by connecting them to App Store revenue data). Though, the virtual tag concept (each product will have a virtual tag for filtering) will remain the same.