Beacons

Create a trackable Beacons short link pointing at a destination URL. Clicks are counted and readable through get_analytics with source links, whose overview lists every short link. Pass vanity_slug to get a readable URL on the creator’s handle as well as the generated one; both point at the same link and their clicks count together. A slug already in use on this handle is refused rather than reassigned.

generate_short_link

Read your Link in Bio before editing or after an uncertain write. Omit selectors for every page with its ordered block summaries, the current appearance (colors including the link and block shadow colors, fonts, background) and site settings — the Disclaimers (sensitive content age warning, cookie notice), the SEO site title and site description, tracking pixels, UTM source and medium, and visitor pop-up — plus integrity warnings; a dangling_layout_entry includes repairable, which says whether the empty slot can be dropped with update_link_in_bio_blocks or needs cleanup in the Beacons editor, and an orphan_block_body includes repairable, which says whether that off-layout block can be put back on the page with a placement write, plus blocked_by when it cannot — pinned_header for the page header, account_cap or account_type_cap when the account already holds its maximum. The whole-account and page reads also return blocks_used and blocks_allowed: the editor allows 100 blocks per account across every page, hidden blocks and spacers included, and no plan raises it; block_type_usage gives each type's used and allowed count across the account. When a creator says Add block is greyed out, compare blocks_used with blocks_allowed first — at the cap, a block has to be deleted in the Beacons editor, or two merged, before another can be added. A multiple_header_blocks warning lists every shown header and the pinned one the editor edits; the others can only be hidden. Pass page for one page, or block_id for that block's full editable content and field limits — for a links block that is its links, each with its link_id, URL, title, subtitle, display and archived state, 50 at a time: links_total counts every link on the block, and while next_offset is not null, read again with that block_id and links_offset set to it (links_limit up to 100) until you have seen them all — or block_ids to read several blocks in one call, which returns each block's first window; read a later window of one of them with its block_id and links_offset. The whole-account read also returns affiliate_collections, every one of the creator's Affiliate Products collections with its collection_id, title, product_count and share_url, the link that opens that collection on their public page (null when the page link could not be read), whether or not an Affiliate block lists it; it is omitted when they have no collections and null when they could not be read. An affiliate block read also returns collection_share_urls, the shareable link that opens each of the creator's affiliate collections on their public page, keyed by collection_id, or null when the page link could not be read; give that link when a creator asks for a link to one collection, and wrap it with generate_short_link when they want a short link. Display and public render visibility are different: use the returned render verdict, and name blocks by block_name. A TikTok video in a Videos block is deliberately not shown when the page is opened inside the TikTok or Instagram app, and TikTok's own player shows a blank frame or 'Access denied' for a video that is private, deleted, region-restricted or has embedding turned off — neither is a Beacons fault, so explain it instead of reporting a gap. Missing setup returns empty pages; do not invent a page. Content category chips on the public page live on the Media Kit header: read them with get_media_kit and set or clear them with set_media_kit_profile header.categories.

get_link_in_bio

Get your Media Kit share URL to include in a message or draft. This returns a link and does not send a message.

get_media_kit_link

Who you are on Beacons: your username (handle), your public page URL, any custom domain, whether your email is verified, and which plans are active. Use this first when a question depends on what the account already has set up — "what is my url", "am I on Pro", "is my email verified". Also use it when you want a new username or page URL — "change my username", "update my username", "fix my Beacons URL", "change my page url": it returns the rules a new username must meet, what a username change does to your Beacons link and other links, whether this account can change it, and the Settings link where you make the change. It never renames. Call it again for each new name they suggest, because its rules are not carried into later messages. Reports entitlement, never billing: no amounts, invoices, cards, or renewal dates.

get_account

