Docs/API/MCP Tools

MCP Tools Catalog

celavii-mcp@0.2.8 exposes 83 tools across 12 groups to AI assistants via the Model Context Protocol.

Jump to group

Meta (3)Profiles (13)Campaigns (4)Lists (8)Analytics (14)Content (2)Manage (6)Knowledge (8)Enhance (4)Scrape (17)Refine (2)Jobs (2)

Meta3 tools

Account info and credit usage. Always loaded.

Tool	Description	Credits
`get_account_info` Get Account Info	Get API key info, organization, scopes, and a TWO-LEVEL usage rollup. Returns: (1) `usage.total_credits_used` and `usage.credits_today` for THIS key (what the key personally spent), (2) `usage.credits_by_family` breaking that down into {scrape, enhance, refine, other} so you can see where credits went, and (3) `usage.organization_totals` with the SAME shape rolled up across every API key in the org plus a `by_key` array showing per-key spend. Why two levels: a freshly-rotated key looks free (e.g. 35 credits) even though the org has burned thousands via another key — always check `organization_totals` for the real bill. Costs 0 credits.	Free
`get_usage` Get Usage	Get credit usage and rate limit status. Returns: lifetime + today totals for the calling key, a `credits_by_family` breakdown {scrape, enhance, refine, other} so agents see where spend went, `organization_totals` rolled up across every key in the org (with a `by_key` array), and `endpoints_today` — the top 20 endpoints by request count for today with per-endpoint credit totals. Use `organization_totals.credits_by_family.scrape` to see total scrape spend across the org — that is the answer to "what about scraping credits?". Costs 0 credits.	Free
`get_youtube_quota` Get YouTube Data API v3 Quota	Returns the platform's YouTube Data API v3 quota state. Returns BOTH raw units (cap, used, remaining, reset_seconds) AND a normalized "operations remaining today" estimate per op-type — agents can pick the shape that suits their planning. Note: quota is a global daily cap shared across all orgs on the same Google API key. Free.	—

Profiles13 tools

Search, retrieve, and enhance creator profiles.

Tool	Description	Credits
`search_profiles` Search Profiles	Search the Celavii creator database. Filter by query text, niche, location, gender, follower count. Returns matching Instagram profiles with basic stats. At least one filter is required. Costs 1 credit.	1
`search_profiles_by_affinities` Search Profiles by Affinities	Search creators by their AI-analyzed brand or topic affinities. Find creators who have affinity for specific brands, interests, or topics. Costs 1 credit.	1
`get_profiles_bulk` Get Profiles Bulk	Get detailed information for multiple profiles at once by username or profile ID. Up to 100 profiles per request. Costs 1 credit.	1
`get_profile` Get Profile	Get detailed information about a single Instagram profile by username or profile ID. Returns bio, stats, niche, location, job_status (enhance/refine/scrape progress), and more. Costs 0 credits.	Free
`get_profile_affinities` Get Profile Affinities	Get AI-analyzed brand and topic affinities for a profile. Shows what brands, interests, and topics a creator is associated with. Costs 0 credits.	Free
`get_profile_posts` Get Profile Posts	Get recent posts for a profile across all 4 platforms (Instagram, TikTok, YouTube, X). Returns post platform + title (YouTube primary hook surface — null for IG/TT/X) + caption/content + engagement metrics + media URLs + hashtags. Identifier accepts platform-prefixed IDs (`yt:UCxxx`, `tt:username`, `ig:xxx`, `x:username`), bare usernames, or @handle. Costs 0 credits.	Free
`get_profile_network` Get Profile Network	Get the social network graph for a profile — mutual connections, top followers, and following relationships. Costs 0 credits.	Free
`get_profile_followers` Get Profile Followers	Get the followers list for a profile. Only available if followers have been scraped. Costs 0 credits.	Free
`get_profile_following` Get Profile Following	Get the accounts a profile is following. Only available if following data has been scraped. Costs 0 credits.	Free
`get_profile_social_links` Get Profile Social Links	Get external social media links found in a profile bio (YouTube, TikTok, Twitter, etc.). Costs 0 credits.	Free
`get_profile_contact` Get Profile Contact	Get contact information (email, phone) for a profile. Requires the profiles:contact scope. Costs 0 credits.	Free
`find_similar_profiles` Find Similar Profiles	Find profiles semantically similar to a seed profile using AI embeddings. Uses vector similarity to find creators with similar content, topics, and style. More powerful than keyword matching — finds conceptually related profiles. Costs 1 credit.	1
`find_similar_to_cohort` Find Similar to Cohort	Find profiles similar to a GROUP of seed profiles. Computes a centroid embedding from multiple profiles and finds similar creators. Use case: "Find creators like these 5 influencers I already work with". Costs 1 credit.	1

