API

Access your AI visibility data programmatically — build dashboards, automate reports, and integrate AEO metrics into your data stack.

The Insights API gives 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 with three data sources combined 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

All metrics include _change variants showing period-over-period delta.

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

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.

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.

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

---

Supported Countries

32 countries supported. Pass ISO 3166-1 alpha-2 codes in the countries filter:

US GB DE FR JP AU CA BR IN KR MX ES IT NL SE NO DK FI PL CZ AT CH BE PT IE NZ SG HK TW TH ID PH

---

Errors

Status	Meaning
400	Invalid filter, operator, or sort field. Check validation_errors in the response.
401	Missing or invalid API key.
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.