Creator analytics for one source or several side by side: links (Link in Bio and short-link clicks and unique clicks by link, link type, country, device or referrer), pages (views of their Link in Bio and Media Kit pages, and Link in Bio click rate, by page, country, device or referrer), products (store earnings split into direct sales and affiliate commissions, orders, refunds, product page views and conversion rate by product, traffic source, device, purchaser country or discount code), posts (posts on connected Instagram, TikTok, YouTube and other accounts: views, likes, comments, shares, saves and engagement by platform, account, post, content type (reels, carousels, videos) or sponsored), accounts (each connected social account's followers, follower change and profile views by platform, account or time), subscribers (email-list and form subscribers: signups, still active, unsubscribes, net change and retention by signup form or referrer platform; subscriber country is not available), emails (marketing email sends: delivered, opens, clicks, bounces, spam reports, open, click and bounce rates and deliverability by broadcast vs automation, email, automation or time) or deals (brand-deal money paid to them: revenue, paid deals and average deal value by brand, brand category, currency or month) or replies (Smart Reply automations: comments and unique_commenters (distinct recorded commenters), events, DMs sent, skipped and failed and send rate by automation, comment vs DM, outcome, reason or UTC time) or invoices (invoices they sent brands through Beacons Invoicing: invoices issued, amount invoiced, still unpaid, invoices paid and amount paid by customer, currency, day, week or month). For a broad question across areas, such as their biggest wins this week, a weekly recap or how they are doing overall, pass sources (the areas to cover) and the window instead of source: one call returns each area's totals for that window and the one before it. A comparison within one area, such as one platform this week vs last, is a single-source breakdown grouped by week. Pass only source (with optional start_date and end_date) for that area's full overview, the call for a general question such as how their sales, traffic, posts, followers, list or emails are doing. links: clicks over time, clicks per link, recorded revenue and form signups per link (which link made the most money or leads), and the short-link catalog capped by limit. pages: Link in Bio visits over time with country, device and referrer breakdowns, and Media Kit views; these page views are not the Home dashboard's Total Views, which counts views on their social posts. products: earnings and orders against the previous window, all-time earnings (the Home Total Earnings card), top products, sources and purchaser countries, and conversion by product (no direct vs affiliate split; ask for affiliate_earnings). posts: the window's top posts by engagement. accounts: every linked account's followers and when they last synced, connection health, engagement, audience demographics and Instagram/Facebook 28-day unique reach with its source and update time, a rolling snapshot that ignores the dates (filters.city looks up one audience city); call it for 28-day reach or before answering why a follower count looks old or how to refresh it. subscribers: signups and still-active counts by signup form and day, never names, emails or phones; the source for how their email list is doing (for growing or shrinking, ask for signups, unsubscribes and net_change, which the overview lacks). emails: the Email Marketing dashboard's delivery, open, click, bounce and deliverability numbers with new subscribers and undeliverable contacts; the source for how their emails are performing. deals: brand-deal revenue paid in the window by month, brand and category, all-time closed revenue, open pipeline value by stage and what is awaiting payment; brand deals only, never added to products. replies: every Smart Reply automation with its all-time sends and link clicks, and the latest comment and DM events with why each sent, was skipped or failed. invoices: all-time totals per currency of what they invoiced, were paid and are still owed, with draft, outstanding, paid and overdue counts, ignoring the dates; never added to deals or products. Each overview adds a vocabulary of the source's metrics, dimensions, filters and rules for the next slice. Add metrics, group_by or filters for a breakdown with every group up to limit (1-100), not a fixed top-N summary; truncated true means more rows exist than were returned, so raise limit or narrow the filters. Breakdowns answer: how much of their earnings was affiliate commissions (affiliate_earnings), exact page views per product (each row carries the product title, so no product lookup is needed first), where buyers are located (purchaser country), sales or views by hour, day or day of week, earnings by traffic source, which discount code drove the most sales, which product earns most on weekends, how one link did each day (filters link, group_by day, metrics clicks and unique_clicks), which referrers click one link, which posts got the most engagement last month, when to post (views_per_post by publish hour, since total views by hour mostly count how many posts went out then), how many followers they gained this month, one platform's followers and profile views week over week (filter by that platform, group_by week), which form or platform brings the most subscribers, and any ranking the fixed reports truncate. For a time window shorter than a day (e.g. "the last 24 hours"), group by day and hour with start_date set to yesterday's YYYY-MM-DD date, end_date today and limit 48, then sum only additive metrics in the day-and-hour rows inside the window, using the current time and the returned timezone; for products, hour takes only direct_orders, direct_earnings or refunded_orders. Never sum comments or unique_commenters across groups; omit group_by for distinct totals in a calendar-date window. Reply with the number; do not explain hours, time zones or how it was counted unless the creator asks. Products hours are the creator's local time and Link in Bio hours are UTC; product page views have no hours, only days. Purchaser country is the country recorded on the order at checkout, not visitor or follower geography.

get_analytics

One of your own brand deals in full: terms, deliverable counts, your notes, and the suggested-rate range Beacons precomputed for it. That range is frozen until the deal changes — use get_pricing_estimate to price a different or hypothetical bundle.

get_brand_deal

The email conversation behind one of your own deals, live from your connected Gmail. Returns gmail_thread_id and each message's gmail_message_id, sender, time, and body, plus saved file context. Copy those Gmail fields verbatim when replying or forwarding; Beacons UUIDs are never valid Gmail ids.

get_brand_deal_email_thread

Your own saved deal criteria — minimum rates, categories you want or avoid, dealbreakers. Read them before judging whether a deal is a fit or advising on a negotiation, and cite the one you relied on.

get_brand_deal_preferences

What Beacons knows about one brand: industry, size, headquarters, whether it runs an affiliate program you could join, and how often YOU have publicly posted about it. Take the beacons_brand_uid from a deal via get_brand_deal.

get_brand_info

Every integration on your account in one list — social accounts, payout methods, custom domains and the Google Workspace on them, and the Google Calendar and Zoom connections behind appointment bookings — each with whether it is connected, what broke and why in plain words, and a link to the page that repairs it. Use for "reconnect my Instagram", "why won't my YouTube connect", "why are my stats not syncing", "is my Stripe set up", "what email is my PayPal or Stripe on", "which PayPal connection does checkout use", "Express Checkout or Complete Payments" (Beacons has one PayPal connection, sometimes called PayPal Marketplace), "is my calendar connected for bookings", "do I have Google Workspace". Also for "disconnect my tiktok", "unlink my Instagram", "switch to a different TikTok account", "disconnect my Google Calendar" or "disconnect Zoom": no tool disconnects or switches an account, so this says where the creator does it. A social account that failed to connect is listed even if it was never linked, and a failure with no specific cause carries a support code for Beacons support. Reconnecting is an OAuth round trip and cannot be done here, so a broken integration comes back with a fix link. A payout method reports whether it is attached and the email on that Stripe or PayPal account, never the account id. A conferencing entry reports that a grant is stored, not that it still works — for whether Beam itself can read the calendar, call get_google_calendar_connection_status instead.

list_connections

Detailed view of one welcome or post-purchase Email Marketing automation, such as their welcome email or welcome letter: sequence settings and each email's subject, preview line, body, recipient, open, click, bounce, spam, and drop counts and rates. Call list_email_marketing_automations first and pass its sequence_id. It also returns each email's preview line and body block by block, with each text block written in the syntax the body parameter of update_email_marketing_automation takes, so where that tool is available read an email here before adding to or changing it. It returns totals for each email, never who received it.

get_email_marketing_automation

Read one of your broadcasts: what it says and how it performed. Returns its title, subject, preview_line (the inbox preheader) and body — the body as every block in the email in order, with the copy of each text block, the label and URL of each button, the titles and URLs inside image blocks, and the link_id, title and URL of each card and video in links and video blocks — so use this to preview, show or read a draft back before or after editing it with update_email_marketing_broadcast. Also delivery, open, click, bounce, spam, drop, and unsubscribe counts and rates, clicks by URL, a 30-day activity summary, and who the broadcast was sent to, as the names of the audience groups it targets, the store products whose buyers it adds or leaves out, and a count of any addresses entered individually. send_blocker says why it will not send: no subject, body text or audience, scheduled with nothing queued, or marked sent with nothing delivered. Call list_email_marketing_broadcasts first and pass its message_id. Subscriber identities and email addresses are not returned.

get_email_marketing_broadcast

Your current email sender settings: the read-only sender (From) address your emails, newsletters, broadcasts and automations are sent from, the default from-name and reply-to address (where replies land) for broadcasts and automated emails, your email logo, footer social links, single- or double-opt-in mode, whether the Beacons logo shows in your email footer, and safe custom-domain status. The read half of set_email_marketing_settings, under the same argument names — read it first, because that tool replaces each field it is given and replaces social_links wholesale. Your SendGrid key and subscriber lists are not readable here.

get_email_marketing_settings

Read which notifications reach you: the emails and mobile pushes for store activity — a free download, a paid sale, a new subscriber — and whether Beacons emails you a receipt when it charges your own Beacons subscription. Answers "am I notified when someone buys something?" and "do I get a receipt for my Beacons subscription?". Each field is true when that notification is currently being sent. Appointment booking reminders are always sent and are not listed. There is no notification timing, quiet hours, digest, or per-product notification setting. Read-only — set_account_notification_settings changes any of it.

get_account_notification_settings

One rostered creator's social account connections and their health: whether each handle is connected, whether it was ever OAuth-connected at all, why a connection is down, and the most recent auth failure per platform. Use it to answer "is this creator's Instagram connected" or "why is their data stale". Social connections only — payout methods and custom domains are not exposed on the manager surface. Reconnecting is an OAuth round trip only the creator can perform from their own account, so a broken connection is something to chase with the creator, not repair here.

list_organization_creator_connections

Detailed profile for ONE creator in an organization you manage: bio, categories, country, language, rates, creator-entered past brand partners, Media Kit brand partnerships and case studies, the full CRM profile, and overview stats plus audience demographics for each social account. crm_profile is the profile the agency maintains for this creator — the same record the Beacons for Managers portal edits under Creators → creator → Profile info — and it is the authoritative store for every built-in intake field, which list_organization_creators reports as intake_form questions whose answer is always null. Its top level (display_name, brand_deal_bio, content_categories, location, profile_pitch_photo_url) is shared data that already reaches pitch materials and Media Kits. Everything under crm_profile.agency_private is marked private in the portal and must NOT be put in anything a brand sees — a pitch, a one-sheet, a deck, an outreach email — unless the manager asks for that specific field in that specific place: language, dietary preferences, occupation, brand-deal and partnership preferences, past projects, personal milestones, birthday, gender, ethnicity, LGBTQ+ status, family members, legal name, personal and brand-deal contact email, phone number, website, and mailing-address country. Answer the manager’s own questions from it freely; it exists so they do not have to open the portal. mailing_address_country is the only address part available at all — street, city, province and postal code are encrypted at rest and no tool can read them. crm_profile.brand_deal_bio is the portal’s “Creator bio”; the top-level bio falls back to social_profile_bio, the creator’s own profile bio, when it is blank (bio_source says which). Whether a creator has a bio is answered by crm_profile.brand_deal_bio alone; read bio_note. rates and past_brand_partners stay at the top level and are not repeated inside crm_profile, and categories comes from the resolved profile rather than the CRM row: the portal’s “Content Category” is crm_profile.content_categories, so answer and edit from that. A manager asking about "past brand partners" means media_kit_brand_partnerships — the logo strip the Profile info page shows badged "in media kit" — NOT past_brand_partners, a legacy CRM column no surface renders and which is empty for almost every creator; read past_brand_partners_note before answering from either. The account fields include last-30-day average and median Reel views, average Reel watch time, average and median Story views, content engagement rate, and follower engagement rate. Audience demographics include age, gender, country, and city. Not searchable — one creator per call. For an "all stats" request or a pitch block, call this tool once, then call get_organization_creator_social_stats for every relevant account returned here; do not reconstruct account averages or medians from search_organization_content results. The average_*_last_30_days fields are PER-POST averages over the last 30 days, NOT 30-day totals — and do NOT multiply by engagement_content_count_last_30_days to get a total: each average is taken over only the subset of posts carrying that specific metric, a smaller and metric-specific count this payload does not expose, so that multiplication overstates the real total. The story-free averages are null when engagement_content_count_last_30_days is 0 or null (no story-free posts in the window at all, so there is nothing to average); a non-null average can still be 0 for an account that posted but has no view data for any of those posts, which reads the same as a real zero. average_engagement_rate_last_30_days is Beacons content engagement: the mean of (likes + comments + shares + saves) / views over story-free posts. follower_engagement_rate_last_30_days is the average likes + comments + shares + saves divided by followers (subscribers on YouTube). Both are 0-1 FRACTIONS, not percentages: 0.05 means 5%. average_reels_avg_watch_time_last_30_days is stored in HOURS; multiply by 3600 when quoting seconds. Reel metrics are story-free averages and become null when no story-free content exists. Story metrics use the story-inclusive content count and can remain present in that case. total_reach_count_last_28_days is first-party only (accounts the creator connected) and YouTube never carries it, so null there means unknown, never zero reach. The first-party figures (follower, following, subscriber, view and content counts, and reach) come from the FRESHEST record for that account; first_party_data_source is other_beacons_account when that record is held by a different Beacons account for the same handle, usually the same person signed up twice, and null when there is no first-party record at all. The data_source_is_connected / data_source_connection_state / data_source_state_reason_type / data_source_state_reason_timestamp fields are the connection state of that same record, so they answer "is the data behind these numbers healthy" rather than "is this creator’s own login healthy" — they are all null when first_party_data_source is null. For this creator’s own login state, read is_connected from list_organization_creators; the two legitimately disagree when the freshest record belongs to another account. audience_demographics values are 0-100 PERCENTAGES (65.3 means 65.3%), unlike engagement rates elsewhere which are 0-1 fractions; it is null for an account with no measured audience. A null age band means UNMEASURED, never 0% — the source fills absent bands with zeros, so a zero cannot be distinguished from a real absence and is reported as null. In age_percent the 45_64 band is a wider alternative bucketing some platforms report instead of 45_54 and 55_64 — never add all three, and expect only one of the two shapes to be present. country_percent is a list of {code, value} entries whose code is an ISO country code or a catch-all remainder bucket whose label casing varies; match it case-insensitively and never treat it as a country. city_percent is a list of {name, value} entries. Story link clicks are not in this payload because Beacons only stores them as creator-reported manual values, not connected-platform metrics.

get_organization_creator_info

The personal intake form link (onboarding link) for ONE roster creator in an organization you manage: the same link the manager portal copies with “Copy onboarding link” from the creator’s menu. The manager sends it to the creator, who opens it to fill in the agency’s intake form and connect their socials; the answers land on that creator’s profile. Every creator has their own link, so never reuse one creator’s intake_link for another. The agency has one intake form shared by every creator; intake_form_editor_url is the portal’s Creator Intake page, where the agency edits its questions and sees who has filled it in. Share intake_link exactly as returned.

get_organization_creator_intake_link

One link's lifetime click total plus its per-day clicks time series (up to ~3 years back; time_series_truncated flags older history, which the lifetime total still includes). Per-link views/impressions are not tracked. The link must belong to the creator. get_organization_analytics with source links and mode detail returns the same.

get_organization_creator_link_analytics

All link-in-bio links for ONE creator in an organization you manage, with lifetime click totals summed from daily click data. Per-link views/impressions are not tracked, so click-through rates cannot be computed. Use get_organization_creator_link_analytics for a per-day series.

list_organization_creator_links

Smart Reply triggers ONE creator has set up on Instagram, with their trigger word, response, and watched post. Currently returns comment triggers only, reported as trigger_type "post" — the same vocabulary set_smart_reply takes, so the value can be passed back verbatim. dm/global triggers and send/click totals are not yet available on this surface (totals return null, meaning unknown).

list_organization_creator_smart_replies

One Smart Reply trigger's analytics. Send/click totals and the per-day series are not yet available on this surface — totals return null (unknown) and the series is empty; the call still validates the trigger belongs to the creator.

get_organization_creator_smart_reply_analytics

The complete Beacons social-stat snapshot plus daily time-series stats for ONE of a creator's social accounts, up to 400 days back. One account per call. The series beacons_social_stats includes the organization-configured engagement window, every general and platform-specific metric Beacons has for that window (including median format views, watch time, story metrics, follower engagement, growth, totals, and audience cities/countries), with creator-entered manual overrides applied. For an "all stats" request or a pitch block, pair one call per relevant account with get_organization_creator_info for the creator-level profile, rates, partnerships, and account overview. engagement_metrics.average_reels_avg_watch_time is stored in HOURS; multiply by 3600 when quoting seconds. engagement_metrics.average_story_clicks is creator-entered manual data when present, not a connected-platform measurement. A null means Beacons has no usable value for that account; never describe a null as zero. The series is IRREGULARLY SAMPLED, not one row per day, and it is SPARSER in the recent window than in the older one — across 300 sampled accounts the most recent 100 days hold 4152 rows against 7281 in the oldest 100. days_returned vs days_requested is the machine-readable version of that: a low ratio means sparse coverage for this specific call, check it before doing period-over-period math rather than assuming one row per day. Quarter-over-quarter and any other period-versus-period math is therefore biased by sampling density; compare first and last values in a period, never row counts or sums. Current YouTube refreshes often supply follower and content snapshots without daily performance, while older historical rows can contain views and engagement. A missing daily value is not evidence that Beacons lacks the current profile snapshot. accounts_reached_last_day is ALWAYS null on TikTok and YouTube — ingestion stores the view count in that column, so there is no unique-reach figure to report; use view_count for views and accounts_engaged_last_day for engagement when those values are present. content_count can DECREASE when a creator deletes content, so a posts-published figure derived from its deltas must floor at zero. YouTube follower_count is quantized to three significant figures by the upstream API, so an unchanged value there hides any movement smaller than one step — zero growth on YouTube is not evidence the account did not grow. The whole series comes from whichever Beacons account holds the freshest profile row for this account, which is not always the creator's own — the same choice get_organization_creator_info reports as first_party_data_source, though this tool does not expose that label. That account is not always the one with the longest history, so past_n_days can return far fewer first-party points than the window would suggest, with the rest degrading to sparser scraped-only rows.

get_organization_creator_social_stats

Basic profile information about an organization you manage, including its managers (role, when added, name) and its branding: logo, badge, and the brand kit colors and fonts applied across its rosters, decks and media kits. Also gives the Beacons for Managers Chrome extension, the browser extension a manager installs from the Chrome Web Store: install_url is its store listing, and settings_url opens Settings > Agency Settings, whose Chrome extension section has the Get Chrome extension and Get access token buttons. You cannot install the extension or show the token yourself. When a manager asks about the Chrome extension, send both links and the steps: open the store listing in Chrome, click Add to Chrome, confirm Add extension, then click Get access token in Agency Settings to copy the token the extension uses. Does not include creators — use list_organization_creators for the roster, or get_organization_roster_analytics for roster-wide follower averages.

get_organization_info

Read ONE agency-branded Media Kit an organization you manage owns, in full: everything list_organization_media_kits shows plus the kit’s saved sections and appearance. This is the agency’s copy; the creator’s own Media Kit is a separate document that this never reads or changes. Address the kit by media_kit_slug or by the roster creator’s manager_creator_profile_id; either is checked against this organization, so a slug the manager gives you (or the end of the kit’s public /mediakit/ address) works without listing kits first.

get_organization_media_kit

Read ONE roster (one-sheet) or pitch deck an organization you manage owns, in full: everything list_organization_pitch_materials shows plus its description, slug, the creators on it, a roster’s card-or-table view type, and its saved layout and appearance. Each creator comes back with the manager_creator_profile_id the other agency tools take, so a creator on a material can be looked up directly, along with the per-material overrides update_organization_pitch_material_creator writes: creator_bio (the Description shown for them), min_rate, max_rate and profile_picture_url. Resolve the pitch_material_id with list_organization_pitch_materials first.

get_organization_pitch_material

Read ONE campaign report or pitch report an organization you manage owns, in full: everything list_organization_reports shows plus its budget, brand logo and domain, public slug, the creators on it, every content piece counted in it, and the rosters and pitch decks attached to it. Call it to answer how a campaign did: stats carries the headline numbers — creators, posts, views, engagements and engagement rate, plus spend, CPM and CPE when spend is recorded. visibility carries what the brand is shown (CPM, CPE, spend, EMV, audience, and the creators, content and platform tables) under the same show_ names update_organization_report takes, and hidden_from_brand what the shared link leaves out. Each creator comes back with the manager_creator_profile_id the other agency tools take, and each attached material with the pitch_material_id get_organization_pitch_material takes. Resolve the campaign_report_id with list_organization_reports first.

get_organization_report

Server-side average follower count by platform across every active creator on an organization you manage. Pages the full roster internally — a full page from list_organization_creators is not the roster and must not be averaged. Each creator counts at most once per platform (highest follower_count). The average denominator is creators with a known follower count on that platform; a missing count is omitted, not treated as zero. coverage is complete when every roster page was fetched, and incomplete only when a hard page cap stopped the walk. Do not invent averages when coverage is incomplete. To pick creators by follower count — "creators with more than 1M Instagram followers", "over 4M total reach" — pass min_follower_count: matching_creators then lists every roster creator at or above it, highest first, with the beacons_username a roster or deck takes. The count is summed across the platforms passed (one platform for a per-platform threshold, none for total reach across every platform). Use this instead of paging list_organization_creators. It lists 100 at a time; when next_offset is set, call again with the same arguments and offset for the next page. When coverage is incomplete the matches come from the loaded pages only, so matching_creator_count is a lower bound, not the full count. get_organization_analytics with source followers and mode detail returns the same.

get_organization_roster_analytics

List the management organizations you belong to. Call this first — the org-scoped tools take one of the returned organization_uids. Each membership carries has_paid_management_plan; the org-scoped tools refuse organizations without a paid Beacons for Managers plan.

list_organizations

Money questions about getting paid: "when do I get paid", "have I been paid", "where is my money", "what is my payout history", "am I set up to get paid", "how much have I made", "how much have I earned", "cash me out". Returns whether a Stripe or PayPal method is attached (with a repair link when none is), lifetime earnings as gross and Beacons fee per currency, and the link to the Payouts page in Beacons. Call it for any of those asks — do not refuse them. It CANNOT report your available balance, next payout date, tax documents, or the record of individual payouts already sent: Beacons does not hold those, Stripe and PayPal do, and they are reached through the Payouts page this tool returns. Say so and hand over that link rather than inferring any of it from earnings. Beacons cannot move money, so there is no cash-out tool — a creator asking to cash out gets the same page.

list_payouts

Comments on one of your own Instagram or TikTok posts: each comment's text, author username, and like count. Pass that post's instagram_post_id as content_id from list_creator_platform_posts — that field is the post id on Instagram and TikTok. Never invent one from a URL. If truncated is true, pass next_cursor back as cursor on the same platform and content_id to read the next page. If Instagram or TikTok is not connected or the session expired, the result carries reconnect_url: give the creator that link and do not invent comments.

get_post_comments

Get the creator's public Beacons page URL (their beacons.ai link or custom domain) — use when they ask for their page link, Beacons URL, or the link to share or paste. Always the signed-in creator's handle; there is no handle argument. Returns the canonical URL, the handle, and per-page URLs when they have more than one page. For a QR or barcode of that page, call generate_qr_code with no url. A missing handle or a Link in Bio that was never set up come back as DATA with a status, not as an error. page_available says whether the page is live or suspended by Beacons — use it for "my page says Link in Bio not available". Also returns the custom-domain mapping on the account and how to set one up — where the setting lives, the DNS records to add — so use it for "how do I use my own domain" and "my domain is not working".

get_public_page_url

Every canonical field of one of your own Shop products, under the exact same names update_store_product writes: title, price, checkout content, emails, layout, custom_slug, and more. page_appearance is the product page design under the names set_store_product_appearance writes — layout, font, and the page background, text, link, button, button-text, and block colors — with Store defaults filled in for anything never set. Course products include learner-facing course_title and course_description. waitlist_enabled says whether the product is Coming soon (a waitlist signup instead of checkout), with the waitlist copy in waitlist_heading, waitlist_description, waitlist_button_text and waitlist_launch_text, and waitlist_show_price. External-link products include external_url, the page the product redirects buyers to. Membership products deliver no files and include membership_config — the recurring price and currency, how often it bills, how many payments it takes, whether Stripe and PayPal are configured, and billing_status — plus setup_url, the Recurring price section of the Store builder. billing_status is live once a provider is charging, which update_store_product starts when it creates a membership for a creator with Stripe or PayPal attached. It is pending_payment_setup while nothing is charging, and interval and total_cycles are then null because nothing has chosen them yet. live_terms_unavailable means the provider terms could not be read, so report what is null as unknown rather than quoting a price. Also returns delivered files in display order, a read_only block (id, type, sales, sync status, store_item_version, shop_product_document_version), plus appointment_config, appointment_availability, and blocked_dates for appointment products. public_url is that product page's shareable link — the same one Beacons copies, using your custom domain when one is mapped and custom_slug when the product has one. Answer "what is the link to this product" from it; never build a URL by hand. It is null only when the account has no handle and no mapped domain. A hidden product (availability false) still has a public_url, so read availability before calling the page live. checkout_description is the product description — the Description section of the Store product editor, and the copy buyers read on the product page — as sanitized rich HTML that Beam chat renders as formatted text. The separate description field is a catalog caption, and is not what a creator means by the description. active_checkout_fields lists what the checkout already asks buyers for beyond name and email — read it before changing that set so you can tell the creator what is already on. Call this before update_store_product so a patch only changes the fields you mean to.

get_shop_product

Your store orders with per-currency totals: what sold, what state each order is in (completed, refunded, declined, or still open), the buyer name, email and shipping address on each order, and both gross earnings and earnings net of the Beacons fee. Also your Beacons affiliate sales, orders for another creator's product you resell, with the commission, Beacons fee and payout you earned on each and its commission status (available, processing, in-flight, paid, denied), in affiliate_orders and affiliate_by_currency. This is the read for who bought or ordered a physical product and where to ship or mail it: buyer shipping addresses are in shipping_address_line_1 through shipping_country, and shipping_address_status says whether one is on file. Each store order also carries the buyer's answer to the product's custom checkout question in checkout_answers. Also holds donations and legacy paid requests, so the response says how many of the orders are actual storefront sales. State comes from the order timestamps, so a refund is never hidden behind the completion before it, and refunded orders are excluded from earnings rather than deducted. Every order carries the traffic source it came from (instagram, tiktok, youtube, facebook, direct, and so on), and by_source rolls those up per currency with an average order value, read against the account's own average in by_currency, which is what answers which source drives higher-value orders. This is also the read for how many active members or subscribers a membership has: every membership renewal is its own order, so by_membership counts members per membership product (active right now, ended or cancelled, and started in the date range), and each membership order says whether its recurring subscription is still active. When a buyer never got their receipt, this is the read that finds the order: pass its order_id to send_store_order_confirmation to resend that confirmation email. Optional filters: order_id (one order), product_id (one product; this is orders.asset_id), state (completed / refunded / declined / open), status (raw orders.status, usually store_purchase or donation), since and until (YYYY-MM-DD). Returns order objects, not a spreadsheet download. This tool never refunds, edits, or deletes an order.

list_store_orders

Your store catalog: title, price, availability, inventory, and setup health flags (missing_delivery_asset, no_image, no_description, hidden, zero_views). Filter with product_type, availability, and search (case-insensitive title match). Omit every filter to list newest-first up to limit — the same unfiltered page as before. product_type values and what each supports: digital-products (file download after purchase; ~70% of catalog and ~93% of paid orders — ~84% of digital-product orders are free, so a store question is not automatically a revenue question), external-link (sends the buyer to a URL you host), beacons-affiliate (Beacons marketplace affiliate listing), appointments (bookable calendar time), brand-affiliate (a brand affiliate product on your store), course (gated course content), shopify-rye (Shopify product sold through Rye), membership (recurring membership access), shopify-rye-marketplace (Shopify marketplace product sold through Rye). missing_delivery_asset is only raised for digital-products and course. hidden is availability false. Prices are what a buyer is charged. Every product carries public_url, its shareable product page link, so "what are the links to my products" is answered from this tool alone — one call, no per-product follow-up. Rename, show, hide, or reprice a product by passing its product_id straight to update_store_product — no get_shop_product read first. store_item_version is the expected_store_item_version for adding a file, link, or review. Read the product with get_shop_product only when the edit needs its current contents: its checkout_description HTML, checkout_images, review ids, or the appointment availability and blocked dates being removed. Files are edited in Beacons. zero_views is a setup health flag (true when no views have been counted for the product page yet; today's views may not be counted), not a view count. Use it to decide whether to look up views; do not name the flag to the creator. For exact product page views, orders, and conversion rate per product, call get_analytics with source products, group_by product, metrics page_views, orders, conversion_rate. Never tell the creator view counts are unavailable. total_count is the number of products matching the filters across the whole catalog, independent of limit. Answer "how many products do I have" from total_count, never from the length of the returned list.

list_store_products

Your store-wide settings in one place: terms and conditions, whether Beacons branding is hidden, whether payment plans are offered, the four tracking pixels. Currency is set per product with update_store_product. There is no store-wide currency, tax, category, shipping, or abandoned-cart setting, and which sale notifications reach you lives in get_account_notification_settings, not here. Read-only.

get_store_settings

Public social accounts posting about a brand most often, with handles and counts. Evidence that the brand works with creators in this space — a mention is organic unless proven otherwise, never proof anyone was paid.

list_top_brand_mention_creators

Every Smart Reply automation on your Instagram account — post-specific, any-post, and DM/story — with per-automation send and click stats and whether the Instagram connection is healthy. It identifies the one Instagram account configured for Smart Reply and every Instagram account connected to Beacons. Smart Reply supports one account at a time, and this tool cannot switch it. It warns when account state is ambiguous or incomplete. Never use a Smart Reply list to identify a post. Post identity comes only from published-post metadata and image or content evidence — the captions, permalinks, timestamps and thumbnails from list_creator_platform_posts. Once you have an instagram_post_id from there, call this with that id to see whether that post already has an automation. Called with no arguments it is the whole inventory, which answers "what automations do I have?" and nothing about which post the creator means. A post automation shadows any-post automations on its post, and duplicate keywords across any-post or across DM automations are rejected.

list_smart_replies

Your recent posts on one platform (up to 20 from the last 60 days), newest first, with thumbnail, content type, title, duration, caption, available view/like/comment counts and permalink. This is the source of post identity: work out which post the creator means from these captions, permalinks, timestamps and thumbnails, never from a Smart Reply list. post_source says whether Instagram was checked live. Never call a cached result latest, newest, or today. Use instagram_post_id for Smart Reply and content_id for Link in Bio feed post_ids; never construct an id from a URL. Feed writes resolve owned cached posts and may refuse a live Instagram post until it is cached. A healthy connection is only needed for Instagram auto-sync, not static cached feeds.

list_creator_platform_posts

List your Store discount codes, newest first. discount_amount is a 0–1 fraction: 0.2 means 20% off. store_item_id is the one product a code works on at checkout; a row with store_item_id null is attached to no product, so buyers cannot redeem it anywhere until set_discount_code gives it one. Optional discount_code is an exact match after trim and uppercase. Optional store_item_id omitted returns every code, null returns only codes attached to no product, and a UUID returns codes for that product. Store discount codes are percentage-only; there are no fixed-amount or flat-rate codes. writable is true on every row: set_discount_code can update it, or delete it with delete true and that row's discount_code_id. There is no expiry, usage-limit, or minimum-order capability.

list_discount_codes

List this creator's Beacons Email Marketing welcome and post-purchase sequences, the funnels that send emails automatically, across active, paused, draft, and archived states. Use it to audit sequence settings and each email's recipient, open, and click performance; this is not list_automations, which reads Beam Settings automation toggles, and it does not list one-off broadcasts. Call it first when they ask whether their automated emails are working, turned on, or sending, which emails are not active, or whether new subscribers got the second email, and when they mention their welcome email or welcome letter; then pass its sequence_id to get_email_marketing_automation for that one sequence. Optional status accepts active or paused; active maps to the stored running status. Returns the newest 25 sequences by default, up to 100; a start-condition id of global means any list or product. The product stores status-change time, not the last time a recipient triggered a sequence.

list_email_marketing_automations