Campaigns4 tools

Manage campaigns and creator outreach.

Tool	Description	Credits
`list_campaigns` List Campaigns	List all campaigns in the organization. Optionally filter by status. Costs 0 credits.	Free
`get_campaign_metrics` Get Campaign Metrics	Get performance metrics for a specific campaign — total creators, posts, engagement, reach, and more. Costs 0 credits.	Free
`get_campaign_creators` Get Campaign Creators	Get the list of creators assigned to a campaign with their statuses and metrics. Costs 0 credits.	Free
`get_campaign_content` Get Campaign Content	Get content (posts) associated with a campaign. Includes engagement data and media. Costs 1 credit.	1

Lists8 tools

Organize creators into reusable lists.

Tool	Description	Credits
`list_lists` List Lists	Get all creator lists in the organization. Costs 0 credits.	Free
`create_list` Create List	Create a new creator list. Costs 1 credit.	1
`get_list` Get List	Get details for a specific list by ID. Costs 0 credits.	Free
`update_list` Update List	Update a list name or description. Costs 0 credits.	Free
`delete_list` Delete List	Delete a list. This does not delete the creators in the list. Costs 0 credits.	Free
`get_list_members` Get List Members	Get the creator profiles in a list with optional filtering. Costs 0 credits.	Free
`add_list_members` Add List Members	Add creators to a list by username or profile ID. Costs 1 credit.	1
`remove_list_members` Remove List Members	Remove creators from a list. Costs 0 credits.	Free

Analytics14 tools

Audience analytics, demographics, and affinity insights.

Tool	Description	Credits
`get_demographics` Get Demographics	Get audience demographics breakdown (age, gender distribution). Optionally pass profile_ids to analyze a subset, or scope=org for managed profiles only. Costs 1 credit.	1
`get_locations` Get Locations	Get location distribution — top cities and countries. Use scope=org for managed profiles only. Costs 1 credit.	1
`get_niches` Get Niches	Get niche/topic distribution across profiles. Use scope=org for managed profiles only. Costs 1 credit.	1
`get_network_overlap` Get Network Overlap	Get follower/following overlap between profiles. Shows shared connections. Provide identifiers, a list_id, or a campaign_id. Costs 1 credit.	1
`get_shared_hashtags` Get Shared Hashtags	Get hashtags shared across a set of profiles. Shows common themes and topics. Provide identifiers, a list_id, or a campaign_id. Costs 1 credit.	1
`get_hashtag_creators` Get Hashtag Creators	Find creators who use specific hashtags. Useful for discovering creators by topic. Costs 1 credit.	1
`get_affinity_posts` Get Affinity Posts	Get posts linked to a brand/topic affinity term. Searches globally across all profiles. Costs 1 credit.	1
`analyze_cohort` Analyze Cohort	Run a full cohort analysis on a set of profiles. Includes demographics, affinities, hashtag usage, and aggregate stats. Costs 2 credits. IMPORTANT — affinities/niches come from REFINEMENT, not enhancement. `account_stats.enhanced` reflects basic enrichment (bio/followers/gender/engagement), while affinity vectors and brand/topic niches require `refine_profiles`. If you bulk-enhanced a cohort and saw `cohort_count`s for affinities not move, that is expected — call `refine_profiles` next. To refine a network cohort, first create a list (`create_list` + `add_list_members`) or pass explicit `identifiers` to `refine_profiles`; a raw `source: {type: 'followers'\|'following'}` input is not refinable on its own.	2
`get_cohort_stats` Get Cohort Stats	Get aggregate statistics for a cohort — average followers, engagement rate, etc. Provide identifiers, a list_id, or a campaign_id. Costs 1 credit.	1
`filter_cohort` Filter Cohort	Filter a cohort of profiles by advanced criteria — follower range, engagement rate, niche, location, affinities, and more. Costs 2 credits.	2
`get_posting_times` Get Posting Times	Get posting time patterns (day-of-week + hour heatmap), content format distribution, and sentiment analysis for a cohort. Useful for finding optimal posting times. Provide identifiers, a list_id, or a campaign_id. Costs 1 credit.	1
`get_youtube_channel_summary` Get YouTube Channel Summary	Aggregate stats about a YouTube channel's commenter network — total comments collected, unique commenters, last collection time. Backed by api.get_channel_summary_yt_v1. Free. Response includes `data_status` (collected \| channel_found_no_commenters \| channel_not_found), `last_collected_at`, and `channel_id` (canonical yt:UCxxx) which can be passed directly to `scrape_youtube_commenters` to collect commenter data. The legacy `summary.out_*` fields are preserved for back-compat and will be removed in 0.3.0.	—
`get_youtube_bridge_creators` Get YouTube Bridge Creators	Find YouTube channels whose commenters overlap with a seed channel — the YT-network analogue of audience overlap. Backed by api.get_bridge_creators_yt_v1. Free. Response includes `data_status` (collected \| collected_no_bridges \| no_commenter_data \| channel_not_found) so callers can distinguish "no overlap" from "no data collected yet". If `no_commenter_data`, run `scrape_youtube_commenters` on the seed first.	—
`get_youtube_graph_edges` Get YouTube Commenter Graph Edges	Edge list for the commenter-overlap graph rooted at one or more seed channels — suitable for network visualization. Provide seeds as usernames or yt: prefixed IDs. Backed by api.get_graph_edges_yt_v1. Free.	—

