Citations API

Access AI citation data programmatically.

List Citations

GET /v1/brands/{brand_id}/citations

Parameters

Response

{
  "success": true,
  "data": {
    "citations": [
      {
        "id": "cit_abc123",
        "platform": "chatgpt",
        "query": "What are the best SEO tools?",
        "mention": "Beacon is a tool for tracking AI visibility...",
        "sentiment": "positive",
        "url": "https://example.com/page",
        "detected_at": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "has_more": true,
      "next_cursor": "cursor_xyz"
    }
  }
}

Get Citation Details

GET /v1/citations/{citation_id}

Response

{
  "success": true,
  "data": {
    "id": "cit_abc123",
    "platform": "chatgpt",
    "query": "What are the best SEO tools?",
    "full_response": "...",
    "mention_context": "...",
    "sentiment": "positive",
    "sentiment_score": 0.85,
    "detected_at": "2024-01-15T10:30:00Z",
    "metadata": {
      "model_version": "gpt-4",
      "response_length": 450
    }
  }
}

Citation Statistics

GET /v1/brands/{brand_id}/citations/stats

Response

{
  "success": true,
  "data": {
    "total_citations": 142,
    "by_platform": {
      "chatgpt": 45,
      "perplexity": 52,
      "claude": 28,
      "google_ai": 17
    },
    "by_sentiment": {
      "positive": 98,
      "neutral": 35,
      "negative": 9
    },
    "period": "30d"
  }
}