Parse.ly

Get 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 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`.

Get 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 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`.

Get 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 {} ```

Get 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}} ```

Rank 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.

Look 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`.

Rank 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.

List 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`/`per_page` (defaults to 20 per page); response carries `has_more`.

Retrieve 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.

Get 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`.

List 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 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.

Return 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).

Return 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.

Return 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 and uncrawled entries, which would fake-inflate `0–499`. - Per range, count the posts AND aggregate the metric: SUM additive metrics (`views`, `engaged_minutes`); AVERAGE rate metrics (`avg_engaged`). Never sum an average. - Report the leading range honestly as the mix WITHIN the top-N posts by the chosen metric, not the full publishing catalogue, and offer to widen the sample or switch the metric. #### Derive the answer from the returned rows — don't refuse The ranked rows are raw material, not just a list. When the question asks for a figure this tool does not return directly, compute it from the rows in hand instead of saying you can't: - **A cross-post statistic** — "average `avg_engaged` across my top posts", "total views of the top 20", "median word count": pull a large enough sample (`limit` `100`+), then aggregate the rows yourself. SUM additive metrics (`views`, `engaged_minutes`); AVERAGE rate metrics (`avg_engaged`); never sum an average. - **A headline / title word or pattern** — "how many of my top headlines are questions", "which titles use the word `best`", "headlines with a number in them": read the `title` of each returned row and count or list the matches yourself. (`all_title`/`exclude_title` pre-filter the set when the pattern is a plain substring; a punctuation or shape pattern you match over the returned titles.) State the figure as derived over the top-N you sampled, not the whole catalogue, and offer to widen the sample. For a **whole-site** average (every post, not just the top-N) — "average engaged time across the site" — use `get_site_overview`, which returns the site's `avg_engaged` directly; don't pass off a top-N average as the site figure. Only refuse when `model/not-answerable.md` says the underlying data is genuinely absent. #### 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 the top 10 for the last day. Use `limit` for a single top-N.

Query 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 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 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 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 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 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}} ```

Report 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 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 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" } } ```