viral.app

Counts the organization's creator payouts by status (upcoming, due, canceled, paid). Cheap first call to answer 'do I owe anything?'.

get_payout_counts

Creates a brief from markdown (contentMarkdown) and returns its id. Optional: ordered sample videos from the organization's tracked videos, and who reads it — campaignIds to link (a campaign holds one brief, so linking moves it off any other brief), creatorIds to send it to creators directly (from list_creators), or allCreators=true for everyone at the organization (alone, never with campaigns or creators). Every creator it reaches must read it on their next visit. Viral-library videos are attached afterwards with add_brief_sample_videos. notify=true also notifies them (in the app and by email): only when the user asked for it. Show the user the full draft before calling.

create_brief

Creates a campaign from a spec: name, schedule (interval, intervalCount, anchor rolling|fixed, optional startsOn), videoTarget, optional briefId and payouts (fixedSalary, basePayouts, cpmPayouts, flatBonuses, performanceCap, eligibility). Amounts are major units (10 = 10.00); tiers are half-open [from, to). Returns the campaign with its sentences. Only after preview_campaign returned ok and the user saw its sentences; send exactly the spec it returned plus its previewHash — the call is refused without one (PREVIEW_REQUIRED) and on a mismatch. briefId attaches a brief (none by default).

create_campaign

Creates a creator in the organization (firstName, lastName, email). Optionally links tracked accounts (accountIds) and sends the invitation email in the same call (invite: true). Counts against the active-creators plan meter. ONBOARDING CHAIN: to also link social handles, first add_tracked_accounts(handles), then list_tracked_accounts to fetch the new orgacc_ ids (the add result does not include them), then pass those as accountIds here. Setting invite: true SENDS THE INVITATION EMAIL immediately — state the exact recipient email in your message before this call so the user approves knowingly.

create_creator

Creates a new organization tag.

create_tag

Creates a new tag workflow and, with `applyToPastVideos`, enqueues a one-time backfill over existing videos. Without it the workflow only sees videos that sync in afterwards. ⚠️ Consumes extra credits: 11 credits ($0.011) per evaluated video; cached evaluations are free. Metric workflows consume none, and a workflow created without a backfill consumes nothing up front.

create_tag_workflow

Permanently deletes a brief. Its audience links, sample references, and read receipts cascade; sample videos the brief created (and nothing else references) are untracked. Silent, like unlinking a campaign: the brief's audience is not notified.

delete_brief

Deletes one MCP event subscription (automation) by its id (`mcpsub_…`, from list_event_subscriptions): its events stop at once. You can delete your own; owners and admins any in the organization. Returns `deleted: false` when there is no such subscription you may delete.

delete_event_subscription

Deletes an organization tag. Refused with 400 while an active workflow still assigns the tag, and with 409 `CONFLICT` while a campaign's payout conditions (ended campaigns included) name it; `data.campaigns` lists those campaigns.

delete_tag

Deletes multiple organization tags. Tags still assigned by workflows, or named in a campaign's payout conditions (ended campaigns included), are skipped and reported in `blocked` with the reason.

delete_tags_bulk

Soft deletes a workflow. Applied tag assignments are kept unless deleteAssignments is set.

delete_tag_workflow

Clones an existing job posting into a new draft under a new title. The copy keeps the source configuration and always starts as a draft.

duplicate_job

Sets a campaign's end date on a cycle boundary: endBasis prev, current or next (the dates come from get_campaign_end_context), or custom with endDate. Assignments reaching past the end make the call fail unless the user consented to endAssignments (each moves to its last full period before the end) or revokeAssignments (rows that cannot keep one full period are deleted). Pass endAssignments / revokeAssignments only when the user chose them in the consent question. Without consent the call fails on assignments reaching past the end (ASSIGNMENTS_ACTIVE, ASSIGNMENTS_AFTER_END) — report that, do not retry with flags the user did not choose.

end_campaign

Library videos most similar to ONE viral-library video — same kind of app, format, hook and what happens on screen — ranked by the dossier embedding. Use the `id` from a search result as `videoId` when the user likes one example and wants more of that kind; for a fresh topic use search_viral_video_library instead.

find_similar_viral_videos

Retrieves a brief with its content (as TipTap JSON and as markdown), its audience, read progress, ordered sample videos, and how many creators a notify would reach right now.

get_brief