Content2 tools

Retrieve and analyze creator posts and content.

Tool	Description	Credits
`search_content` Search Content	Full-text search across post captions on all 4 platforms (Instagram, TikTok, YouTube, X). Returns matching posts with platform + title (YouTube primary hook — null for IG/TT/X) + caption + engagement metrics. Use `platform` to filter to a single network. Use `verbose: false` to strip caption + hashtags from the response (helps when result captions are long — YouTube descriptions can run 2,000–5,000 chars; title is kept even in non-verbose mode since it's the primary YT hook surface). Costs 2 credits per call (was incorrectly documented as 1 credit through 0.2.3).	2
`semantic_search_content` Semantic Search Content	Search posts using AI embeddings for semantic similarity (Instagram, TikTok, X only). Combines full-text search with vector similarity for best results. YouTube post embeddings are not yet populated — use `search_content` (FTS) for YouTube. Returns platform + title (null for IG/TT/X — these don't have a separate title field) + caption + engagement + semantic_score. `verbose: false` strips caption + hashtags. Costs 1 credit.	1

Manage6 tools

Organization and workspace management.

Tool	Description	Credits
`get_managed_profiles` Get Managed Profiles	Get all profiles in the CRM pipeline with their relationship statuses, notes, and tags. Costs 0 credits.	Free
`get_crm_summary` Get CRM Summary	Get a summary of the CRM pipeline — counts by status, recent activity, etc. Costs 0 credits.	Free
`get_org_stats` Get Organization Stats	Get aggregate statistics for the organization — total profiles, enhanced profiles, scraped data, and more. Costs 0 credits.	Free
`upsert_relationship` Upsert Relationship	Create or update a CRM relationship for a creator. Set status, notes, tags. Costs 0 credits.	Free
`delete_relationship` Delete Relationship	Remove a creator from the CRM pipeline. Does not delete the profile itself. Costs 0 credits.	Free
`upsert_relationships_bulk` Upsert Relationships Bulk	Bulk update notes, tags, or status for multiple CRM profiles in one call. Creates relationships if they do not exist. Max 100 profiles per request. Costs 0 credits.	Free

Knowledge8 tools

Brand DNA, briefs, and knowledge base entries.

Tool	Description	Credits
`list_knowledge_folders` List Knowledge Folders	List all knowledge base folders in the organization. Costs 0 credits.	Free
`create_knowledge_folder` Create Knowledge Folder	Create a new knowledge base folder. Costs 0 credits.	Free
`get_folder_entries` Get Folder Entries	Get all entries in a knowledge base folder. Costs 0 credits.	Free
`create_knowledge_entry` Create Knowledge Entry	Create a new knowledge base entry in a folder. Costs 0 credits.	Free
`get_knowledge_entry` Get Knowledge Entry	Get a specific knowledge base entry by ID. Costs 0 credits.	Free
`update_knowledge_entry` Update Knowledge Entry	Update a knowledge base entry. At least one field required. Costs 0 credits.	Free
`delete_knowledge_entry` Delete Knowledge Entry	Delete a knowledge base entry. Costs 0 credits.	Free
`search_knowledge` Get Knowledge Context	Get aggregated brand context from the knowledge base, organized by folder type. Returns entries for AI agent consumption. Filter by folder type to get specific context. Costs 0 credits.	Free

Enhance4 tools

AI enrichment of profiles and content.

Tool	Description	Credits
`enhance_profiles` Enhance Profiles	Trigger AI enhancement for one or more profiles. Enhancement adds affinities, demographics, niche analysis, and more. Returns a job ID — poll with get_enhancement_status to check progress. Costs 1+ credits.	—
`enhance_bulk` Enhance Bulk	Trigger bulk enhancement for a large set of profiles from a network source (followers/following) or search filters. Returns a job ID. Costs 1+ credits.	—
`confirm_enhancement` Confirm Enhancement	Confirm and start a pending enhancement job. Some jobs require confirmation before processing begins (e.g. large batches). Costs 0 credits (charged at creation).	Free
`get_enhancement_status` Get Enhancement Status	Check the status of an enhancement job. Returns progress, completed count, and results when done. Costs 0 credits.	Free

Scrape17 tools

Trigger fresh data pulls from social platforms.

Tool	Description	Credits
`scrape_followers` Scrape Followers	Trigger a follower scrape for a profile. Collects the full follower list. Returns a job ID — poll with get_scrape_status. Costs 2 credits.	2
`scrape_following` Scrape Following	Trigger a following scrape for a profile. Collects who they follow. Returns a job ID — poll with get_scrape_status. Costs 2 credits.	2
`scrape_followers_bulk` Bulk Scrape Followers	Trigger a follower scrape for multiple profiles in a single Apify run. Much more efficient than calling scrape_followers repeatedly — uses 1 API call, 1 DB connection, and 1 Apify run instead of N. Max 50 profiles per request. Returns a single job ID — poll with get_scrape_status. Costs 2 credits + processing. IMPORTANT: TikTok bulk scrapes limited to 10 profiles per request due to rate limiting.	2
`scrape_following_bulk` Bulk Scrape Following	Trigger a following scrape for multiple profiles in a single Apify run. Much more efficient than calling scrape_following repeatedly — uses 1 API call, 1 DB connection, and 1 Apify run instead of N. Max 50 profiles per request. Returns a single job ID — poll with get_scrape_status. Costs 2 credits + processing. IMPORTANT: TikTok bulk scrapes limited to 10 profiles per request due to rate limiting.	2
`scrape_locations` Scrape Locations	Scrape posts from a specific Instagram location/place. Returns a job ID. Costs 1 credit.	1
`scrape_hashtags` Scrape Hashtags	Scrape posts from a specific hashtag. Collects recent posts using that hashtag. Returns a job ID. Costs 1 credit.	1
`scrape_urls` Scrape URLs	Scrape specific Instagram post or reel URLs. Extracts engagement data, comments, and media. Returns a job ID. Costs 1 credit.	1
`get_scrape_status` Get Scrape Status	Check the status of a scrape job. Returns progress + results + cost. The `cost` block surfaces `estimated_credits` (locked at trigger time), `actual_credits` (populated by Apify-webhook reconciliation OR YT Data API v3 quota tracker — null while job is still running), and `cost_status` (held \| final \| refunded \| expired \| none). Costs 0 credits to call.	Free
`scrape_x_followers` Scrape X Followers	Trigger an X (Twitter) follower scrape for a profile via apidojo/twitter-user-scraper. Returns a job ID — poll with get_scrape_status. Costs 2 credits + processing.	2
`scrape_x_followers_bulk` Bulk Scrape X Followers	Trigger X follower scrapes for up to 50 profiles in one request. Each profile gets its own search row + queue job — independent retries. Costs 2 credits per profile.	2
`scrape_x_following` Scrape X Following	Trigger an X (Twitter) following scrape for a profile. Returns a job ID — poll with get_scrape_status. Costs 2 credits + processing.	2
`scrape_x_following_bulk` Bulk Scrape X Following	Trigger X following scrapes for up to 50 profiles in one request. Costs 2 credits per profile.	2
`scrape_x_hashtags` Scrape X Hashtags	Scrape recent X (Twitter) posts matching one or more hashtags via kaitoeasyapi tweet scraper. Supports advanced filters (media-only, blue-verified, has-engagement) and sort order. Returns a job ID. Costs 1 credit + processing.	1
`scrape_youtube_commenters` Scrape YouTube Commenters	YouTube does not expose subscriber lists — the closest network signal is the set of channels commenting on a creator's videos. Triggers a batched commenter fetch (channels.list + videos.list + per-video commentThreads.list). Hybrid sync+async: executes synchronously within the request (typically 5–30s depending on video_count × comments_per_video) and returns inline summary data — succeeded[] with each video's commentCount, failed[], total_comments, unique_commenters, quota_consumed — alongside a job_id + poll_with for retrospective tracking. No polling needed for completion. Response also surfaces video_count_requested + video_count_available + video_count_clamped so agents can detect when the channel has fewer indexed videos than requested (run scrape_youtube_videos first to index more). Requires the channel to have indexed posts — run scrape_youtube_videos (channel mode) or enhance_profiles first if commenters returns 400 "No videos available". Results are stored in the network graph for use by get_youtube_bridge_creators and get_youtube_channel_summary. Costs 2 credits + YouTube Data API v3 quota usage (quota_consumed returned in response).	2
`scrape_youtube_hashtags` Scrape YouTube by Keyword	YouTube keyword/hashtag search via streamers/youtube-scraper (Apify-backed, NOT YouTube Data API v3). Each input becomes a search query. Returns a job_id immediately; results land asynchronously through the unified job system. Poll with `list_jobs` or `get_scrape_status` to track progress (typical run: 1–5 min depending on per_hashtag_limit). Costs 1 credit + Apify processing.	1
`scrape_youtube_trending` Scrape YouTube Trending	Pull the YouTube trending feed via apidojo/youtube-scraper (Apify-backed, NOT YouTube Data API v3). Returns a job_id immediately; results land asynchronously through the unified job system. Poll with `list_jobs` or `get_scrape_status` to track progress (typical run: 1–3 min depending on max_items). Returns the most popular uploads in the requested timeframe. Costs 1 credit + Apify processing.	1
`scrape_youtube_videos` Collect YouTube Videos (Channel or Single)	Dual-mode YouTube video collection via Data API v3 (NOT Apify). Auto-detects input shape: • Channel input (`@handle`, `yt:UCxxx`, bare handle, or channel URL) → pulls channels.list + uploads playlist + videos.list pages + playlists. Writes profile (if new) + posts. Mode = "channel". • Video input (video URL or 11-char video id) → pulls videos.list for that one video. Mode = "video". Response carries `mode` so the agent sees what happened. Channel mode is the typical "give me a channel's recent videos" workflow — also seeds the channel for subsequent scrape_youtube_commenters runs. Executes synchronously (3–15s for channel mode, <2s for video mode). Returns job_id + poll_with + quota_consumed inline; no polling needed for completion. Costs 2 credits + Data API v3 quota (channel: 1 + ceil(videos/50)×2 + 1 units; video: 1 unit).	2

Refine2 tools

Iterative refinement of search results and filters.

Tool	Description	Credits
`refine_profiles` Refine Profiles	Trigger AI refinement for one or more profiles. Refinement uses AI to improve and enrich profile data — better niche classification, bio analysis, content themes, etc. Returns a job ID — poll with get_refinement_status. Costs 1+ credits.	—
`get_refinement_status` Get Refinement Status	Check the status of a refinement job. Returns progress and results when done. Costs 0 credits.	Free

Jobs2 tools

Background job status and coverage.

Tool	Description	Credits
`get_job_coverage` Get Job Coverage	Get aggregate job coverage stats for a list or campaign — shows how many profiles have been enhanced, refined, or scraped (followers/following) and how many are pending or not started. Provide a list_id or campaign_id. Optionally filter by job_type or platform. Costs 0 credits.	Free
`list_jobs` List Jobs	List all jobs for the organization — enhancement, refinement, and 7 scrape kinds. Returns a unified view sorted by most recent. Filter by type and/or status. Scrape kinds (added in 0.2.4): hashtag_scrape, location_scrape, video_scrape, commenter_scrape, url_scrape — alongside existing followers_scrape + following_scrape. Costs 0 credits.	Free