---
title: "Track Extension Events"
method: POST
path: "/api/v1/extension/track"
tags: ["extension"]
---

# Track Extension Events

`POST /api/v1/extension/track`

## Request

- Base URL: `https://geo.sig.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://geo.sig.ai/api/v1/extension/track`
- Auth: none declared

Track extension events (batch endpoint).

Accepts up to 50 events per request for efficient bulk processing.
Implements idempotency using event_id to prevent duplicates.

**Request Body:**
```json
{
  "events": [
    {
      "event_id": "uuid",
      "user_id": "anon_user123",
      "session_id": "session_abc",
      "timestamp": "2025-10-29T10:30:00Z",
      "event_type": "brand_viewed",
      "ai_platform": "chatgpt",
      "brand_name": "HubSpot",
      ...
    }
  ]
}
```

**Response:**
```json
{
  "status": "success",
  "events_received": 2,
  "events_processed": 2,
  "events_failed": 0
}
```

**Features:**
- Idempotency: Duplicate event_id will be skipped
- Session tracking: Creates/updates session records
- Batch processing: Up to 50 events per request

## Request body

- ExtensionEventBatchRequest: Schema for batch event tracking request. Accepts up to 50 events per request for efficient bulk processing.
  - `events` ExtensionEventCreate[], required: Array of extension events (max 50 per request)
    - `event_id` string, uuid, required: Unique event ID from extension (for idempotency)
    - `user_id` string, required: Anonymized extension user ID
    - `session_id` string, required: Session ID grouping related events
    - `timestamp` string, date-time, required: Event timestamp (ISO 8601)
    - `event_type` 'brand_viewed' | 'brand_clicked' | 'reputation_checked': Type of user interaction
    - `ai_platform` 'chatgpt' | 'gemini' | 'claude' | 'perplexity', required: AI platform where brand was mentioned
    - `user_query` string, nullable: User's original query (anonymized)
    - `brand_name` string, required: Name of mentioned brand
    - `brand_category` string, nullable: Brand category (e.g., 'crm', 'ecommerce')
    - `mention_rank` integer, nullable: Position in AI response (1st, 2nd, 3rd...)
    - `recommendation_strength` 'explicit' | 'implicit' | 'neutral' | 'negative', nullable: Strength of AI recommendation
    - `clicked_through` boolean: Whether user clicked through to brand
    - `reputation_score_viewed` boolean: Whether user viewed reputation badge
    - `time_viewed_seconds` integer, nullable: Time spent viewing brand mention
    - `extension_version` string, nullable: Extension version (e.g., '1.0.0')
    - `user_agent` string, nullable: Browser user agent

## Response `200`

Successful Response

- ExtensionEventBatchResponse: Schema for batch event tracking response.
  - `status` 'success' | 'partial_success' | 'error', required
  - `events_received` integer, required: Number of events in request
  - `events_processed` integer, required: Number of events successfully processed
  - `events_failed` integer, required: Number of events that failed processing
  - `errors` string[], nullable: Error messages for failed events

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/sig/apis/ai-visibility-intelligence-api.md) · [All operations](https://skmtc.dev/sig/apis/ai-visibility-intelligence-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sig/apis/ai-visibility-intelligence-api/revisions/3ec39f9be9e0?raw)