Lists the creators who read a brief: per creator the routes it reaches them through (campaign, sent directly, everyone), whether they read the current version, an earlier one, or not yet, and when they were last notified. Counts cover the whole audience; creators who have not joined the organization yet are only counted.

get_brief_read_status

Reads one campaign in full: its spec (the shape create_campaign and update_campaign take), one sentence per rule-set (summary), the sheet's alerts (specWarnings), the schedule fields locked by usage (lockedFields), and any advanced rules the spec cannot express. Read it before an edit and to answer how a campaign pays. Read it before update_campaign or end_campaign and whenever asked how a campaign pays; quote the summary sentences. rules is the engine's raw form — never show or edit it; advancedRules survive every update untouched and are not editable here.

get_campaign

Retrieves a single job posting of the current organization, including drafts and paused jobs.

get_job

Retrieves one application with the applicant's discovery profile, portfolio, challenge submissions, and social accounts. Contact details are only included once the application is accepted.

get_application

Returns the immutable engine breakdown snapshot recorded when the payout was issued, plus the invoiced line items. Cheap read — never re-runs the payout engine.

get_payout_breakdown

Get profile and lifetime analytics detail for a single tracked account by platform (tiktok | instagram | youtube | facebook | snapchat) and the platform's native account ID.

get_account

Get an aggregated time series (day/week/month buckets) of a tracked account's metrics: views, likes, comments, shares, bookmarks, posts, paid/organic views, engagement rate, and follower/following levels over time.

get_account_history

Get organization-wide KPI metrics (views, likes, comments, shares, engagement) across all tracked accounts and videos for a date range. Best first call for questions like 'how did we perform last week'. The `tags` filter accepts tag IDS only (orgtag_/orgproj_/systag_ from list_tags or resolve_tags). Plain tag NAMES are NOT resolved — unrecognized values are silently ignored and the result comes back UNFILTERED, so never pass names, and never present results as tag-filtered unless you passed real ids.

get_analytics_kpis

Preflight for assign_creators_to_campaign: the cycle start dates a fixed-anchor campaign offers behind startBasis prev, current and next (startOptions; a basis the assign would refuse is null, and the whole object is null for rolling campaigns, which start on a custom day), today, and per creator whether an archived status or a running or scheduled assignment already blocks the assign (blockedBy) and which campaign they are on. Read it before assign_creators_to_campaign. Fixed campaigns: when today is the cycle's first day use startBasis current without asking; mid-cycle ask the user today vs current vs next in one question showing the three dates — today joins mid-period (the running cycle becomes the first period, starting today, a fixed salary in it paid pro rata), current backdates to the cycle's start and pays it in full, next waits for the boundary; a basis the preflight returns as null would fail (before the campaign starts, or past its end date), so never offer it. Rolling campaigns: startBasis custom with startDate today unless the user names a day. Creators with blockedBy set cannot be assigned — say which and why (archived ones need unarchiving in the app); switching or unassigning is done in the app. blockedBy payout_hold on every creator means hiring is on hold until the organization's overdue creator payouts are settled — point to the Payouts page instead of retrying.

get_assignment_options

Creator-hub performance KPIs: campaign views (views gained by videos posted while the creator was assigned, counted for as long as the assignment lasts — no video-age window), posted and eligible videos, paid + projected spend, and effective/paid CPM. Monetary values are converted into the returned display currency (the campaign currency for a single-campaign scope, otherwise the organization default). Filter by campaignIds and/or creatorIds; scope 'dateRange' also returns a previous-period comparison. THE source for 'how is campaign X performing?'.

get_campaign_kpis

Per-creator activity rows for creator-hub campaigns: current billing-period progress with a pace status (onSchedule/runningTight/overdue), date-range-normalized targets, and recent 14-day posting. Filter by pace bucket (all/onSchedule/behindSchedule — behindSchedule groups runningTight and overdue) to answer 'which creators are behind?'.

get_campaign_activity

Preflight for end_campaign: the campaign's validity span, the cycle-aligned end dates behind endBasis prev, current and next (cycleEnds), and every assignment with its validity, the creator's latest settled payout window and whether settled payouts overlap it — what an end date would cut off. Read it before end_campaign. Offer cycleEnds.current and cycleEnds.next as the end date (never invent one) and, when assignments reach past the chosen end, ask the user in ONE question for consent to endAssignments and/or revokeAssignments — naming the creators — before calling end_campaign.

get_campaign_end_context

Full detail for one creator (id from list_creators): user/contact info, invitation status, linked social accounts, and profile. Use for follow-ups after payout, campaign, or performance questions.

