Insights API

The AirOps Insights API: an AEO and AI citation tracking API with programmatic access to mention rate, share of voice, citations, and page performance, for custom dashboards, ETL, and reporting.

The Insights API is AirOps' answer engine optimization (AEO) and AI citation tracking API, giving you programmatic access to the same data you see in your Insights dashboard — mention rates, citations, share of voice, page performance, and more. Use it to build custom dashboards, automate reporting, or pipe AEO data into your data warehouse alongside your other marketing metrics.

All Insights endpoints live under /public_api/brand_kits and require a Brand Kit with AEO enabled. For authentication setup, see the API Reference.

---

Data Model

The Brand Kit is the root resource. Everything else connects to it:

Resource	What it contains
Analytics	Flexible metric queries — mention rate, share of voice, citation rate, sentiment, and more — sliced by provider, competitor, topic, country, or date
Web Pages	Your tracked pages with AEO citations, Google Search Console, and GA4 metrics combined
Prompts	AI questions being tracked, with mention/citation rates and trends
Citations	URLs cited in AI answers, with influence scoring and sentiment
Competitors	Domains you're monitoring for competitive analysis
Topics	Categories that organize your prompts
Personas	Audience profiles used for prompt analysis

---

Quick Start

1. Find your Brand Kit

curl -X POST https://api.airops.com/public_api/brand_kits/list \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [{ "field": "aeo_enabled", "operator": "EQ", "value": true }]
  }'

The response includes your Brand Kit id — use it in all subsequent calls.

2. Query your AI visibility

curl -X POST https://api.airops.com/public_api/brand_kits/{brand_kit_id}/analytics \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["mention_rate", "share_of_voice", "citation_rate"],
    "dimensions": ["date"],
    "grain": "weekly",
    "start_date": "2026-01-01",
    "end_date": "2026-02-18"
  }'

3. Find pages that need attention

curl -X POST https://api.airops.com/public_api/brand_kits/{brand_kit_id}/web_pages/list \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "smart_filter": "losing_ai_visibility",
    "per_page": 10,
    "sort": "-citations_count"
  }'

Three calls and you have: your visibility trend, competitive position, and which pages need work.

---

Endpoints

Which endpoint do I need?

I want to...	Use
Get my overall AI visibility metrics	Analytics
Compare against competitors over time	Analytics with competitor dimension
Break down performance by AI provider	Analytics with provider dimension
Find pages losing citations or rankings	Web Pages with smart filters
Get AEO + SEO + traffic data per page	Web Pages
See which AI questions mention my brand	Prompts
See which URLs are being cited	Citations

Analytics

POST /public_api/brand_kits/{id}/analytics

The most flexible endpoint. Pick any combination of metrics and dimensions to build the exact query you need.

Metrics:

Metric	Description
mention_rate	% of AI answers that mention your brand (0-100)
share_of_voice	Your mentions / (yours + competitors') (0-100)
citation_rate	% of AI answers that cite your pages (0-100)
citation_share	Your citations / total citations (0-100)
citation_count	Absolute number of citations
sentiment_score	Sentiment of brand mentions (0-100)
average_position	Mean position in AI answer lists
answer_count	Total AI answers analyzed
first_mention_rate	% of answers where you're mentioned first (0-100)

Dimensions (up to 3 per query): date, provider, topic, country, persona, domain, competitor, domain_category

Time grain: daily (max 120 days), weekly (max 180 days), monthly (max 365 days), total (max 365 days)

Filters: providers, topics, countries, personas, brand_mentioned

Limits: Max 1,000 rows per query. Default 100.

Web Pages

POST /public_api/brand_kits/{id}/web_pages/list

Your tracked pages combine citation, search, traffic, and Agent Analytics data in a single response:

Source	Metrics
AEO	citations_count, citation_rate, prompts_count
Google Search Console	clicks, impressions, ctr, position
Google Analytics 4	traffic, sessions, engagement, average_session_engagement
Agent Analytics	user_browse (AI Agent Visits), ai_training (Training Crawls), ai_search (Web Search Crawls)

The Agent Analytics fields are filterable and sortable counts for the selected date range. Connect Agent Analytics first to collect this data. These fields do not include period-over-period change variants. total_crawls is not a field on this endpoint; use the Agent Analytics endpoint below for that calculation.

Free-tier workspaces receive 402 Payment Required from the Web Pages endpoint.

Smart filters surface common opportunities:

Filter	What it finds
almost_page_one	Pages ranking #10-20
losing_clicks	Declining clicks with stable rankings
rankings_slipping	SERP position declining over 90 days
losing_ai_visibility	Pages losing AI citations
citation_rate_decline	Losing AI authority despite stable SEO

26+ filterable fields with operators: EQ, NEQ, GT, LT, GEQ, LEQ, CONTAINS, STARTS_WITH, IN

Agent Analytics

POST /public_api/brand_kits/{id}/agent_analytics/list

Returns daily request counts for the Brand Kit's tracked pages after you connect Agent Analytics. Each row contains date, platform, crawl_type, and count. Rows with no requests are omitted.

Provide start_date and end_date to choose a period. You can filter by platform, crawl_type, or one web_page_id, and sort by date or count (-count for largest first). Pagination defaults to 25 rows and supports up to 100 per page. Read every page before calculating totals.

Result	Calculation
Agent Analytics Total Crawls	Sum ai_search and ai_training for tracked engines.
AI Agent Visits	Sum user_browse for tracked engines.
Top Crawling Engine	The tracked engine with the largest combined ai_search and ai_training count.
Crawl type breakdown	Each of ai_search and ai_training as a percentage of their combined total for tracked engines.
Engine breakdown	Group by tracked engine and sum training crawls, web search crawls, their combined total, and AI Agent Visits.
Crawl activity vs. AI agent visits	Group by date and crawl type across all returned platforms, including other requests.
AI Agent Visits over time	Group user_browse by date and tracked engine.

Tracked engines for these calculations are chat_gpt, perplexity, gemini, google_ai_mode, and claude. The response also includes other platforms, such as generic search crawlers.

To match the Pages table's Total Crawls for one page, filter by its web_page_id and sum all rows, including every platform and crawl type. This differs from the Agent Analytics summary's AI-only crawl total.

The daily endpoint follows the Agent Analytics tab's date boundary: a request at exactly midnight after end_date can appear as a row dated the next day. Exclude rows dated after end_date when matching the Pages table.

Prompts

POST /public_api/brand_kits/{id}/prompts/list · GET /public_api/brand_kits/{id}/prompts/{id}

AI questions being tracked for your brand. Each prompt includes mention_rate, citation_rate, and period-over-period trends (mention_rate_trend, citation_rate_trend).

Filter by text, brand_mentioned, topic_id, prompt_volume, mention_rate, citation_rate. Scope metrics to specific providers, countries, or personas using context filters.

Answer intent

Answer list and detail responses expose the prompt's read-only intent_stage: awareness, consideration, evaluation, or purchase. It is null when classification is unavailable. The same field is available through MCP answer tools.

Citations

POST /public_api/brand_kits/{id}/citations/list · POST /public_api/brand_kits/{id}/citations/show

URLs cited in AI answers, each scored with an influence_score (0-100) that factors in domain authority, citation frequency, and relevance. Includes brand_sentiment (positive/neutral/negative) and domain_category.

Sort by citation_count, citation_share, citation_rate, or influence_score.

Citation list and detail responses include a social field when supported social metadata exists. It identifies the platform and contains content and account objects with metadata, metrics, and sync status. social is null when no supported social record exists; social.account can be null even when content is present. Metadata may be incomplete while collection is pending or after a failed collection.

YouTube content metadata also includes duration_seconds, format, and sponsorship_status. Duration can be null; format and sponsorship status use unknown when the information is unavailable.

Observed Ads

POST /public_api/aeo/brand_kits/{id}/ads/list · POST /public_api/aeo/brand_kits/{id}/ads/show

Query ChatGPT ads AirOps observes for the Brand Kit's tracked prompts. These endpoints use the same observed-ad data as Ad Library and do not require a ChatGPT Ads account connection. They require access to the Brand Kit's Ads data.

Endpoint	Returns
List	Unique observed creatives, advertiser details, title and body, appearances, distinct answers, prompts, frequency, and observation history
Show	One creative's details, image and destination URL, advertiser, and observation history

Pass the list result's observed_creative_id as id to the show endpoint. This identifies an observed creative, not a resource in your connected ad account.

List filters include topic_id, prompt_id, and brand_mentioned. Scope requests with start_date, end_date, countries, personas, and tags. The list supports pagination and field selection.

appearances counts ad occurrences; answers counts distinct collected answers containing the ad. frequency is the percentage of tracked answers in scope containing it. first_seen and last_seen cover the ad's observation history, and days_active is the inclusive span between them. The show endpoint does not return the list's windowed appearance, answer, prompt, or frequency metrics.

These observations do not establish full market coverage, advertiser spend, or targeting intent. The equivalent MCP tools are list_aeo_ads and get_aeo_ad.

Competitors, Topics, Personas

POST /public_api/brand_kits/{id}/competitors/list · GET .../competitors/{id} POST /public_api/brand_kits/{id}/topics/list · GET .../topics/{id} POST /public_api/brand_kits/{id}/personas/list · GET .../personas/{id}

Reference data for your Brand Kit configuration. Use these IDs when filtering other endpoints.

---

Common Patterns

Pagination

All list endpoints use offset-based pagination with a max of 100 items per page.

{ "page": 1, "per_page": 100 }

Responses include meta.total_count and meta.total_pages. Loop until page >= total_pages.

Filtering

Pass a filters array in the request body:

{
  "filters": [
    { "field": "citation_rate", "operator": "GT", "value": 5 },
    { "field": "brand_mentioned", "operator": "EQ", "value": true }
  ]
}

Type	Operators
Text	EQUALS, CONTAINS, STARTS_WITH
Numeric	EQ, NEQ, GT, LT, GEQ, LEQ
Set	IN

Sorting

Pass a sort string. Prefix with - for descending:

{ "sort": "-citation_rate" }

Field Selection

Pass a fields array to limit returned fields:

{ "fields": ["url", "citations_count", "clicks", "position"] }

Date Ranges

Metric endpoints accept start_date and end_date in YYYY-MM-DD format. Defaults to the last 30 days if omitted.

• end_date must be before today
• GSC and GA4 metrics have a 4-day lag

Data Availability

Every metric response includes a data_availability object:

{
  "data_availability": {
    "earliest_data_date": "2025-10-15",
    "latest_data_date": "2026-02-18",
    "requested_period_has_data": true
  }
}

Check requested_period_has_data before processing results.

---

Supported AI Providers

Use these values in the providers filter:

Value	Platform
chat_gpt	ChatGPT
gemini	Google Gemini
perplexity	Perplexity
google_ai_mode	Google AI Mode
google_ai_overview	Google AI Overview
claude	Claude

Claude is available on Enterprise workspaces by default. Each Claude Answer uses four billing units: four tasks on a combined-task workspace or four Answer Credits on a legacy workspace. See AEO Answers usage and billing.

---

Supported Countries

AirOps accepts these 49 region codes. Pass ISO 3166-1 alpha-2 codes in the countries filter:

AE AR AT AU BE BR CA CH CL CN CO CZ DE DK ES FI FR GB GR HR HU ID IE IL IN IS IT JP KE KR MX MY NG NL NO NZ PE PH PL PT SA SE SG TH TR TW US VN ZA

Platform coverage varies by region. A region appearing in this list does not guarantee that every AI provider collects answers there. For example, Kenya is supported for ChatGPT, Google AI Overview, Google AI Mode, and Claude; other providers may be unavailable.

---

Errors

Status	Meaning
400	Invalid filter, operator, or sort field. Check validation_errors in the response.
401	Missing or invalid API key.
402	The endpoint requires a paid workspace; Web Pages requests from Free workspaces return this status.
404	Brand Kit doesn't exist or you don't have access.
412	AEO is not configured for this Brand Kit.
422	Analytics-specific: end_date is today or later, date range exceeds grain limit, or more than 3 dimensions.

---

Use Cases

ETL & Data Export

AEO is a new data category that most marketing stacks don't have yet. The API lets you land it in your warehouse alongside SEO, paid, and web analytics data for cross-channel analysis.

What to export:

Table	Source endpoint	Sync strategy
Visibility metrics	Analytics (dimensions: date, provider)	Daily incremental — append yesterday's row
Competitive trends	Analytics (dimensions: date, competitor)	Weekly incremental
Page performance	Web Pages	Daily snapshot — paginate all pages
Citation inventory	Citations	Weekly snapshot — paginate all citations
Prompt landscape	Prompts	Weekly snapshot — paginate all prompts

Integration options:

• Airflow / Dagster / Prefect — Add a DAG that calls the API, writes JSON to S3/GCS, and loads via COPY INTO
• Airbyte / Fivetran — Use the generic HTTP API source connector with POST method and offset-based pagination
• Snowflake Snowpark — Call the API directly from a stored procedure and schedule with Snowflake Tasks
• AWS Lambda + Snowpipe — Serverless function on a cron writes to S3, Snowpipe auto-ingests

Pipeline tips:

• end_date must be a past date — the API only serves finalized data, so set it to yesterday or earlier. Requests with today's date or a future date will return a 422 error.
• GSC and GA4 metrics have a 4-day lag — data for the most recent 3 days may not be available yet
• Use per_page=100 (the max) to minimize round trips when paginating
• Check meta.data_availability.requested_period_has_data to detect empty date ranges before processing
• The analytics endpoint caps at 1,000 rows per query — for long time ranges with high-cardinality dimensions, split into windows based on the grain limit (120 days daily, 180 weekly, 365 monthly)

The Web Pages endpoint is especially valuable for ETL because it combines AEO + GSC + GA4 in a single response — saving you from stitching three separate data sources together.

Looker Studio

We provide a ready-to-deploy Looker Studio Community Connector that visualizes your AEO data directly — no ETL, data warehouse, or coding required.

What you get: Three data sources in one connector:

Data Source	What it shows
AI Visibility Analytics	Mention rate, share of voice, citation rate, sentiment, and more — sliced by date, provider, competitor, topic, or country
Page Performance	AEO + Google Search Console + GA4 metrics pre-joined per URL in a single data source
Citations	Citing source URLs with domain info, sentiment, influence score, and domain authority

Getting your API key

1. Log in to AirOps and go to Workspace Settings
2. Find the API Key section
3. Copy your API key — or click Regenerate if you need a new one

The key authenticates as a Bearer token. Keep it confidential and never expose it in client-side code.

Note: Regenerating your API key immediately invalidates the old one. If you have existing integrations using the key, update them before regenerating.

Connecting to Looker Studio

1. Open the AirOps AEO Connector
2. Authorize the connector when prompted by Google. You may see a "Google hasn't verified this app" warning — click Advanced → Go to AirOps AEO Connector to proceed. This only appears once.
3. Enter your AirOps API key when asked
4. Fill in the configuration:

   • Brand Kit ID — your numeric Brand Kit ID (visible in the AirOps dashboard URL, e.g., app.airops.com/brand_kits/12345)
   • Data Source — choose one of the three options: AI Visibility Analytics, Page Performance, or Citations
5. Click Connect — Looker Studio fetches the schema automatically
6. Click Create Report to start building

Tip: Add the connector three times (once per data source) to get analytics, page performance, and citations all in one report. Each data source becomes an independent source you can use in any chart.

Example charts

• Time series — Mention Rate over time (Analytics: Date + Mention Rate)
• Bar chart — Share of Voice by AI Provider (Analytics: AI Provider + Share of Voice)
• Competitor comparison — Grouped bar of Mention Rate by Competitor
• Top pages table — URL with Citations, GSC Clicks, GA4 Traffic side by side (Pages)
• Scatter plot — Citations vs. GSC Clicks to find pages winning on both AEO and SEO (Pages)
• Top citing domains — Bar chart of Domain by Citations (Citations)
• Sentiment breakdown — Pie chart of Brand Sentiment by citation count (Citations)

Available fields

AI Visibility Analytics:

Dimensions	Metrics
Date, AI Provider, Competitor, Topic, Country	Mention Rate, Share of Voice, Citation Rate, Citations, Sentiment, Avg Position, First Mention Rate, Answers

Page Performance:

Dimensions	Metrics
URL, Folder	Citations, Citation Rate, Prompts, GSC Clicks, GSC Impressions, GSC CTR, GSC Position, GA4 Traffic, GA4 Sessions, GA4 Engagement

Citations:

Dimensions	Metrics
URL, Domain, Domain Category, Page Type, Brand Mentioned, Brand Sentiment	Citations, Citation Share, Citation Rate, Influence Score, Domain Authority

Dashboard layout suggestion

A single-page executive overview might include:

• Top row — Scorecard widgets for Mention Rate, Share of Voice, Citation Rate, Total Citations
• Middle left — Mention Rate over time (line chart)
• Middle right — Share of Voice by AI Provider (bar chart)
• Bottom left — Top Pages table (URL, Citations, GSC Clicks, GA4 Traffic)
• Bottom right — Top Citing Domains (bar chart)

Add a Date range control widget to the report — all three data sources respect it automatically. Data for today is excluded since it's incomplete.

Limitations

• The Analytics API allows a maximum of 3 dimensions per query
• Page Performance and Citations return the top 500 rows per load
• This is a Community Connector — each user must authorize it on first use

Custom Dashboards

Build internal dashboards in Retool, Metabase, or Grafana. The analytics endpoint is flexible enough to power an entire dashboard from a single endpoint — just change the dimensions.

Automated Reporting

Schedule a script to pull weekly metrics and send a Slack summary or email digest to your team. The analytics endpoint with competitor and date dimensions gives you a full competitive report in one call.

Alerting

Use smart filters on a schedule to detect when pages start losing AI visibility or rankings slip. Trigger alerts in Slack, PagerDuty, or email when the losing_ai_visibility filter returns results.

Content Prioritization

Combine citation_rate, influence_score, and smart filters to programmatically rank which pages to optimize first. Feed the prioritized list into your content calendar or project management tool.

---

For full endpoint specifications including request/response schemas, see the API Reference.