AIclicks

Daily ChatGPT-ads activity for the domain over the past `days` days — the ads trend.

get_chatgpt_ads_timeline

Daily citability score — the share of all citations (`citation_count`) that point to the domain's URLs — with `answers_count` per day.

get_citability_time_series

Cited domains (hosts) in AI answers to the domain's prompts, sorted by citations desc. Each row: `citations`, `prompt_count`, `share_percent` (share of all citations), and `owner`: `own` (the brand's site), `competitor` (a tracked competitor's site) or `third_party`. Use for "which sites does AI cite, and how much is ours vs competitors?". Paginated (`items`, `total`, `page`, `size`, `total_pages`); drill into one host's URLs with `get_citations(cited_domain=...)`.

get_citation_domains

Each brand's share of citations within every topic (or tag). Returns one item per topic/tag with `brands`: the own brand first, then each tracked competitor, each with `citations` and `share_of_all_citations` (%) for that unit. Use for "in which topics do competitors out-cite us?" questions.

get_citation_share

URL-level citations the domain appears in across AI search results — page type, citation frequency (primary ranking metric), aggregate mentions, prompt count, models. Sorted by frequency desc. Pagination is opt-in. Without `page` every URL comes back as `items`; a 30-day pull on a busy domain can exceed the response size limit and drop the connection. For anything over 7 days pass `page=1` to get `items` plus `total`, `page`, `size`, `total_pages`, and only request further pages when the question needs the long tail; narrow with `min_frequency`, `cited_domain` or `page_type` instead of pulling every page. `group_by=domain|page_type` returns aggregated rows (paginated the same way); for per-domain ownership (own / competitor / third-party) use `get_citation_domains`. Each URL row also carries `prompt_ids`: the tracked prompts whose responses cited that URL — resolve them to text and search volume via `list_prompts`. Long windows (90 days) can take a minute on the first call; later pages and filters reuse the cached aggregate. Each URL row also has `mentioned` (whether the page itself names the brand; null when unknown) and `competitors` (tracked competitors named on the page as `{id, name}`). A `summary` block splits citations between pages that mention the brand and pages that don't (counts and %).

get_citations

Daily citation count for the domain (URLs from this domain appearing in AI answers), with `answers_count` per day.

get_citations_time_series

How often AI answers cite each tracked domain: the own brand first, then each competitor. Each entry has `citations` (cited URLs on that domain) and `share_of_all_citations` (%). Use for "whose website do LLMs cite most?" questions. For a per-topic or per-tag breakdown in one call, use get_citation_share.

get_competitor_citations

Competitors that show up in AI answers to your prompts but you AREN'T tracking yet. Detected (non-dedicated) brands mentioned alongside you, ranked by how many of your prompts mention them (`prompts_mentioned` out of `total_prompts`). Use to find rivals worth adding to tracking. Distinct from get_brand_rankings, which only covers already-tracked competitors.

get_competitor_discovery

Daily visibility / share-of-voice / position per tracked competitor (plus the brand) over time. The trend version of get_brand_rankings: each entry (brand first, then competitors) has a `series` of daily {visibility, sov, mentions, avg_position, sentiment, answers_count, citations, citation_count, citability} plus window averages and totals. `citations` counts citations of the entity's own site; `citability` is that share of all citations (`citation_count`). Use for "how is competitor X trending vs us?" questions.

get_competitor_time_series

Create a new brand (domain) with the prompts that will be tracked. Creation is not reversible through this API, and the prompts drive all subsequent analysis. Requires prompts the user has supplied or approved, passed as `prompts` (each {"text": str, "topics"?: [str], "tags"?: [str]}). `generate_prompts=true` is a fallback where the backend picks prompts server-side; those are not returned for the user to review, so it applies only when the user has opted out of reviewing them. A brand with no prompts is rejected (400): a non-empty `prompts` list OR `generate_prompts=true` is required. Also requires the caller to be a member of `team_id`, on a Pro+ plan, and within the team's domain limit. Returns the created domain. Results can take a while to appear in the aiclicks dashboard (it caches for ~30 min). Poll `get_domain_status` to know when the first analysis has finished.

create_domain

Create a tag in a domain. This mutates the account. Returns the new tag with its UUID for set_prompt_tags / add_prompt. Fails (error in payload) when a tag with that name already exists. Requires the admin, co-admin or editor role on the team.

create_tag

Create a topic in a domain. This mutates the account. Returns the new topic with its UUID for set_prompt_topics / add_prompt. Fails (error in payload) when a topic with that name already exists.

create_topic

Threads and posts worth engaging in: the community pages AI answers lean on for the domain's prompts. Each row has the source URL, title, platform, how often AI answers cite it (`frequency`), engagement `metrics`, its status, and `is_brand_named`: true if the page already names the brand, false if it was checked and does not, null if aiclicks has no citation analysis for that URL. Also returns `counts_by_platform`. Paginated.

list_engage_recommendations

AI-referred traffic broken out per LLM source (ChatGPT, Perplexity, Claude, Gemini…) — sessions/users/pageviews each — plus the previous period, to see which assistants actually send visitors.

get_ga4_by_llm

AI-referred traffic by device category (mobile/desktop/tablet) — device + sessions.

get_ga4_devices

GA4 key events / conversions attributed to AI-referred traffic — total, per-LLM breakdown, and top events — plus the previous period's total. The 'did AI traffic convert?' view.

get_ga4_key_events

Totals of AI-referred traffic from GA4 over the window — sessions, users, pageviews — plus the previous period's totals for delta comparison.

get_ga4_summary

Daily AI-referred sessions over the window, each day broken down by LLM source. Use for trend/time-series of AI-driven traffic.

get_ga4_timeline

AI-referred traffic by browser — browser + sessions, top 10 sorted desc.

get_ga4_top_browsers

AI-referred traffic by country/location — location + sessions, sorted desc.

get_ga4_top_locations

Which pages pull the most AI-referred traffic — page_path + sessions, sorted desc. The 'which content wins AI visitors' view.

get_ga4_top_pages

Report where a domain's analysis stands. Use it to poll a newly created domain until its data is ready, instead of guessing. Returns `analysis_complete` (no analysis is currently running), `has_any_completed_analysis` (at least one analysis has finished, so analytics tools return data), `responses_count` and `queries_count` (progress of a running analysis; null once complete) and `is_discovery_ready` (a completed analysis exists and AI answers named competitors, so `get_competitor_discovery` and `add_competitors(from_discovery=N)` have candidates). Not cached; a first analysis typically takes tens of minutes, so poll every few minutes, not in a tight loop.

get_domain_status

Show a team's plan and what is used of it: prompt credits (limit/used/remaining), domains, AI models, price and included features. With `domain_id`, also that brand's tracked prompts and dedicated-competitor slots. Check this before adding prompts or competitors in bulk.

get_team_usage

List one domain's competitors, sorted by name. Returns the tracked competitors by default; set `is_dedicated=false` for discovered (untracked) brands or null for both. Without `page` the full list comes back as one array. Discovered lists can run to 1,500+ brands, so pass `page=1` to get `items` plus `total`, `page`, `size`, `total_pages` instead.

list_competitors

List every aiclicks domain (brand) the caller's API key can read. **Always call this first** — every other tool needs a `domain_id` from the response. The response shape depends on the key type (check `validate_key` if unsure): - **Team key** (scoped to one team): `data.items` is a flat array of domains — `{id, name, website, created_at}`. Every domain belongs to the key's single team. - **Master key** (spans all the user's teams): `data.items` is an array of teams, each `{team_id, team_name, domains: [{id, name, website, created_at}]}`. Read the `domain_id` from `items[].domains[]`, and use `team_name` to tell which team a domain belongs to. Detect which you got: if an item has a `domains` array it's a team group (master key); otherwise items are domains directly (team key).

list_domains

List the fanout (expanded) queries derived from the domain's prompts. Fanout queries are the broader set of question variants the discovery pipeline runs against AI search engines on top of the seed prompts. Useful to see what the search graph looks like beyond the user's curated prompt list. Grouped by prompt. Without `page` you get every prompt (`items`, `total`); the all-model view of a large project can be too big for one response, so pass `page=1` (then `page`, `size`, `total_pages` come back too) or `prompt_id` to see one prompt's fan-outs. `cited_urls` (with `include_urls`) are per AI response, so fan-outs from the same response share them.

list_fanout_queries

List the prompts/queries tracked for one domain, optionally filtered by text, topics, or tags. Each prompt is a search query aiclicks runs against AI search engines to see whether the brand shows up, with its topics and tags. Results are paginated; default page size is 50. `total` reflects the filters. For per-prompt metrics use list_prompt_metrics.

list_prompts

List the tags defined for a domain, each with its UUID and name. Use this to resolve tag names to the `tag_ids` that add_prompt and set_prompt_tags expect (they take UUIDs, not names). Create a missing tag with create_tag.

list_tags

List the topics defined for a domain, each with its UUID and name. Use this to resolve topic names to the `topic_ids` that add_prompt and set_prompt_topics expect (they take UUIDs, not names). Create a missing topic with create_topic.

list_topics

Daily mention count for the domain (answers naming the brand) as `value`, with `answers_count` — the analyzed answers that day — as the denominator.

get_mentions_time_series

Per-AI-model breakdown of how often the domain appears. Tells you whether ChatGPT, Perplexity, AI Overviews, etc. surface this brand at different rates over the window. Each row carries `answers_count`, the answers its visibility is computed over.

get_model_leaderboard

The AI answers collected for one prompt, newest first, one row per answer. Each row has date, model, the answer text, whether the own brand was named and at what position, the tracked competitors named with their positions, and the cited URLs. Paginated (default 20 per page). Use to read what the AI actually said.

get_answers

Every tracked brand for one prompt: the own brand first, then each tracked competitor. Each entry has total_mentions, avg_visibility, avg_sov, avg_position and avg_sentiment over the window. Use for "who wins this prompt?" questions.

get_prompt_brands

Every tracked prompt with its metrics over the window, paginated. Each row has visibility (%), mentions, citations, avg_position, responses (answers collected), estimated_search_volume, topics and tags. Prompts with no answers in the window are included with zeros. Use for "which prompts are we weakest on?" tables.

list_prompt_metrics

Per-prompt performance over time — which tracked prompts win or lose the brand visibility. Returns one page of prompts ranked by `sort` over the window (default: top 25 by total mentions), each with its `estimated_search_volume` and a daily `series` of `mentions`, `responses`, `citations`, and `avg_position`, window `totals` (incl. `answers_count`, the visibility denominator), plus `total`/`total_pages` for paging through every prompt. Use for "which prompts gained/dropped the most" questions.

get_prompt_statistics

The AI answers behind one sentiment theme, paginated. Each answer has its channel (ChatGPT, Gemini, ...), the prompt, the date, the quoted answer text and the source URLs it cites. Use to show the evidence for a theme.

get_sentiment_answers

Positive/negative sentiment split for how AI answers talk about the domain. Returns positive_percent, negative_percent, and total_mentions across the window. Use for "how do LLMs feel about my brand right now?" questions.

get_sentiment_overview

URLs the AI answers cite when raising sentiment themes about the domain. Returns each cited URL with its domain, citation frequency, the themes it appears under, and the models that cited it (sorted by frequency desc). Use to find which pages shape how LLMs talk about the brand.

get_sentiment_theme_sources

Themes AI answers raise about the domain, each tagged positive or negative. Returns theme id, name, sentiment, occurrence count and answers_count (answers behind the theme), sorted by occurrences desc. With `granularity`, returns `periods`, each with `period_start` and all its themes, for week-over-week theme trends. Use to see *what* drives sentiment — e.g. "pricing" negative, "support" positive.

list_sentiment_themes

Daily positive-sentiment percentage for the domain over the past `days` days. Each point is the share of that day's sentiment themes that are positive. Use to see whether brand sentiment in AI answers is trending up or down.

get_sentiment_time_series