Every Tool the Cheerful Connector Exposes

Search creators. Creator rows carrying handle, followers, engagement and platform, plus total and filtered_blocked_count. Results already have your account’s own block list applied. This tool consumes credits at the same rate as the web app.

Arguments

• query — for keyword search this describes the PERSON ("vegan meal prep mom"), not the campaign or the product. For action="similar" it is a handle.
• action — keyword (default, hard filters), smart (natural-language brief, planner-ranked), or similar (creators resembling one handle).
• platform — instagram (default) or tiktok.
• limit (25), page (1).
• min_followers, max_followers, min_engagement — keyword search only.
• location — full country names, never codes. Keyword search only.
• exclude_saved — skip creators already on your lists.

Traps

• action="smart" binds a location for fifteen countries only: United States, United Kingdom, Canada, Australia, Germany, France, Spain, Brazil, India, Mexico, Italy, Netherlands, Japan, South Korea and United Arab Emirates. A brief naming any other country has its location silently dropped and comes back global. Use action="keyword" with an explicit location for anywhere else. This is the single most expensive trap on the whole surface.
• location takes full country names, never ISO codes: "United States" not "US", "United Arab Emirates" not "UAE".
• No apostrophes in query — "women’s health" returns a 502. Write "womens health".
• total is the provider’s pre-filter pool, usually tens of thousands. It is not what you received. Count the rows you actually got.
• A search takes 90–155 seconds. That is the normal shape, not a hang, and retrying over the top of a running call just spends credits twice.

Creator profile. Followers, engagement, bio, recent posts, and a public email if one exists. This tool consumes credits at the same rate as the web app.

Arguments

• handle — with or without the leading @.
• platform — instagram (default), tiktok or youtube.

Traps

• platform must match the platform the handle was discovered on. Handles collide across platforms, so asking for a TikTok handle under the default instagram returns a different person’s profile, not an error.
• No email is the common case, not a failure, and not a reason to search again — emails are enriched later, when a creator is added to a campaign.
• TikTok and YouTube handles Cheerful has not seen before return is_enriched: false with no profile detail. Those platforms have no cheap refresh source, so the full profile is fetched when the creator joins a campaign. That is "not enriched yet", never "a creator with no followers".
• Roughly 60 seconds on a cold profile.

Read creator lists. Lists with their names and counts; for one list, every creator on it with creators_total. This tool is free — reads do not consume credits.

Arguments

• action — index (default, every list) or get (one list’s creators).
• list_id — required for action="get".

Traps

• A list carrying owner_email belongs to a teammate. It is readable and usable, but it is theirs — say so when you talk about it.

Read campaigns. Campaigns with team_id and owner_email, full settings for one campaign, or the sender mailboxes for one campaign. This tool is free — reads do not consume credits.

Arguments

• action — index (default), get (one campaign’s settings), or senders (the mailboxes that may send THIS campaign).
• campaign_id — required for get and senders.
• include_stats — sent and reply counts on the index.

Traps

• Senders are a property of the campaign, not of the viewer. A mailbox you can read is not necessarily one you may send from, so never name a sending mailbox that did not come from action="senders".
• 404 and "not yours" are deliberately the same response. A 404 is not proof the thing does not exist — list the parent collection instead of guessing ids.

Campaign performance. Sent, opened, replied and opted-in counts. This tool is free — reads do not consume credits.

Arguments

• action — account (default, whole account) or campaign.
• campaign_id — required for action="campaign".

Traps

• These are outreach metrics only. Credits and spend live in billing_usage, and the two answer different questions.

Read inbox. Threads with the account_id each one arrived on, plus a next_cursor. This tool is free — reads do not consume credits.

Arguments

• action — threads (default), counts (per-status totals with no bodies), or search (text across senders, recipients and subjects).
• campaign_id, account_id, status_filter, direction_filter, search.
• limit (25), cursor, include_messages.

Traps

• Page by cursor, never by offset. Pass the previous result’s next_cursor back as cursor — once a cursor is in play the server ignores offset and you will re-read the same page forever.
• Every thread names the mailbox it arrived on, because you may be reading a teammate’s. A thread on a read-only grant cannot be replied to or hidden by you; account_read is what tells you which is which.

Integration status. Connection health for Shopify, Google Sheets, Instantly, Monday, Airtable and the rest. This tool is free — reads do not consume credits.

Arguments

• None.

Traps

• Reports only. Connecting or reconnecting an integration happens in the web app, and no tool here can do it for you.
• Each provider’s status is fetched independently, so one provider being down reports as that provider’s error rather than blanking the others.

Account and access. Your user id and email, the teams you belong to, and exactly which mailboxes you may read versus send from. This tool is free — reads do not consume credits.

Arguments

• None.

Traps

• This is the tool that answers a 403. "Why can’t I" is almost always an access answer, not an error.
• It answers even for an account with no mailbox connected yet, which makes it the cheapest way to confirm a fresh connector is really talking to your account.

Credits and usage. Credit balance, what consumed credits this cycle, and when the balance renews. This tool is free — reads do not consume credits.

Arguments

• cycle — a specific billing cycle. Defaults to the current one.

Traps

• This is where a 402 sends you. A 402 means out of credits, not a bug.
• Reports credits, never dollars — you buy credits, not spend.
• If computed_at is null the cycle has not been rolled up yet. That is "not computed yet", not zero.
• Usage is keyed to the account that owns the work, so a teammate’s campaign spends the owner’s credits rather than yours.

Tools return a structured error rather than raising a protocol error, because a raised exception reaches an assistant as something opaque it cannot act on, and the blind-retry loop that follows is expensive for everyone.