Beacons

Read one Link in Bio block in full by block_id. The writable types (text, header, links, spacer, scrolling text / marquee, countdown, community, media kit / media_kit_in_lib, live events / tours_and_events, affiliate products / affiliate, digital products / store) return the full body, the writable field contracts, and a render verdict; links entries come back as well-formed links only. Other block types return a summary. Name the block to the creator by its product name (scrolling text block, never marquee block). Safe to retry.

get_link_in_bio_block

What your own Media Kit currently says: appearance (colors, font, component shape), the header (display name, pronouns, headline, location, profile photo), the bio text block, the contact info block (contact_email, title, message), the rate card, brand partners with their logos and websites, case studies, featured links (portfolio, press, past campaigns — not the Media Kit share URL), and the social platform blocks on the page. Every write argument uses the same name here — rate lines use deliverable, price_usd, and description, matching set_media_kit_rate. Until 2026-12-01 each rate also repeats deliverable as name for clients that still parse the old field. price_display and price_minor_units are the formatted money pair for quoting. Send writable values back only when non-null; omit null price_usd or description fields on updates. Read this before writing. Use only write tools that already appear in your tool list — never invent a write-tool name. Appearance is set_media_kit_appearance. Every rate is returned regardless of visibility; `rates_displayed` reports whether the rate card is visible to visitors, `featured_links_displayed` does the same for the links block, and every other block carries its own `displayed`.

get_media_kit

How often your own Media Kit was viewed, by day. There is no creator argument — the account is always yours. Anonymous views, your own logged-in views, and views that arrived via your Link in Bio are counted separately, so "audience" is not confused with self-traffic.

get_media_kit_analytics

Performance for every Smart Reply automation on your Instagram account — post-specific, any-post, and DM/story — with all-time send and click counts plus clicks by destination. Use for questions about deliveries, link clicks, CTR, or which automation or button performs best.

get_smart_reply_analytics

Who you are on Beacons: your 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". Reports entitlement, never billing: no amounts, invoices, cards, or renewal dates.

get_account

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 — each with whether it is connected, what broke, and a link to the page that repairs it. Use for "reconnect my Instagram", "why are my stats not syncing", "is my Stripe set up". Reconnecting is an OAuth round trip and cannot be done here, so a broken integration comes back with a fix link. Payout methods report only whether they are attached, never the account id.

list_connections

How your own email broadcasts performed — delivered, opened, clicked, and the open and click rates. Broadcasts only; automated and triggered emails are a separate surface and are excluded.

get_email_marketing_analytics

Your current email sender settings: the from-name and reply-to address applied to broadcasts, your email logo, and the footer social links. 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

What you have invoiced, been paid, and are still owed, grouped by currency and never added across currencies. Counts drafts, outstanding, paid and overdue invoices. Each amount comes as a minor-units integer plus a formatted display string — quote the display string.

get_invoice_analytics

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, and overview stats plus audience demographics for each social account. Not searchable — one creator per call. 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. All five averages are null together 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 a 0-1 FRACTION, not a percentage: 0.05 means a 5% engagement rate. 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.

get_organization_creator_info

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_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. 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. accounts_reached_last_day and accounts_engaged_last_day are present on roughly 79-87% of rows overall and are entirely absent on YouTube. accounts_reached_last_day is ALWAYS null on TikTok — ingestion stores the view count in that column, so there is no reach figure to report; use view_count for views and accounts_engaged_last_day for engagement. 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). Does not include creators — use list_organization_creators for the roster.

get_organization_info

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

Whether you are set up to get paid, and what you have earned: which payout method is attached, plus gross and Beacons fee from completed orders per currency. Answers "am I set up to get paid" and "how much have I made". It CANNOT report your available balance, next payout date, tax documents, or individual payouts — Beacons does not hold those; Stripe and PayPal do. Send the creator to the payouts page rather than inferring any of it from earnings.

list_payouts

