create_aspect_group
ChatGPTCreate a new aspect group. Create custom aspect group with inclusion and exclusion rules. The create_aspect_group tool creates a new aspect group with specified filters. Use it to define custom content collections based on inclusion and exclusion criteria. When to Use Use create_aspect_group only when: - User wants to create a new aspect group for specific aspect like campaign, author, tag etc. with specific include, exclude filters. When NOT to Use - If the user wants to list, view, create, or delete groups, do not use this tool. Use list_aspect_group, get_aspect_group, update_aspect_group, or delete_aspect_group respectively instead. Examples User wants to create a campaign group: User: "Create a new campaign group "Paid" that selects medium to be any of "ad" and "paid_search", but excludes any that have source "google"." ``json { "body": { "name": "Paid", "group_type": "campaign", "filters": [ {"field": "medium", "condition": "any", "values": ["ad", "paid_search"]}, {"field": "source", "condition": "exclude", "values": ["google"]} ] } } ``
create_goal
ChatGPTCreate a goal. Set a target for a metric over a repeating period, optionally scoped by filters. The goal then reports its live pace through list_goal. The create_goal tool sets a target for a metric over a repeating period, optionally scoped by filters. Once created, the goal reports its live pace through list_goal. Important: A goal's target is measured over each period from scratch — period: "monthly" with goal: 200000 means 200,000 every month, not 200,000 in total. Important: Filters use the flat filter vocabulary (any_author, exclude_section, page_type, ...), not the stored condition format. Use author, section and tag values returned by list_author, list_section and list_tag: a value that is not indexed produces a goal that counts nothing rather than an error. When to Use Use create_goal only when: - The user wants to start tracking a new target for a metric. - The metric, the target value and the cadence are known or can be confirmed with the user. When NOT to Use - If the user wants to see existing goals or their pace, use list_goal. - If the user wants one goal's history, use get_goal. - If the user wants to change an existing goal, use update_goal. - Goals cannot be deleted through a tool; direct the user to the dashboard. Examples User wants a site-wide monthly views goal: User: "Set a goal of 200,000 views a month." ``json { "body": { "name": "Monthly views", "metric": "views", "period": "monthly", "aspect": "site", "goal": 200000 } } ` **User wants a goal scoped to a section:** User: "Track 50,000 views a month in the News section, excluding opinion." `json { "body": { "name": "News views", "metric": "views", "period": "monthly", "aspect": "site", "goal": 50000, "any_section": ["News"], "exclude_section": ["Opinion"], "page_type": "post" } } ` **User wants a conversions goal:** User: "We want 500 subscriptions this quarter, last-touch." `json { "body": { "name": "Quarterly subscriptions", "metric": "conversions", "period": "quarterly", "aspect": "site", "goal": 500, "attribution_type": "last_touch", "conversion_type": "subscription" } } ``
delete_aspect_group
ChatGPTDelete a specific aspect group as indicated by the primary key. Permanently remove content groups and their associated filters. The delete_aspect_group tool permanently removes an aspect group and all its associated filters. Important: This endpoint requires the numeric group ID. If user specifies a group name, first call tool list_aspect_group to find the ID and then call this tool. Important: This action is irreversible and destructive. Do not use without explicit user confirmation of the destructive action. When to Use Use delete_aspect_group only when: - User explicitly requests or confirms the permanent deletion of a specific aspect group and all its filters. - The ID of the group to update is provided by the user or known from a previous operation. When NOT to Use - If the user wants to list, view, create, or update groups, do not use this tool. Use list_aspect_group, get_aspect_group, create_aspect_group, or update_aspect_group respectively instead. Examples User wants to delete a group with known ID: User: "Delete group 15 permanently" ``json {"path_params": {"pk": 15}} ``
get_aspect_group
ChatGPTGet a specific aspect group as indicated by the primary key. Examine detailed filters and criteria for a specific aspect group. The get_aspect_group tool retrieves detailed information about a specific aspect group by ID. Important: This endpoint requires the numeric group ID. If user specifies a group name, use tool list_aspect_group instead of this. When to Use Use get_aspect_group only when: - User asks for details about a specific aspect group. - The ID of the group to update is provided by the user or known from a previous operation. When NOT to Use - If the user wants to list, create, update or delete groups, do not use this tool. Use list_aspect_group, create_aspect_group, update_aspect_group, or delete_aspect_group respectively instead. - Even for viewing a single group, unless you have the numeric ID, do not use this tool. Examples User wants to know more about a group with known ID: User: "Explain what aspect group ID 8 selects" ``json {"path_params": {"pk": 8}} ``
get_campaign
ChatGPTGet timeline data for a specific campaign value. Return the historical or pulse timeline for a single campaign value. The campaign value (utm_value, e.g. 'paid-revops') is supplied as a path segment (/jess/campaigns/<utm_value>/). utm_key selects the UTM dimension — one of id, source, medium, content, term, or group — and is passed as a query parameter. When no time window is supplied, the timeline defaults to the last 7 days of historical data (interval=1d), so the tool works with just utm_key + utm_value. To override, pass interval + start for a custom historical range (end defaults to today), or minutes for a live pulse window. The timeline is bounded by the window you ask for: start/end set its first and last day, and minutes its length back from now. The timeline always plots views; there is no metric to choose.
get_goal
ChatGPTReturn the period-by-period history for a single goal. Answers "show the month-by-month history of this goal." Returns the goal's historical results grouped by its period granularity (daily/weekly/monthly/quarterly) — one row per elapsed period with start, end, the metric count, and completed (the date the cumulative count first hit the target, else null). Use list_goal first to find a goal's id (e.g. a behind-pace goal), then this tool for its full trajectory.
get_parsely_usage
ChatGPTGet how the site's team uses Parse.ly itself, over the last 30 days or a month window. Covers dashboard adoption (active users, pageviews, visits, top users and screens), reports run, and Parse.ly API requests per endpoint. Measures usage OF Parse.ly by the site's team — not the site's audience. Use it for adoption and seat-usage questions like "how many people use the dashboard?", "who are our most active users?", "which reports do we run?", or "how much do we call the API?". The default window is the last 30 days. Pass start/end (YYYY-MM) to report whole calendar months instead, which unlocks year-over-year and any multi-month window. Every response carries available_months (the earliest and latest month with data for this site); read it to pick a valid start/end rather than guessing. Only site admins can call it. Totals always cover the whole site; the optional filters narrow the listings only. Parse.ly dashboard usage: how the site's own TEAM uses Parse.ly — who logs in, which dashboard areas and screens they open, which reports they run, how heavily they hit the API. This is adoption and seat usage, NOT the site's audience or its content. "Dashboard usage", "usage of the Parse.ly dashboard" and "how much do we use Parse.ly" all mean this tool. When to use - "What's our Parse.ly dashboard usage?", "how much is the dashboard used?" - "Which areas/screens of the dashboard do people use the most?", "most popular areas in the dashboard" - "What are our most-run reports?" - "Who has logged in the most/least in the last month?", active versus dormant seats - Seat and license questions — is the team actually using its access? - "How much do we call the Parse.ly API?" — request counts per endpoint Windows — historical months - The default window is the last 30 days. - For a named or past month, pass start/end as YYYY-MM. February 2026 → start=2026-02, end=2026-02. Multi-month and year-over-year work the same way. - Each response carries available_months (earliest and latest month with data); read it to pick a valid window. Not this tool if - The site's AUDIENCE or CONTENT — "top posts/authors/sections", "most-read articles", "where does our traffic come from?" → query_top_content, query_top_aspect, query_referrers. Watch the wording: "areas/screens of the DASHBOARD" is this tool; "top pages/content of the SITE" is not. Traps to avoid - Admins only. A non-admin caller gets a 403 — do not retry; tell the user they need admin access.
get_site_overview
ChatGPTGet the key analytics numbers shown on the Parse.ly dashboard homepage. Returns current_period stats (views, visitors, engaged minutes for the selected period), a previous_period comparison with weekday and overall rank, and (for today without filters) a 4-week rolling average comparison. Use this to answer questions like "How are we doing today?", "How did we do this week?", or "What was special about yesterday?". Reports on a single period — one of today (default), this_week, or this_month. The metric selects the headline number: views (default, always available), a compound conversion metric like conversions--last_touch--any (requires the conversions feature), or starts (video starts, requires the video feature). Optional aspect filters (overview_section, overview_author, overview_tag, overview_campaign_group) scope every number to that slice. Returns key metrics for the current period, a previous-period comparison (with weekday and overall rank), and — only for unfiltered today — a 4-week rolling average comparison. For "what was special about yesterday?" or "anything unusual?", read it as: was the period anomalous versus a typical day — answer from the weekday/overall rank and the 4-week average rather than treating it as a news question, and say plainly when it was just a normal day.
get_user
ChatGPTGet profile information about the logged-in user. Returns the user's email and permission levels (staff, admin) in Parse.ly. Returns the currently logged-in user's own profile — email, and Parse.ly staff/admin permission flags. Single entity, not a listing; takes no parameters. When to use - "Who am I logged in as?", "what's my email?", "am I a staff/admin user?" Not this tool if - Asking about a teammate or any other account user — this returns only the caller's own profile; there is no user-listing tool.
list_aspect_group
ChatGPTGet a list of aspect groups. Discover and explore aspect groups to understand site organization. The list_aspect_group tool retrieves all aspect groups for the current context. Use it to discover all aspect groups and to find group IDs needed for other operations. When to Use Use list_aspect_group when: - User wants to see information about multiple or all groups of a specific type. - User wants to get number of groups of a specific type. - User wants to operate on a specific group by name so this tool can be used to find group IDs before calling get_aspect_group, update_aspect_group, or delete_aspect_group. When NOT to Use - If the user wants to create, update or delete groups, do not use this tool. Use create_aspect_group, update_aspect_group or delete_aspect_group respectively instead. Examples User asks about number of campaign groups: User: "How many campaign groups do I have?" ``json {"query_params": {"group_type": "campaign"}} ` **User asks about a specific tag group by name:** User: "Explain what the "Tech reviews" tag group selects." `json {"query_params": {"group_type": "tag"}} ` **User asks about all author groups:** User: "List all my author groups." `json {"query_params": {"group_type": "author"}} ``
list_author
ChatGPTGet a list of all authors. Get a list of all authors. Optionally, filter the list by querying by name. The search_author tool finds authors whose names match a keyword query. When to Use - User asks to find a specific author - User wants to search for authors by name - User needs to discover authors writing about a topic When NOT to Use - User wants to see top authors by metrics (use list_post with author filters) - User wants to search for posts (use search_post) Response structure Returns paginated results with total_results (total matches), has_more (whether more pages exist), and results array where each item has an author field with the author name. Examples User asks to find an author: User: "Find authors named John" ``json {"query_params": {"q": "John", "per_page": 10}} ``
list_goal
ChatGPTList a publisher's goals with live progress (active) or historical results (past). Answers "are we on track to hit our goals this month?", "which goals are behind pace?", and "how did our goals end up last quarter?". Use period=active (default) for each goal's live progress against its current period: current (count so far), progress_percent (vs target), pace (>1 ahead, <1 behind), pace_count_delta, current_if_on_pace, and period_left/period_left_unit. Use period=past for the historical per-period results of ended periods: each row carries the period start/end, the count, and completed (when the target was first met, else null). Each goal has its own stored metric (views/visitors/avg_engaged/posts/conversions/...), aspect, and filters. Filter the listing with aspect (site/post/author/section/tag) or goal_ids; sort with sort (e.g. end-des, metric-asc). Paginate with page/per_page (default 9) or limit. For a single goal's full month-by-month history, use get_goal.
list_section
ChatGPTGet a list of all sections. Get a list of all sections. Optionally, filter the list by querying by name. The search_section tool finds content sections matching a keyword query. When to Use - User asks to find a specific section - User wants to search for sections by name - User needs to discover what sections exist on the site When NOT to Use - User wants to see top sections by metrics (use list_post with section filters) - User wants to search for posts within a section (use search_post) Response structure Returns paginated results with total_results (total matches), has_more (whether more pages exist), and results array where each item has a section field with the section name. Examples User asks to find a section: User: "Find sections related to technology" ``json {"query_params": {"q": "technology", "per_page": 10}} ``
list_segment
ChatGPTList the site's audience segments — the configured catalog, not a traffic ranking. Answers "which audience segments exist?". Returns every active segment configured for the apikey — including segments with no traffic in any window — each with its id (the value the sid filter accepts) and display name. Optional name narrows the list by case-insensitive substring. Apikey-scoped: a publisher or group scope returns a 400. To rank segments by traffic instead, use query_top_aspect with aspect=segments.
list_site
ChatGPTGet a list of all sites (API keys) organised under publishers and site groups. Discover all sites and publishers you have access to in a hierarchical structure. The list_site tool retrieves all sites (API keys) that the user has access to. Use it to discover the hierarchical organization of publishers, site groups, and individual sites. When to Use Use list_site for questions about site access and organization: - User asks about what sites they have access to - User wants to see their publishers or site groups - User needs to understand their account structure - User asks about network organization or site hierarchy - User wants to explore available sites before querying analytics When NOT to Use Use analytics tools instead for: - User wants to query actual site data or performance metrics - User asks about content, traffic, or analytics data Response structure The response will be an object containing a "publishers" field, which is a list of publishers. Each publisher object contains its associated site groups and sites. Each site carries a data_available_since date (ISO YYYY-MM-DD): the earliest date that site has data for. Use it to anchor relative dates — bound "all time" or "since launch" windows and sanity-check ranges like "last 90 days" against when the site's data actually starts. Examples User asks about site access: User: "Which sites do I have access to?" ``json {} ` **User asks about publisher access:** User: "Which publishers can I access?" `json {} ` **User asks about site access with specific filters:** User: "If ordered alphabetically, which would be the last 3 sites I have access to?" `json {} ``
list_tag
ChatGPTGet a list of all tags. Get a list of all tags. Optionally, filter the list by querying by name. The search_tag tool finds content tags matching a keyword query. When to Use - User asks to find a specific tag - User wants to search for tags by name - User needs to discover what tags are used on the site When NOT to Use - User wants to see top tags by metrics (use list_post with tag filters) - User wants to search for posts with a tag (use search_post) Response structure Returns paginated results with total_results (total matches), has_more (whether more pages exist), and results array where each item has a tag field with the tag name. Examples User asks to find a tag: User: "Find tags related to sports" ``json {"query_params": {"q": "sports", "per_page": 10}} ``
query_apple_discovery_source
ChatGPTRank the Apple News Discover feeds/channels that sent traffic, by views. Apple News Discover is a distinct traffic source, separate from the regular referrer categories (social, search, etc.). Use this to answer "which Discover feeds sent us the most traffic?". Pass one of the returned source values as discovery_source to query_referrer_urls (with source='apln-rta') to see which posts it drove traffic to.
query_campaigns
ChatGPTLook up top campaigns by metric for one UTM dimension, with explicit pagination. Rank campaigns by an engagement metric (metric, default views; also visitors, engaged time, …) for a UTM dimension (source, medium, id, content, term, or group). Set utm_key to choose the dimension and paginate with page/per_page: the response carries has_more so you know when to fetch the next page. Omit utm_key to get the top campaigns for every dimension at once (as a map keyed by UTM type, without a single page cursor). When no date window is given, defaults to the last 7 days (interval=1d). Ranks acquisition-wide traffic by default (every landing page, page_type=any); pass page_type=post to count only editorial post pages. Per-entry historical sparklines are omitted by default; pass no_sparklines=false to include them (large responses). For finding a campaign by name rather than ranking, use search_campaign. Ranks campaign VALUES by an engagement metric, grouped by one UTM dimension. PERFORMANCE, not discovery. When to use - "Top campaigns this week", "which source/medium drives the most engagement?", "how is campaign X performing?" (once you have its exact value) Not this tool if - Finding a campaign by name, or checking whether one exists → search_campaign (no metrics, name-based lookup) Needs first A campaign value returned by search_campaign — resolve it there first if you only have a rough name. A value that is not indexed returns an empty result, not an error. Traps to avoid Silent defaults — the trap A window the user didn't name is not a reason to ask: default to a recent window — the tool's own stated default, or about the last 7 days if it names none — state the window used, and answer; never ask them to pick one. The reverse is the trap: send neither mode and the server defaults silently (200), so a wrong window (30-day question, 7-day data) fails with no error. Each tool states its own default. - utm_key picks the dimension grouped on (source, medium, id, content, term, or group). Omit it to get the top campaigns for every dimension at once, returned as a map keyed by UTM type rather than a single ranked list — no single page cursor in that shape. - Defaults to the last 7 days, not the site-wide overview's single-day default — totals from this tool and get_site_overview will not reconcile unless both calls use the same explicit start/end.
query_conversions
ChatGPTRank conversion labels by a conversion metric, with explicit pagination. Return the top conversion labels (subscription, newsletter signup, purchase, …) ranked by a conversion metric — conversions (default), converting_visitors, converting_visitors_rate or referrers_conversions — for a time range and the usual content filters (section, author, tag, channel, campaign, referrer). Each entry carries its conversion count, converting visitors and the number of associated posts. conversion_type_data gives the per-type aggregate totals. Choose the attribution model with attribution_type (last_touch default, first_touch/linear/last_post_touched); set all_models=true to get data for each attribution model (slower: it fires four extra ranking queries). Paginate with page/per_page; the response carries has_more. When no date window is given, defaults to the last 7 days (interval=1d). Requires conversion tracking to be enabled for the site. Ranks conversion labels (subscription, newsletter signup, purchase, …) by a conversion metric, with per-type aggregate totals. When to use - "Which conversions/signups performed best?", "top converting content", "conversion rate for <label>", "how many people converted this week?" Not this tool if - A specific page's conversions → query_post_detail - Ranking by an engagement metric instead of conversions → query_top_content Needs first An exact conversion label (from a prior call's conversion_label field) to scope other tools to it — pass it back verbatim, it's case-sensitive. Traps to avoid Silent defaults — the trap A window the user didn't name is not a reason to ask: default to a recent window — the tool's own stated default, or about the last 7 days if it names none — state the window used, and answer; never ask them to pick one. The reverse is the trap: send neither mode and the server defaults silently (200), so a wrong window (30-day question, 7-day data) fails with no error. Each tool states its own default. - Rank metric defaults to conversions; choose converting_visitors, conversion_rate, converting_visitors_rate or referrers_conversions with metric. - attribution_type defaults to last_touch (first_touch/linear/last_post_touched also available); all_models=true adds a per-model breakdown but fires four extra ranking queries — slower. - Defaults to the last 7 days when no window is given. Paginate with page/per_page; the response carries has_more. - Requires conversion tracking to be enabled for the site.
query_headline_tests
ChatGPTList the site's headline A/B experiments — id, title, status, dates, totals and winner. Return a slim listing of the site's headline-optimization experiments — each with its id, title, status, start/end dates, aggregate impressions/clicks/CTR and the winning headline — plus account-wide aggregate counters (in_progress, completed, variants_won, original_won). This shape is small enough that every test of a site fits in one page, so you can rank them client-side (there is no server-side impressions/CTR sort). For the target url plus per-variant headline text and stats, pass include=variants; omit it for the slim shape. Filter with status (free text, e.g. 'Running'/'Completed'/'Scheduled'), search (free text), created_by (creator user ids), and created_at_gte (ISO 'YYYY-MM-DD' date). Order with order_by (the field name to sort by, e.g. 'createdAt') and order (direction, ASC or DESC, case-insensitive). Paginate with page/per_page (defaults to 20 per page); the response carries has_more. Requires the Headline Tests feature and read access for the account. Lists the site's headline A/B tests — a slim row per test (id, title, status, start/end dates, aggregate impressions/clicks/CTR and the winning headline) plus account-wide aggregate counters (in_progress, completed, variants_won, original_won). When to use - "Show our headline tests", "which headline experiments are running/completed?", "did the variant beat the original for <test>?" - "Which test had the most views?" — the dashboard labels a variant's impressions "Total views", so a views / impressions / clicks / CTR question about a test, an experiment, a variant or a headline belongs here, not in a generic analytics query. - Wording / word-choice analysis of tested headlines — "do question headlines win?", "which words drove clicks?", "are winning variants shorter?": the raw headline text IS accessible. Pass include=variants and read each variant's value (its headline text) alongside its stats, then analyze the phrasing yourself. Never claim the headline text isn't available. Not this tool if - Post-level metrics unrelated to a headline experiment → query_post_detail or query_top_content. The user wanting traffic for the ARTICLE that was tested (its page views, referrers, engagement) → query_post_detail with the target's canonical_url: a test's "views" and the article's page views are different numbers. Traps to avoid - Data comes from the external VIP Experiments API, not ES/Mage — there is no traffic window (start/end/minutes do not apply); filter by created_at_gte instead. - "Views" here are impressions of a headline variant, not page views. Ranking tests "by views" means ranking by impressions. Stats are lifetime per test — created_at_gte picks which tests come back; it does not re-window their numbers. - Requires the Headline Tests feature enabled and read access for the account, or the call fails outright — not an empty list. - in_progress / completed / variants_won / original_won are account-wide counters, not the size of this page. The page holds len(experiments); read total_results and has_more for the rest. - Nothing ranks by impressions or CTR server-side. order_by/order sort the listing by an experiment field (e.g. createdAt), never by a stat. To answer "the most views" you must read every test and rank them yourself: send limit=100 (one request, page/per_page null) rather than paging with per_page, which costs a request per page. 100 is a hard ceiling — the upstream rejects more. Ranking a single default page — 20 tests, ordered by recency — yields a confidently wrong #1. - The listing is slim by default (id, title, status, dates, aggregate impressions/clicks/CTR, winner). For the target url plus per-variant headline text and stats, pass include=variants. - Filter with status (free text), search (free text), created_by (creator user ids), created_at_gte (ISO date). Sort with order_by/order. - Paginates with page/…
query_post_detail
ChatGPTRetrieve full analytics detail for a single post by its canonical URL. Answers "How did this article do?" for a given URL. Supply canonical_url as a required query parameter. Optionally specify a date window (start/end + interval=1d for historical, or minutes for pulse); when no window is supplied, the last 7 days of historical data are returned automatically. The response includes: - post: article metadata (title, authors, section, tags, pub_date). - selectionStats: total views, visitors, engaged_minutes, shares (+ device breakdown: desktop/mobile/tablet views). - timeline: time-series view data ([[timestamp, views], ...]). - referrers: self-referral category breakdown. - visited_next: pages visited after this one (recirculation) with referral view counts and a recirculation_rate. - aliases: other URLs that serve the same content (AMP, trailing-slash variants, etc.). - social: social share counts and referral views by network. Not included (separate tools / out of scope): - Per-referrer-domain URL breakdown (a separate referrer-urls endpoint). - Video analytics (grant_data_video). - Network/apikey-group syndication aggregation. - Headline tests. Detailed metrics for ONE page — any page, not just posts (works for landing pages, pricing pages, the homepage). When to use - "How did <specific article/page> do?" - "Where do people go AFTER page X?" / "what do they read next?" → read visited_next - "Mobile vs desktop for page X?" → read selectionStats (the ONLY place this exists) Not this tool if - The user asks where traffic CAME FROM → query_referrers (inbound; this tool's visited_next is OUTBOUND) - The user wants a ranking of many pages → query_top_content Needs first canonical_url — resolve it with search_post (articles) or search_other_page (pricing, landing, checkout, about). Never guess a URL. Traps to avoid Silent defaults — the trap A window the user didn't name is not a reason to ask: default to a recent window — the tool's own stated default, or about the last 7 days if it names none — state the window used, and answer; never ask them to pick one. The reverse is the trap: send neither mode and the server defaults silently (200), so a wrong window (30-day question, 7-day data) fails with no error. Each tool states its own default. - visited_next is NOT "the next page in the session" — it is pages that recorded THIS page as their internal referrer. It answers "where do people go next?". - This is the ONLY way to get referral-by-source-URL: the referrer filter elsewhere is domain-level.
query_realtime
ChatGPTGet a real-time snapshot of what's happening on the site right now. Returns a live pulse snapshot of site activity for the requested window (default: today from midnight to now). Key fields: - visitors: concurrent/active unique visitors (HLL count) — the realtime "concurrents" metric. Shows who is on the site right now. - views: total page views in the window. - engaged_minutes: total engaged time in the window. - top_posts: top pages ranked by the primary metric (default: views). - referrers: where traffic is coming from — per-category totals (social/search/internal/other/direct) and top referring domains. - window: the time window this snapshot covers ({from, to, minutes}). - geo (optional): geographic breakdown by country/subdivision/city. Pass include_geo=true to request it. Geo data is day-granularity only (the UA API does not support sub-day windows) and is available only to staff/superuser accounts. Geo is null for all other users. Use minutes=30 for a 30-minute pulse, minutes=today (default) for the full publisher day. Combine with any_author, any_section, or any_tag to scope the snapshot to a specific content segment. Live pulse snapshot of what's happening on the site right now — concurrent visitors, views, engaged minutes, top pages, and referrer breakdown for a short window. When to use - "Who's on the site right now?", "concurrents", "real-time traffic", "what's trending in the last 30 minutes?" Not this tool if - Historical trend over days/weeks → query_traffic_trend - A ranking of many pages over a normal (non-pulse) window → query_top_content Traps to avoid Silent defaults — the trap A window the user didn't name is not a reason to ask: default to a recent window — the tool's own stated default, or about the last 7 days if it names none — state the window used, and answer; never ask them to pick one. The reverse is the trap: send neither mode and the server defaults silently (200), so a wrong window (30-day question, 7-day data) fails with no error. Each tool states its own default. - Defaults to minutes=today (the full publisher-local day so far) when neither minutes nor interval is given. - top_limit controls how many top pages come back (default 10, max 50). - include_geo=true adds geo breakdown, but it's day-granularity only and available only to staff/superuser accounts — null for everyone else. - Scope to a content segment with any_author/any_section/any_tag.
query_referrer_url
ChatGPTList the individual referring URLs for a single referrer source (source). Drill into one referring source to see the specific URLs that sent traffic, ranked by the requested metric (views or conversions). Scope to a subject by passing the same filter params the listings use — canonical_url for a post, author/section/tag, channel, or campaign UTM params. Answers questions like "which pages on twitter.com drove views to this post?". Apple News Discover mode: pass source='apln-rta' and discovery_source (a feed/channel label from query_apple_discovery_sources) to get the posts that feed sent traffic to instead of URLs.
query_referrers
ChatGPTQuery referring traffic sources by domain, category, and metric. Understand where your audience is coming from. Returns the top referring domains ranked by an engagement metric (metric: views default, or conversions) with a breakdown by referrer category (social, search, internal, direct, etc.). Use this tool to answer questions like "Where is traffic coming from?", "Which social network drives the most views?", "What changed in referrer traffic?" or "How much search traffic did we get last week?". When no date window is given (no interval, minutes, start, or end), defaults to the last 7 days (interval=1d). Each response includes per-category totals (total metric value and the leading domain for that category) and a ranked list of top referring domains. Paginate with page/per_page; has_more signals whether more pages exist. Set category to restrict top_keys to one referrer category. Set canonical_url to scope results to a single post and bypass the 31-day date-range guard (referrers data is otherwise limited to 31-day windows). Pass compare_start and compare_end (YYYY-MM-DD) to get period-over-period comparison data. When supplied, each entry in categories and top_keys gains three extra fields: previous_value (metric in the comparison period), change (current - previous), and change_pct (percentage change, or null when previous_value is 0). The response also includes has_comparison: true and comparison_window echoing the comparison date range. Use this to answer "what referrers changed?" — which categories or domains grew or shrank. Where a site's (or one page's) traffic CAME FROM — referrer categories and domains. INBOUND only. When to use - "Where is our traffic coming from?", "top referrers", "how much from social/search?" - With canonical_url: sources for one specific page Not this tool if - "Where do people GO after page X?" → that is OUTBOUND: query_post_detail → visited_next. Calling query_referrers for that question answers the OPPOSITE direction and is confidently wrong. - "Which of OUR OWN pages send traffic to page X?" → query_referrer_url - Filtering another query by source URL → impossible; referrer filters are domain-level. Route via query_post_detail(canonical_url=...) → visited_next. Traps to avoid - Without canonical_url, a window longer than 31 days returns an EMPTY top_keys plus a warning — it does not error. Pass canonical_url to bypass the guard.
query_sites
ChatGPTReturn a network's member sites ranked by a metric, with filters and pagination. Answers "what are the top sites in my network?", "which properties drove the most engaged time this week?". Pass a network/group slug (e.g. example-group) as the api_key to rank every site in that network; a single site domain ranks just that site. Ranks by the chosen metric (default views) over a time range, filterable by section/tag/author/referrer. Real-time via minutes; historical via start/end. Each row has the site, its metric_value, and views/visitors/engaged_minutes/ posts. Defaults to 15 per page; use limit or page/per_page (has_more signals more pages).
query_top_aspect
ChatGPTReturn the top-ranked values for one aspect: authors, sections, tags, channels, or segments. Set aspect to pick which one. To compare more than one aspect (e.g. "top authors AND top sections this week"), call this tool once per aspect — it is cheap and each call is independent. Ranks by the chosen metric (default views) over a time range, filterable by author/section/tag/referrer (a filter naming the same aspect you're ranking is ignored). Time range is either real-time (minutes) or historical (start/end with interval one of 1d/1w/1M); the two modes are mutually exclusive. If you pass none of minutes/interval/start, it defaults to the last 1 day (interval=1d). Each row has the aspect value, the aggregate metric_value, the posts count, and context1_value/context2_value — the two secondary metrics named in the response's metric.context1/context2 (ranking by engaged_minutes also gives you visitors and avg_engaged per row, so there is no need to re-rank to get them). Defaults to the top 10; use limit or page/per_page (has_more signals more pages). Per-aspect quirks: - tags: smart controls which tag kinds are included (site/general/entity/all/etc.); omit it to use the apikey's saved smart-tag display preference. - segments: apikey-scoped only (400 for a publisher/group scope). Each row's id is the audience segment id — filter with it via sid, not the display value. - channels: the metric is locked to views (or video starts when content_type=video) for parity with the dashboard — any metric you pass is ignored. Requires the channels feature (grant_data_channels); without it the tool returns 403. Each row's raw id is the channel key — filter with it via channel, not the humanized display value. Ranks the values WITHIN one aspect — top authors, top sections, top tags, top channels, or top segments — by a metric. When to use - "Top authors/sections/tags this week", "which channels drive the most traffic?", "most engaged audience segments" - A single aggregate total for one tag/section/author (e.g. "how many views did tag:X get yesterday") — one row gives the summed metric_value; do NOT sum query_top_content rows for a total, that list is a truncated top-N - Comparing more than one aspect (e.g. "top authors AND top sections") — call this tool once per aspect; each call is independent and cheap Not this tool if - Ranking posts themselves (not the authors/sections/tags they belong to) → query_top_content - Which authors/sections/tags exist at all, not a ranking → list_author / list_section / list_tag - Where traffic came from → query_referrers Traps to avoid Silent defaults — the trap A window the user didn't name is not a reason to ask: default to a recent window — the tool's own stated default, or about the last 7 days if it names none — state the window used, and answer; never ask them to pick one. The reverse is the trap: send neither mode and the server defaults silently (200), so a wrong window (30-day question, 7-day data) fails with no error. Each tool states its own default. - One aspect per call — there is no "all aspects at once" mode. - channels locks the metric to views (or starts for video); any metric you pass for it is ignored, and it needs the grant_data_channels feature or the call returns 403. - segments is apikey-scoped only — a publisher/group scope 400s. Each row's id is the filterable segment id; value is display-only. - For authors/sections/tags, value IS the exact filter value (id is null) — case-sensitive, so resolve it with list_author/list_section/list_tag first rather than guessing.
query_top_content
ChatGPTReturn the top-ranked posts or videos by a metric, with filters and pagination. The workhorse "top content" query — answers "top stories this week", "best posts in the news section", "top videos right now". Ranks pages (content_type=post, the default, ranked by views) or videos (content_type=video, ranked by starts) over a time range, filterable by section/author/tag/referrer. Time range: pass minutes (e.g. today) for real-time/pulse, or start/end with interval=1d for a historical window (up to 31 days). When no window is supplied it defaults to the last day. Choose the ranking metric with metric (e.g. views, engaged_minutes, visitors, shares). Defaults to the top 10. Use limit for a single top-N, or page/per_page to paginate; has_more signals whether more items exist. Each entry includes canonical_url, title, authors, section, tags, pub_date, the ranked metric_value, and context1_value/context2_value — the two secondary metrics named in the response's metric.context1/context2 (ranking by engaged_minutes also gives you visitors and avg_engaged per row, so there is no need to re-rank to get them). Ranks pages or videos by a metric — best/top/most-read posts, top videos right now. When to use - "Top stories this week", "best posts in the news section", "most-read posts today" - "Top videos right now" → content_type=video - Ranking many pages by a metric, filtered by section/author/tag/referrer - Trending a section/tag/author over time — call with interval=1d/1w and consecutive start/end; query_traffic_trend is site-wide only, so this is how you trend a filtered slice Not this tool if - One specific page or article → query_post_detail - Top authors/sections/tags/channels themselves (not the posts within them) → query_top_aspect - A single summed total for a tag/section (e.g. "how many views did tag:X get") → query_top_aspect; summing these ranked rows undercounts, because the list is a truncated top-N, not the whole set - Where traffic came from → query_referrers Needs first Filtering by author, section, or tag needs an exact, case-sensitive value — resolve it with list_author/list_section/list_tag first. Never guess a name; an empty result means a wrong value, not zero posts. Content filters & ordering Beyond the aspect filters, this tool can shape the set and the order: - Worst / bottom-N ("least-read", "underperforming"): reverse_order=true ranks ascending. - Include low-traffic posts in a normal ranking: show_cutoff=true (keeps rows below the statistical cutoff). - Evergreen content: lifecycle=evergreen (or evergreen candidate). - Video presence: with_video=yes / no. - Length: word_count as min-max or min- (e.g. 1500-). - URL / title narrowing: path / exclude_path, all_title / exclude_title, canonical_url. "Lowest performing" — answer, don't ask For "lowest performing" / "worst" / "underperforming", don't ask the user to pick a benchmark — choose the reading that fits and say which you used: - Absolute floor: the truly worst are zero-metric rows — reverse_order=true. - Weakest meaningful content: when the zero-view tail is just stale/expired pages, use reverse_order=true by views and start a few rows in. Default to the second for "which of my stories underperformed", state the definition, and offer the other (or rank by engaged time, or compare against the section median). Most popular word count / content-length distribution Each ranked item carries full_content_word_count, so answer "most popular word count", "which article length performs best", or a length-distribution question from ONE call — never punt or ask the user to pick ranges. Pull a large sample for the period (content_type=post, limit 100+), then bucket the returned rows yourself by full_content_word_count (default 0–499 / 500–999 / 1000–1499 / 1500–2999 / 3000+): - Skip rows whose full_content_word_count is 0 or null — videos, landing pages a…
query_traffic_trend
ChatGPTQuery the site-level traffic trend as a time series. Return the traffic timeline for a site (all content combined) bucketed by the requested interval. Use this tool to answer questions like "How is traffic trending this month?", "Compare this week vs. last week", or "Is February up or down year-over-year?". Intervals: interval=1d (daily), interval=1w (weekly), interval=1M (monthly) for historical data. For real-time / pulse data, use minutes=<N> (e.g. minutes=today for today so far, minutes=60 for the last 60 minutes). Pulse and historical are mutually exclusive. Aspect: aspect=post (default, page views), aspect=video (video starts), aspect=conversion (conversion events). Date range: Supply start and end (YYYY-MM-DD) with interval for historical. Omit for a default 30-day window. Month-over-month / period comparison: Supply compare_start and compare_end to receive a second comparison_timeline alongside the primary timeline for direct period-over-period comparison. Site-wide traffic as a time series — is traffic trending up or down, this week vs last week, this month vs last year. When to use - "How is traffic trending this month?", "is traffic up or down?" - "Compare this week vs. last week" → compare_start/compare_end - Real-time / today-so-far → minutes Not this tool if - One specific page's trend → query_post_detail (its timeline) - A ranking of many pages, or a trend scoped to an author/section/tag → query_top_content with an interval instead - "How are we doing overall" (a snapshot, not a series) → get_site_overview Traps to avoid Silent defaults — the trap A window the user didn't name is not a reason to ask: default to a recent window — the tool's own stated default, or about the last 7 days if it names none — state the window used, and answer; never ask them to pick one. The reverse is the trap: send neither mode and the server defaults silently (200), so a wrong window (30-day question, 7-day data) fails with no error. Each tool states its own default. - Accepts NO author/section/tag/channel filters — they are silently ignored, and the response still reports site-wide numbers. A filtered-looking call that answers with unfiltered totals is a fabrication trap; check the response's warning field. - minutes (pulse) and interval/start/end (historical) are mutually exclusive. - Defaults to the last 30 days when no window is supplied.
search_campaign
ChatGPTSearch campaign values by name across one or all UTM dimensions. Discovery endpoint (no metrics): find campaign values, e.g. "do I have a campaign named X?". Omit utm_key to search every dimension. No date range — uses a fixed internal discovery window. For campaign performance, use query_campaigns instead. Finds campaign VALUES by name. DISCOVERY, no metrics — "does a campaign named X exist?", not "how is it performing?". When to use - "Do I have a campaign called X?", "find campaigns matching 'newsletter'" - Resolving an exact campaign value before ranking or looking up its performance Not this tool if - Ranking campaigns by performance, or "how is campaign X doing?" → query_campaigns Leads to query_campaigns(utm_key=..., ...) — take the exact key/utm_key pair from a result to rank or filter by it. Traps to avoid - Prefix match, not substring: query="extel" finds Extel_... but a mixed-case prefix like extel_aac may not match Extel_AAC_.... - No date window — this is a fixed-window discovery index, not the traffic window used elsewhere. Absence here does not mean the campaign never ran. - Omit utm_key to search every UTM dimension at once; set it to restrict the search to one dimension (id, source, medium, content, term).
search_doc
ChatGPTSearch Parse.ly documentation for product knowledge and how-to guidance. Search the docs.parse.ly site for relevant documentation articles. The search_doc tool searches Parse.ly's documentation at docs.parse.ly. It is your primary, authoritative source for product knowledge and how-to guidance. When to Use Use search_doc for: - Questions about Parse.ly features or capabilities - How to use the Dash user interface - Users expressing uncertainty about how to perform a task - Requests to look something up in the docs When NOT to Use Use the granular analytics tools instead for: - Questions about the user's actual data or metrics - Performance queries, top posts, traffic analysis Search Tips The documentation site uses hybrid search. Expand acronyms and abbreviations: - "CTR definition" -> "click-through rate definition" - "API setup" -> "application programming interface setup" Response Structure Returns results (array of documentation pages) and total_results (count). Each result has canonical_url, title, and content (excerpt). After receiving results, summarize the most relevant result(s) in a concise paragraph that addresses the user's query. Cite each page as a markdown link with its title as the link text, [title](canonical_url), never a bare URL. If no results are relevant, inform the user politely and offer to connect them with Support. Examples Simple feature question: User: "What is headline testing?" ``json {"query_params": {"query": "What is headline testing?"}} ` **FAQ/policy question:** User: "Does Sage use my data to be trained?" `json {"query_params": {"query": "Does Parse.ly Sage use customer data for training?"}} ` **Scheduling question with user-specific context:** User: "I would like to schedule a weekly report delivered every Monday morning" `json {"query_params": {"query": "How do scheduled reports work?"}} ` **Uncertain user (docs before support):** User: "I am not sure if I should talk to support, but I need to know what's headline testing" `json {"query_params": {"query": "How does headline testing work?"}} ``
search_other_page
ChatGPTSearch for non-post, non-video pages by keyword across all content fields. Find other pages matching a search query with relevance-ranked results. The search_other_page tool finds non-post, non-video pages (pricing, landing, checkout, category, homepage, about) matching a keyword query, with relevance-ranked results and highlighted content snippets. Its main job is to RESOLVE such a page to a canonical_url you can then measure. When to Use - User asks to find pages that are not posts or videos - User wants to search for landing pages, pricing/checkout pages, or other non-article content - User needs a canonical_url for a non-article page before pulling its metrics When NOT to Use - User wants an article/post → search_post (articles are NOT indexed here) - User wants to search for videos → search_video - User wants to rank top pages by metrics → query_top_content (with a page_type filter) Leads to query_post_detail(canonical_url=...) — take the canonical_url from a result to pull full metrics for that one page. query_post_detail works for ANY page, not just posts. Response structure Returns paginated results with total_results (total matches), has_more (whether more pages exist), and results array where each item has title, canonical_url, authors, section, pub_date, and full_content (highlighted snippet). Examples User asks to find other pages: User: "Find landing pages about pricing" ``json {"query_params": {"q": "pricing", "per_page": 10}} ``
search_post
ChatGPTSearch for posts by keyword across all content fields. Find posts matching a search query with relevance-ranked results. The search_post tool finds posts matching a keyword query with relevance-ranked results and highlighted content snippets. When to Use - User asks to find articles about a topic - User wants to search for posts by keyword - User needs to locate specific content by title or text - User asks about a word or pattern in headlines — "which posts have AI in the title", "how many headlines are questions": search the keyword (or list recent posts), then read the returned title fields and count or list the matches yourself. Don't refuse a headline pattern you can read off the results; if ranking by traffic matters, use query_top_content and pattern-match its title rows instead. When NOT to Use - User wants to rank top posts by metrics (use query_top_content instead) - User wants authors/sections/tags (use list_author, list_section, list_tag) - User wants to search for videos or other pages (use search_video, search_other_page) Leads to query_post_detail(canonical_url=...) — take the canonical_url from a result to pull full metrics for that one post. Response structure Returns paginated results with total_results (total matches), has_more (whether more pages exist), and results array where each item has title, canonical_url, authors, section, pub_date, and full_content (highlighted snippet). Examples User asks to find articles about AI: User: "Find articles about AI" ``json {"query_params": {"q": "AI", "per_page": 10}} ` **User asks to search with pagination:** User: "Search for posts mentioning climate change, page 2" `json {"query_params": {"q": "climate change", "page": 2, "per_page": 10}} ``
search_video
ChatGPTSearch for videos by keyword across all content fields. Find videos matching a search query with relevance-ranked results. The search_video tool finds videos matching a keyword query with relevance-ranked results and highlighted content snippets. When to Use - User asks to find videos about a topic - User wants to search for video content by keyword - User needs to locate specific videos by title or description When NOT to Use - User wants to search for posts (use search_post) - User wants to search for other pages (use search_other_page) - User wants to list top videos by metrics (use list_post with page_type filter) Response structure Returns paginated results with total_results (total matches), has_more (whether more pages exist), and results array where each item has title, canonical_url, authors, section, pub_date, and full_content (highlighted snippet). Examples User asks to find videos: User: "Find videos about cooking" ``json {"query_params": {"q": "cooking", "per_page": 10}} ``
submit_feedback
ChatGPTReport a gap in these tools. Call this BEFORE you answer the user whenever you hit a limitation: you looked for a tool or parameter that does not exist; a tool returned an empty or surprising result you could not explain; you are about to tell the user something is not possible; or you had to approximate because the data you wanted was not available. Be specific — name the tools you called and the arguments you used. This is the only channel through which the people who build these tools learn what is missing, and it directly drives what gets fixed. Reporting costs you nothing and never changes the answer you give the user. The submit_feedback tool reports a gap in these tools to the people who build them. It is the only channel through which we learn what is missing. When to Use Call it before you answer the user, whenever any of these is true: - You looked for a tool or a parameter that does not exist. - A tool returned an empty or surprising result you could not explain. - You are about to tell the user something is not possible. - You had to approximate, or answer a narrower question than the one asked, because the data you wanted was not available. - The numbers look wrong — two tools disagree, or a total does not add up. Reporting costs you nothing, never fails, and never changes the answer you give the user. Report first, then answer. When NOT to Use - Do not use it as a scratchpad, or to report your own mistake. If you called a tool with a wrong value, fix the call and retry — an empty result is usually a wrong filter value, not a missing feature. - Do not report the same gap twice in one conversation. Pass session_id so repeats are collapsed automatically. What Makes a Report Useful what_i_tried is the field that decides whether we can act on it. Name the tools and the arguments, with what came back. "It returned nothing" is not reproducible; the example below is. Examples A filter accepted a value and silently returned nothing: ``json { "body": { "what_i_needed": "top content for one audience segment, by its display name", "what_i_tried": "query_top_content(sid=\"Midwest\") -> 0 rows; query_top_aspect(aspect=segments) showed id 2471 = \"Midwest\"; query_top_content(sid=\"2471\") -> data", "gap_type": "incomplete_results", "suggestion": "resolve segment display labels to ids in sid, the way the segments aspect already does", "resolution": "worked_around", "tools_called": ["query_top_content", "query_top_aspect"], "site": "arstechnica.com", "session_id": "abc123" } } ` **A capability that does not exist at all:** `json { "body": { "what_i_needed": "pageviews broken down by hour of day for a past week", "what_i_tried": "query_traffic_trend(interval=\"1h\", start=\"2026-07-01\", end=\"2026-07-07\") -> daily buckets only", "gap_type": "missing_tool", "resolution": "blocked", "tools_called": ["query_traffic_trend"], "session_id": "abc123" } } ``
update_aspect_group
ChatGPTUpdate a specific aspect group as indicated by the primary key. Modify existing content group properties and selection rules. The update_aspect_group tool modifies an existing aspect group's properties and filters. Important: This endpoint requires the numeric group ID. If user specifies a group name, first call tool list_aspect_group to find the ID and then call this tool. Important: Updating an aspect group replaces all existing filters with the new set provided. To modify filters incrementally, first retrieve the current filters using get_aspect_group or list_aspect_group, adjust them as needed, then submit the full updated filter set in the update request. When to Use Use update_aspect_group only when: - User wants to change a specific aspect group's name, type, filters, or other properties. - The ID of the group to update is provided by the user or known from a previous operation. When NOT to Use - If the user wants to list, view, create, or delete groups, do not use this tool. Use list_aspect_group, get_aspect_group, create_aspect_group, or delete_aspect_group respectively instead. Examples User wants to update a group with known ID: User: "Update group 15 to include exclude "bing" as well" ``json { "path_params": {"pk": 15}, "body": { "name": "Paid", "group_type": "campaign", "filters": [ {"field": "medium", "condition": "any", "values": ["ad", "paid_search"]}, {"field": "source", "condition": "exclude", "values": ["google", "bing"]} ] } } ``
update_goal
ChatGPTUpdate a goal. Replaces the goal's name, cadence, aspect, metric, target and filters with what is sent. The update_goal tool changes an existing goal's name, metric, cadence, target or filters. Important: This endpoint requires the numeric goal id. If the user names a goal, call list_goal first to find its id, then call this tool. Important: Updating a goal replaces every field with what is sent, filters included. To change one thing, first read the goal's current definition from list_goal, adjust it, then submit the full set. Omitting a filter removes it. When to Use Use update_goal only when: - The user wants to change a specific goal's target, cadence, metric, name or filters. - The id of the goal is provided by the user or known from a previous list_goal call. When NOT to Use - If the user wants to see existing goals or their pace, use list_goal. - If the user wants one goal's history, use get_goal. - If the user wants a new goal, use create_goal. - Goals cannot be deleted through a tool; direct the user to the dashboard. Examples User wants to raise a target: User: "Bump goal 1390 to 350,000." ``json { "path_params": {"pk": 1390}, "body": { "name": "Politics views", "metric": "views", "period": "monthly", "aspect": "site", "goal": 350000, "page_type": "any", "path": ["/news", "//politics"], "exclude_section": ["Opinion"] } } ` **User wants to change a goal's cadence:** User: "Make the subscriptions goal weekly instead of monthly." `json { "path_params": {"pk": 842}, "body": { "name": "Subscriptions", "metric": "conversions", "period": "weekly", "aspect": "site", "goal": 500, "attribution_type": "last_touch", "conversion_type": "subscription" } } ``
