addAccounts
ChatGPTStart indexing one or more missing brands or creators in Spyglass. Returns each account's id, name, websiteUrl, igUsername, and status (ready or indexing). Use when: - getAccounts cannot find a specific brand or creator the user named, and you have its websiteUrl, igUsername, or both. Inputs: - accounts: 1-20 accounts, each with a name and websiteUrl, igUsername, or both. Omit an unused field instead of sending an empty string. Output: - If an account's status is indexing, call getAccountsIndexStatus with its id until status is ready before calling getMedia, getBrandMediaInsights, getBrandCampaigns, or getBrandLandingPages. Free — does not use credits.
getAccounts
ChatGPTSearch Spyglass brands and creators and return their ids, summaries, and follower/engagement stats. Resolve a brand or creator NAME to an id, then pass that id to getMedia, getBrandMediaInsights, or getBrandLandingPages. mode (required): - ids: set brandIds to UUIDs or numeric platform ids from prior results. count does not apply. - brand_name: set brandNames; OR-matches names (ilike). Pass every named brand in one call, using the user's exact spelling plus a spaced/unspaced variant (e.g. "sototennis", "soto tennis"). If none match, retry with smart. - smart: set query to a self-contained discovery brief with concrete nouns (industry, product type, audience, price tier, region if relevant). Never a single vague token like "competitors". Also use as fallback when brand_name finds no exact match. Optional: type (BRAND or CREATOR; omit to search both), count 1-100 (default 20), offset, minFollowers, maxFollowers, sortBy (NAME | MOST_FOLLOWERS | LEAST_FOLLOWERS | MOST_VIEWS | HIGHEST_ENGAGEMENT | MOST_ACTIVE_ADS). ethnicity, gender, ageRange, location, language filter creators. Put creator geography, language, gender, and age here, not in query. If a filtered smart call returns 0, retry once without the filter.
getAccountsIndexStatus
ChatGPTCheck whether accounts added via addAccounts have finished indexing. Polls twice (30 seconds apart) and returns each account's id and status (ready or indexing). Inputs: - accountIds: 1-20 account UUIDs returned by addAccounts. Output: - Returns immediately when all requested accounts are ready, or after ~30 seconds with each account's current status. If any account is still indexing, call getAccountsIndexStatus again (up to 10 times total). Free — does not use credits.
getBrandCampaigns
ChatGPTGet a Spyglass brand's campaigns or offers. Requires a brandId from getAccounts. Inputs: - brandId: the brand's id. - type: CAMPAIGN or OFFER. - sortBy: MOST_RECENT (default) or HIGHEST_VELOCITY. - limit: 1-100 results, default 10. - dateRange: a preset or startDate/endDate, never both. Filters by campaign start date. last-year is the prior calendar year. Omit for all time.
getBrandLandingPages
ChatGPTGet a Spyglass brand's top landing pages, sorted by how many ads use them. Requires a brandId from getAccounts. Inputs: - brandId: the brand's id. - showInactive: include inactive landing pages too. Set only when the user asks (default false). - limit: 1-100 results, default 100. - offset: skip this many rows before returning the page. Default 0. Output: - total is the number of ads pointing to the url, not traffic, clicks, or CTR.
getBrandMediaInsights
ChatGPTSummarize patterns across a Spyglass brand's media by grouping similar media into hooks, target personas, ad angles, or media mix. Requires a brandId from getAccounts. Inputs: - brandId: the brand's id. - type: HOOK, TARGET_PERSONA, AD_ANGLE, or MEDIA_MIX. - maxDaysBack: 1-90, default 30. Output: - HOOK, TARGET_PERSONA, AD_ANGLE: ranked clusters, each with id, label, tags, and total. Highest total first. - MEDIA_MIX: only format counts (video/image/carousel) across all statuses and platforms in the window.
getCollabs
ChatGPTGet the creators a Spyglass account (a brand or a creator) has collaborated with, ordered from most media to least. Requires an account id from getAccounts. Inputs: - brandId: the account id. - limit: 1-100 results, default 20. - offset: skip this many rows before returning the page. Default 0. Output: - name, profileUrl, and mediaCount (how many of the account's media items tag the creator).
getMedia
ChatGPTRetrieve indexed Spyglass media (Meta ads, Instagram, TikTok). How to query: - Creative search (hooks, scenes, messaging, style): query only. - A known brand: accountId, and no query. - A theme inside a brand: accountId plus query or a landingPage filter. query: a short creative phrase (e.g. "hydrogel mask"). No task, brand names, dates, platforms, formats, or performance constraints. Without an account id it searches the whole corpus. accountId: an id from getAccounts, never a name. Direct filtered retrieval without query requires accountId. filters: only constraints the user asked for. With query, omit category, taxonomy, funnelStage, language, location, and format unless asked. - channel: META_AD is paid; INSTAGRAM and TIKTOK are organic. Use separate calls for organic-versus-paid comparisons. - dateRange: a preset or startDate/endDate, never both. last-year is the prior calendar year; use explicit dates for a rolling 12 months. Omit for all time. - status: META_AD only. Defaults to ACTIVE. For all-time, use ALL with sortBy LONGEST_RUN. - category: a creative format, not a topic. - location: the brand's country (expand regions to country names), not ad targeting. Never combine with accountId. - sortBy: MOST_IMPRESSIONS and LONGEST_RUN need channel exactly META_AD. MOST_LIKES, MOST_COMMENTS, MOST_VIEWS, HIGHEST_ENGAGEMENT, and HIGHEST_OUTLIER are organic only. Never MOST_RECENT for best, top, trending, or viral. With query, sortBy re-ranks toward generic viral posts, so use it only for an explicit ranking and set limit to 50-100. - limit: 100 for corpus semantic search, 20-50 for top-N, 500 for a known brand, 2000 only for exhaustive counts or time series. - offset: omit on the first page. limit + offset must be under 10,000 for semantic search. Each creative includes thumbnailUrl (a preview image you can display inline) and mediaUrl (the full asset). When showing creatives to the user, render the thumbnailUrl images.
searchTaxonomies
ChatGPTSearch Spyglass product taxonomy paths you can pass to getMedia as filters.taxonomy. query: a product or category phrase (e.g. "running shoes"). Returns path strings such as "Apparel > Footwear > Sneakers". limit: 1-50, default 20. Free. Does not use credits.
submitFeedback
ChatGPTReport an MCP/API issue, missing account or creative, documentation mismatch, or agent friction to the Spyglass team. Use when: - A tool call returned unexpected, degraded, or incomplete results, or you hit friction completing the user's request. - Documentation or tool instructions did not match actual behavior. - The user explicitly asks to send feedback or report an issue to Spyglass. Inputs: - category: bug, docs_mismatch, friction, feature_gap, quality_degradation, or other. - note: what went wrong, what you expected instead, and the exact arguments/filters/payloads you passed to the relevant tool calls (e.g. accountId, brandId, query, mode, filters) (1-4000 chars). - tool: optional name of the Spyglass tool involved (e.g. "getMedia", "getAccounts"). - url: optional URL or resource the feedback is about (e.g. a brand website, social profile, or docs page). Output: - Returns feedbackId. Free — does not use credits.