Your own store sales for a window (default the last 30 local days): revenue and orders, breakdowns by product, source, device and purchaser country, a daily series, and per-product page views with conversion rate (orders / views). Purchaser country is the ISO code recorded on the order at checkout (IP), not visitor or follower geography. Earnings are net of the Beacons fee and include verified affiliate commissions.

get_sales_analytics

Every canonical field of one of your own Shop products, under the exact same names set_shop_product writes: title, price, checkout content, emails, layout, custom_slug, and more. Also returns delivered files in display order, a read_only block (id, type, sales, sync status, store_item_version), and appointment_config for appointment products. checkout_description is sanitized rich HTML that Beam chat renders as formatted text. Call this before set_shop_product so a patch only changes the fields you mean to.

get_shop_product

Your own Beacons short links with their click counts — lifetime and over a recent window — ordered by lifetime clicks. There is no creator argument. Returns the short URL, any vanity URLs (an array), and the destination.

get_short_link_analytics

Your own social performance per platform: followers, engagement over the last 10 posts and last 30 days, content-type breakdown, follower growth, and audience gender/country splits. Rates and shares are fractions, and null means untracked rather than zero. A platform that is listed but not OAuth-connected comes back named, with a link to the page that connects it.

get_social_analytics

Your store orders with per-currency totals: what sold, what state each order is in (completed, refunded, declined, or still open), the buyer name and email on each order, and both gross earnings and earnings net of the Beacons fee. 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. There is no resend tool — once this returns a buyer's email, tell the creator to resend the order from the Sales area in Beacons; this conversation cannot send or resend the order, and stopping at the email dead-ends the request. 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). Legacy product types are also filterable: audio, link, exclusive-image-video, other, request, newsletter, and physical-products. missing_delivery_asset is only raised for digital-products and course. hidden is availability false. Prices are what a buyer is charged. Rename, show, hide, reprice, or replace a plain-text product-page description with set_shop_product. Read the full field contract with get_shop_product. Files are edited in Beacons.

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. There is no store-wide currency, tax, category, shipping, or abandoned-cart setting. 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

Your own Link in Bio traffic for a window (default the last 30 local days): page visits and link clicks over time, plus breakdowns by country, device, referral source and content clicks.

get_traffic_analytics

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. Read this before creating or changing an automation: 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 connected platform (up to 20 from the last 60 days), newest first, each with its thumbnail, content type, caption, available view/like/comment counts, and permalink. Instagram posts also carry the Smart Reply automation already on them; Smart Reply runs on Instagram only, so other platforms come back with none and the reply says so. The post_source field says whether Instagram was checked live. Never call a cached result latest, newest, or today. The instagram_post_id returned here is the only valid id for Smart Reply writes — never construct one from a URL or another tool.

list_creator_platform_posts

Brand mentions by the creators of an organization you manage: the top brands by mention count (limit, default 25, max 100), each with mention/sponsored counts and up to 3 newest posts. Each post includes its publish date, content type, URL, views, likes, comments, shares, saves, and unique reach when Beacons holds those metrics. A null metric is unavailable, never zero. Use these post metrics for recent paid partnership performance; this tool reads the operational content store and does not depend on the eligibility-gated content search index. Rosters routinely mention far more brands than one page holds, so read the truncation flags: brands_truncated means more brands were mentioned in the window than were returned (raise limit), and a brand’s posts_truncated means it has more posts in the window than the ones listed — its mention_count, not the length of its posts list, is the real total. Each post’s is_sponsored is true when either the platform or Beacons marks the post sponsored; false only when both signals are false, and null when no signal is true and at least one signal is unknown. Never infer organic from null. This is the same combined signal search_organization_content documents for its own is_sponsored; filter on is_sponsored = false for organic, not on "not true". sponsored_count only ever counts explicit true rows. Each post carries the manager_creator_profile_id of the creator who published it — group on that, not on platform_username, which repeats across a roster. Filter by creator, brand name, sponsorship, or look-back window (default 365 days).

list_organization_brand_mentions

