# API

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](https://docs.airops.com/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

```bash
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

```bash
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

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

```json
{ "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:

```json
{
  "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:

```json
{ "sort": "-citation_rate" }
```

### Field Selection

Pass a `fields` array to limit returned fields:

```json
{ "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:

```json
{
  "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](https://app.airops.com) 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](https://lookerstudio.google.com/datasources/create?connectorId=AKfycbwR2EmDc6nXQkCLQNnn8EvUk_Z30Maf8wWD1sK3T13Zoe9LeeEQy3MtK6uzi_sU_1za)
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](https://docs.airops.com/api-reference/api-reference/brand-kits).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.airops.com/insights/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.