get_creator

Get an aggregated time series (day/week/month buckets) of a creator's metrics summed across all of the creator's assigned accounts: views, likes, comments, shares, bookmarks, posts, paid/organic views, engagement rate, and follower/following levels over time.

get_creator_history

Usage vs included quota for one plan meter: eventName is one of 'tracked_videos', 'tracked_accounts', 'active_creators', 'creator_invites_daily', 'active_jobs', 'team_seats', 'extra_credits'. Answers 'how much of my plan am I using?', 'how many creators can I still invite today?' and 'how many credits are left?' for any member.

get_usage_meter

The organization's current subscription: plan/product, status, billing period, and included benefits. Admin/owner only — other roles get a permission error; use get_usage_meter for usage counters available to every member.

get_plan_usage

Get the organization's top performing tracked social accounts for a date range, ranked by metric gains. Metric semantics: plain metrics (viewCount, likeCount, …) rank by LIFETIME totals and surface old evergreen content. When the user asks about a time window ('last 30 days', 'this week'), rank by the matching *InPeriod metric (e.g. viewCountInPeriod) — the dateRange alone does NOT change the ranking. Every result row already contains both lifetime and in-period numbers, so do not re-call with tweaked filters to cross-check. The `tags` filter accepts tag IDS only (orgtag_/orgproj_/systag_ from list_tags or resolve_tags). Plain tag NAMES are NOT resolved — unrecognized values are silently ignored and the result comes back UNFILTERED, so never pass names, and never present results as tag-filtered unless you passed real ids.

get_top_accounts

Get the organization's top performing creators (Creator Hub) for a date range, ranked by metric gains across their accounts. Metric semantics: plain metrics (viewCount, likeCount, …) rank by LIFETIME totals and surface old evergreen content. When the user asks about a time window ('last 30 days', 'this week'), rank by the matching *InPeriod metric (e.g. viewCountInPeriod) — the dateRange alone does NOT change the ranking. Every result row already contains both lifetime and in-period numbers, so do not re-call with tweaked filters to cross-check. The `tags` filter accepts tag IDS only (orgtag_/orgproj_/systag_ from list_tags or resolve_tags). Plain tag NAMES are NOT resolved — unrecognized values are silently ignored and the result comes back UNFILTERED, so never pass names, and never present results as tag-filtered unless you passed real ids.

get_top_creators

Get the organization's top performing tracked videos for a date range, ranked by metric gains (e.g. views). Use to answer 'which videos popped'. Metric semantics: plain metrics (viewCount, likeCount, …) rank by LIFETIME totals and surface old evergreen content. When the user asks about a time window ('last 30 days', 'this week'), rank by the matching *InPeriod metric (e.g. viewCountInPeriod) — the dateRange alone does NOT change the ranking. Every result row already contains both lifetime and in-period numbers, so do not re-call with tweaked filters to cross-check. The `tags` filter accepts tag IDS only (orgtag_/orgproj_/systag_ from list_tags or resolve_tags). Plain tag NAMES are NOT resolved — unrecognized values are silently ignored and the result comes back UNFILTERED, so never pass names, and never present results as tag-filtered unless you passed real ids.

get_top_videos

List recent tracking sync runs (queued/running/completed/failed). Use after add_tracked_accounts or refresh_* tools to check whether syncs finished; filter by eventIds returned from those calls.

get_tracking_status

Returns the number of conversations with unread messages. Organization staff must use scope "org".

get_chat_unread_count

Get analytics detail for a single tracked video by platform (tiktok | instagram | youtube | facebook | snapchat) and the platform's native video ID.

get_video

Get the time-series metrics history (views/likes/comments/shares over time) for a single tracked video. Pass the metrics to return and, optionally, a day/week/month aggregation. Use for trend questions about one video.

get_video_history

Get the organization's view gains for a date range grouped by country tag, with each country's top accounts and videos, plus filtered totals. Use to answer 'which markets drove views' or 'which accounts lead a market'.

get_views_by_country

Deep research breakdown of ONE viral-library video, beyond what search_viral_video_library already returns per result: the full hook analysis (visual, text overlay, audio, timestamp, psychological trigger, retention pattern, share/save drivers), the commercial read (product/brand shown and when, CTA mechanic, sponsored or organic), creator persona, and a scene-by-scene timeline where available. Use the `id` from a search result as `videoId`; call it for a handful of standout videos, not for every result.

get_viral_video_insights