REST API Documentation

TL;DR

Generate a personal API key in your account settings. Then use standard HTTP GET requests with your API key to retrieve visibility scores, mention counts, and sentiment data from ChatGPT, Gemini, Perplexity, and Claude. Works with Excel, Google Sheets, Power BI, Tableau, Python, and any other HTTP client.

Table of Contents

1. Base URL
2. Authentication
3. Rate Limits
4. Endpoints
   1. GET /api/v1/looker/schema
   2. GET /api/v1/looker/data
   3. GET /api/v1/looker/selections
5. Data Fields Reference
6. Response Format
7. Error Handling
8. Code Examples
9. FAQ

curl -H "Authorization: Bearer avt_your_key_here" \
  https://your-domain.com/api/v1/looker/data

curl "https://your-domain.com/api/v1/looker/data?api_key=avt_your_key_here"

Returns the data schema with field names, types, and semantic information. Useful for understanding the data structure before querying.

Parameters: None

Example Request:

curl -H "Authorization: Bearer avt_your_key_here" \
  https://your-domain.com/api/v1/looker/schema

Example Response:

{
  "schema": [
    {
      "name": "date",
      "label": "Date",
      "dataType": "STRING",
      "semantics": {
        "conceptType": "DIMENSION",
        "semanticType": "YEAR_MONTH_DAY"
      }
    },
    {
      "name": "visibility_score",
      "label": "Visibility Score",
      "dataType": "NUMBER",
      "semantics": {
        "conceptType": "METRIC"
      }
    }
  ]
}

Returns your AI visibility analysis results. Supports filtering by date, topic area, and AI system. Includes pagination for large datasets.

Query Parameters:

Example Request:

curl -H "Authorization: Bearer avt_your_key_here" \
  "https://your-domain.com/api/v1/looker/data?date_from=2025-01-01&date_to=2025-01-31&ai_system=chatgpt&limit=500"

Example Response:

{
  "data": [
    {
      "date": "20250115",
      "topic_area": "Brand Monitoring",
      "prompt": "What is the best project management tool?",
      "category": "Product Comparison",
      "funnel_stage": "Consideration",
      "ai_system": "chatgpt",
      "brand": "Asana",
      "visibility_score": 75,
      "mention_count": 3,
      "position_score": 85,
      "sentiment_score": 0.8,
      "web_search_used": false
    }
  ],
  "pagination": {
    "total": 1250,
    "limit": 500,
    "offset": 0,
    "has_more": true
  }
}

Returns a list of your topic areas (selections) with their IDs. Use these IDs to filter data in the /data endpoint.

Parameters: None

Example Request:

curl -H "Authorization: Bearer avt_your_key_here" \
  https://your-domain.com/api/v1/looker/selections

Example Response:

{
  "selections": [
    {
      "id": 42,
      "name": "Brand Monitoring",
      "description": "Track brand mentions across AI platforms",
      "prompt_count": 25,
      "is_active": true,
      "created_at": "2025-01-10T14:30:00"
    }
  ]
}

import requests

API_KEY = "avt_your_key_here"
BASE_URL = "https://your-domain.com/api/v1/looker"

headers = {"Authorization": f"Bearer {API_KEY}"}

# Get all topic areas
selections = requests.get(f"{BASE_URL}/selections", headers=headers).json()
print(selections)

# Get visibility data for January 2025
params = {
    "date_from": "2025-01-01",
    "date_to": "2025-01-31",
    "limit": 1000
}
data = requests.get(f"{BASE_URL}/data", headers=headers, params=params).json()
print(f"Total records: {data['pagination']['total']}")

# Paginate through all results
all_records = []
offset = 0
while True:
    params["offset"] = offset
    response = requests.get(f"{BASE_URL}/data", headers=headers, params=params).json()
    all_records.extend(response["data"])
    if not response["pagination"]["has_more"]:
        break
    offset += params["limit"]

print(f"Fetched {len(all_records)} records total")

const API_KEY = "avt_your_key_here";
const BASE_URL = "https://your-domain.com/api/v1/looker";

const headers = { "Authorization": `Bearer ${API_KEY}` };

// Get visibility data
const response = await fetch(`${BASE_URL}/data?date_from=2025-01-01&limit=500`, { headers });
const result = await response.json();
console.log(`Total: ${result.pagination.total} records`);

# Get schema
curl -H "Authorization: Bearer avt_your_key_here" \
  https://your-domain.com/api/v1/looker/schema

# Get data with filters
curl -H "Authorization: Bearer avt_your_key_here" \
  "https://your-domain.com/api/v1/looker/data?date_from=2025-01-01&ai_system=chatgpt&limit=100"

# Get topic areas
curl -H "Authorization: Bearer avt_your_key_here" \
  https://your-domain.com/api/v1/looker/selections

function getVisibilityData() {
  const API_KEY = "avt_your_key_here";
  const url = "https://your-domain.com/api/v1/looker/data?limit=500";

  const options = {
    headers: { "Authorization": "Bearer " + API_KEY },
    muteHttpExceptions: true
  };

  const response = UrlFetchApp.fetch(url, options);
  const json = JSON.parse(response.getContentText());

  // Write data to the active sheet
  const sheet = SpreadsheetApp.getActiveSheet();
  const headers = Object.keys(json.data[0]);
  sheet.getRange(1, 1, 1, headers.length).setValues([headers]);

  const rows = json.data.map(row => headers.map(h => row[h]));
  sheet.getRange(2, 1, rows.length, headers.length).setValues(rows);
}