Skip to main content
This guide provides practical examples of common API requests. All examples use JSON format and require authentication via API key.

Reports

The following examples are provided as reference to recreate the metrics in the dashboard for your own purposes. Please note:
  • The endpoints have far larger capacity than the /v1/logs/* endpoints. With millions of logs, querying 10,000 at a time is cumbersome. These endpoints retrieve pre-aggregated data.
  • Response times will be much faster than the /v1/logs/* endpoints.
  • Pre-aggregation happens at the daily level. Only day-by-day data is available via these endpoints, finer granularity requires querying the /v1/logs/* endpoints.
  • Timestamps are converted to start of day, EST.

Bot Reports

Use the following request to get a count of visits by bot type:Dashboard Metrics
POST /v1/reports/bots HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "domain": "www.tryprofound.com",
  "start_date": "2025-12-12",
  "end_date": "2025-12-18",
  "metrics": ["citations", "training", "indexing"]
}
{
  "info": {},  // removed for brevity
  "data": [
    {
      "metrics": [
        20640,
        8450,
        3646
      ],
      "dimensions": []
    }
  ]
}

Referral Reports

Use the following request to get a count of refferals broken down by platform:
Note:other represents referrals from Traditional Sources, e.g. LinkedIn, Facebook, etc.internal represents referrals from within your website, e.g. a blog post linking to another blog post.
Referrals By Platform
POST /v1/reports/referrals HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "domain": "www.tryprofound.com",
  "start_date": "2025-12-12",
  "end_date": "2025-12-18",
  "dimensions": ["referral_source"],
  "filters": [
    {"field": "referral_source", "operator": "not_in", "value": ["none", "internal"]}
  ],
  "metrics": ["visits"]
}
{
  "info": {},  // removed for brevity
  "data": [
    {
      "metrics": [
        222022
      ],
      "dimensions": [
        "other"
      ]
    },
    {
      "metrics": [
        5171
      ],
      "dimensions": [
        "openai"
      ]
    },
    {
      "metrics": [
        102
      ],
      "dimensions": [
        "perplexity"
      ]
    },
    {
      "metrics": [
        39
      ],
      "dimensions": [
        "gemini"
      ]
    },
    {
      "metrics": [
        22
      ],
      "dimensions": [
        "anthropic"
      ]
    },
    {
      "metrics": [
        2
      ],
      "dimensions": [
        "deepseek"
      ]
    }
  ]
}

Raw Data

The API also exposes endpoints for retreiving raw data. Raw data is not pre-aggregated. This means that the response times will be slower than the pre-aggregated endpoints, and response sizes will be significantly larger. Moreover, for sites with millions of visits per day, querying 10,000 at a time is infeasible. Use the pre-aggregated endpoints for most use cases.
Raw data is not cleaned. Raw data may include duplicate entries, logs to static assets (e.g. “_next/static/chunks/…”) and other non-user-facing logs. These are deduplicated, filtered, and cleaned in the pre-aggregation process. This also includes removing non-200 requests, non-GET requests, etc.
Use the following request to recreate the live log stream:
Note the filters applied in the top right. The dashboard is showing a live log stream with,
  • Status Codes: 2xx
  • Visit Types: Bot Visits
  • Bot Types: AI Assistant
  • Platforms: NOT ChatGPT
Live Bot Logs
POST /v1/logs/raw HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "domain": "www.tryprofound.com",
  "start_date": "2025-12-17T23:59:59",
  "dimensions": ["timestamp", "bot_provider", "bot_name", "bot_types", "user_agent", "path", "query_params"],
  "filters": [
    {"field": "status_code", "operator": "is", "value": 200},
    {"field": "bot_types", "operator": "contains", "value": "ai_assistant"},
    {"field": "bot_name", "operator": "not_is", "value": "ChatGPT-User"}
  ],
  "metrics": [],
  "pagination": {"limit": 10, "offset": 0},
  "order_by": {"timestamp": "desc"}
}
[
  {
    "timestamp": "2025-12-19T04:10:59",
    "path": "/blog/technology",
    "user_agent": "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; PerplexityBot/1.0; +https://perplexity.ai/perplexitybot)",
    "query_params": {},
    "bot_name": "PerplexityBot",
    "bot_provider": "perplexity",
    "bot_types": [
      "index",
      "ai_assistant"
    ]
  },
  {
    "timestamp": "2025-12-19T04:10:37",
    "path": "/customers/1840-co-answer-engine-optimization-case-study",
    "user_agent": "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; PerplexityBot/1.0; +https://perplexity.ai/perplexitybot)",
    "query_params": {},
    "bot_name": "PerplexityBot",
    "bot_provider": "perplexity",
    "bot_types": [
      "index",
      "ai_assistant"
    ]
  },
  {
    "timestamp": "2025-12-19T03:43:25",
    "path": "/blog/what-is-claude-web-search-explained",
    "user_agent": "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; PerplexityBot/1.0; +https://perplexity.ai/perplexitybot)",
    "query_params": {},
    "bot_name": "PerplexityBot",
    "bot_provider": "perplexity",
    "bot_types": [
      "index",
      "ai_assistant"
    ]
  },
  {
    "timestamp": "2025-12-19T03:36:44",
    "path": "/_next/static/chunks/6d678fe91afd78f8.js",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15 (Applebot/0.1; +http://www.apple.com/go/applebot)",
    "query_params": {
      "dpl": "..."
    },
    "bot_name": "Applebot",
    "bot_provider": "apple",
    "bot_types": [
      "index",
      "ai_assistant"
    ]
  },
  {
    "timestamp": "2025-12-19T03:35:13",
    "path": "/blog/best-generative-engine-optimization-tools",
    "user_agent": "DuckAssistBot/1.2; (+http://duckduckgo.com/duckassistbot.html)",
    "query_params": {},
    "bot_name": "DuckAssistBot",
    "bot_provider": "duckduckgo",
    "bot_types": [
      "ai_assistant"
    ]
  },
  {
    "timestamp": "2025-12-19T03:34:31",
    "path": "/blog/9-best-answer-engine-optimization-platforms",
    "user_agent": "DuckAssistBot/1.2; (+http://duckduckgo.com/duckassistbot.html)",
    "query_params": {},
    "bot_name": "DuckAssistBot",
    "bot_provider": "duckduckgo",
    "bot_types": [
      "ai_assistant"
    ]
  },
  {
    "timestamp": "2025-12-19T03:34:31",
    "path": "/robots.txt",
    "user_agent": "DuckAssistBot/1.2; (+http://duckduckgo.com/duckassistbot.html)",
    "query_params": {},
    "bot_name": "DuckAssistBot",
    "bot_provider": "duckduckgo",
    "bot_types": [
      "ai_assistant"
    ]
  },
  {
    "timestamp": "2025-12-19T03:30:50",
    "path": "/careers/technical-operations-engineer",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15 (Applebot/0.1; +http://www.apple.com/go/applebot)",
    "query_params": {},
    "bot_name": "Applebot",
    "bot_provider": "apple",
    "bot_types": [
      "index",
      "ai_assistant"
    ]
  },
  {
    "timestamp": "2025-12-19T03:29:42",
    "path": "/",
    "user_agent": "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 5X Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/99.0.4844.84 Mobile Safari/537.36 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)",
    "query_params": {},
    "bot_name": "Google-CloudVertexBot",
    "bot_provider": "google",
    "bot_types": [
      "ai_assistant"
    ]
  },
  {
    "timestamp": "2025-12-19T03:29:19",
    "path": "/",
    "user_agent": "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 5X Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.7390.122 Mobile Safari/537.36 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)",
    "query_params": {
      "_rsc": "..."
    },
    "bot_name": "Google-CloudVertexBot",
    "bot_provider": "google",
    "bot_types": [
      "ai_assistant"
    ]
  }
]