List the active creators an organization you manage represents, oldest-added first, with their status, assigned manager, intake-form answers, categories, languages, and social accounts (follower counts, connection state, posting volume in the requested activity window, and follower growth). Answers roster-wide questions from one page rather than a call per creator. Optional start_date / end_date (YYYY-MM-DD, inclusive UTC calendar days) set the activity window; omit both to default to the last 30 UTC days ending today. The payload echoes the resolved window as activity_start_date / activity_end_date. Each account's content_count counts ALL posts INCLUDING Instagram stories published in that window, so content_count = 0 is the right test for "is this account dark in this window". engagement_content_count excludes stories and is the comparable cadence figure across platforms. content_count_last_30_days / _90_days and engagement_content_count_last_30_days / _90_days remain the megatable's fixed snapshots and do not follow start_date/end_date. follower_count is read from the FRESHEST first-party record for that account, which is sometimes held by a different Beacons account for the same handle (usually the same person signed up twice); first_party_data_source names which, and null means no first-party record at all. Connection state comes in two sets that answer different questions and legitimately disagree. is_connected / connection_state / state_reason_type / state_reason_timestamp are always this creator’s own login: a null is_connected means this creator has no first-party connection to report, never that another account’s connection failed. The data_source_* copies of those four describe the record follower_count was read from, so they answer "is the data behind these numbers healthy" — they are identical to the own fields on creator_account, describe a different account’s record on other_beacons_account, where both sets can be non-null and disagree, and are all null when first_party_data_source is null. A disconnected own login with a connected data source means the record behind these numbers is still healthy; the reverse means the numbers rest on an unhealthy record even though the creator’s own login works. follower_growth_last_30_days is a FRACTIONAL RATE, not a percentage: 0.05 means 5% growth; it is populated on about 73% of accounts, and null means unknown, never flat. creator_categories / creator_languages are unioned across the creator’s accounts and are a coarser read of the same loosely-held fact as get_organization_creator_info's categories / language, which many creators have not filled in at all; creator_languages holds ISO codes there and free text here. Neither is authoritative — do not treat a missing language as evidence a creator does not speak one. Pass the returned next_cursor to fetch the following page.

list_organization_creators

Rank the creators of an organization you manage against a free-text brief or search query. Returns manager_creator_profile_ids with a relevance score (not comparable across different queries) and the posts used as evidence. Join the ids with list_organization_creators for creator details.

search_organization_creators

Pause or resume one automation. Pausing keeps its keywords, message and all of its stats, so it is the reversible way to turn something off. Pausing a post automation lets any-post automations run on that post again.

set_smart_reply_active

Your own brand deals — the most recently active ones, up to `limit` (default 100, max 250; `truncated: true` means more exist). Call it ONCE with no filters and read the list; nothing is gained by one call per status, and no status called ACTIVE. Statuses are PITCHED, DETECTED, NEW, NEGOTIATING, PRODUCTION, AWAITING_PAYMENT, COMPLETED, DECLINED. Archived deals are left out unless you ask for them, and threads already flagged as not-a-deal never appear. Filter only when the creator asked for a specific subset.

search_brand_deals

Search the indexed social posts of the creators an organization you manage represents. Returns matching posts with engagement metrics, the account they came from, and the manager_creator_profile_id that owns it — group by that id, not by platform_username, which a roster can repeat. That id is null when the handle belongs to more than one roster creator, because the index cannot say which of them posted it; do not attribute those posts. Each post also carries is_sponsored and content_type: is_sponsored is true when either the platform sponsorship flag or Beacons internal classification is true (94.6% populated on first-party rows, 87.4% on scraped), where null means NOT YET CLASSIFIED and never organic — filter on is_sponsored = false for organic, not on "not true". content_type is the platform post type (for example post, reel, story) with casing that varies by source, so match it case-insensitively; use it to drop story rows. Results are ranked by relevance, NOT by date, so this cannot enumerate a posting timeline even with since/until set. The index covers eligible accounts and a rolling window of recent posts, so absence is not proof a post does not exist.

search_organization_content