> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Analytics

> Sample requests for Agent Analytics endpoints.

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

# Reports

<Tabs>
  <Tab title="Daily Reports (V1)">
    Examples for **V1** report endpoints (`/v1/reports/*`): daily pre-aggregated data in EST.
    For hourly granularity, use the **Hourly Reports (V2)** tab above.

    <Info>
      Raw Agent Analytics log endpoints are retired. For raw per-execution
      prompt-answer rows, use `POST /v2/prompts/answers`. For bot and referral
      traffic, use the aggregated `/v2/reports/bots` and `/v2/reports/referrals`
      endpoints.
    </Info>

    * **Capacity:** Full date ranges in one request using aggregated report endpoints.
    * **Granularity:** Data is bucketed by day. Timestamps are normalized to the start of each day in EST.

    ## Bot Reports

    <Tabs>
      <Tab title="Bot Highlights">
        Get a count of visits by bot type:

        <img src="https://mintcdn.com/profound-37face47/_84snNj2y4O4wlvX/images/rest-api/aa-examples/get-bot-visit-highlights.png?fit=max&auto=format&n=_84snNj2y4O4wlvX&q=85&s=f61cba46eb807a2712365c4ad71b8e1e" alt="Dashboard Metrics" width="3680" height="2390" data-path="images/rest-api/aa-examples/get-bot-visit-highlights.png" />

        ```http theme={null}
        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"]
        }
        ```

        ```json theme={null}
        {
          "info": {},  // removed for brevity
          "data": [
            {
              "metrics": [
                20640,
                8450,
                3646
              ],
              "dimensions": []
            }
          ]
        }
        ```
      </Tab>

      <Tab title="Citations by Day">
        Get a count of ChatGPT citations by day:

        <img src="https://mintcdn.com/profound-37face47/_84snNj2y4O4wlvX/images/rest-api/aa-examples/get-citations-by-bot-by-day.png?fit=max&auto=format&n=_84snNj2y4O4wlvX&q=85&s=42042eb802d987cc0f20ede22bedfe1a" alt="By Day Breakdown" width="3680" height="2390" data-path="images/rest-api/aa-examples/get-citations-by-bot-by-day.png" />

        <Tip>
          Note you can easily retrieve the full daily list broken down by bot by substituting:

          ```
          "dimensions": ["date", "bot_name"],
          "filters": [],
          ```
        </Tip>

        ```http theme={null}
        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",
          "dimensions": ["date"],
          "filters": [
              {"field": "bot_name", "operator": "is", "value": "ChatGPT-User"}
          ],
          "order_by": {
              "date": "desc"
          },
          "metrics": ["citations"]
        }
        ```

        ```json theme={null}
        {
            "info": {},  // removed for brevity
            "data": [
                {
                    "metrics": [
                        2698
                    ],
                    "dimensions": [
                        "2025-12-18"
                    ]
                },
                {
                    "metrics": [
                        2847
                    ],
                    "dimensions": [
                        "2025-12-17"
                    ]
                },
                {
                    "metrics": [
                        2986
                    ],
                    "dimensions": [
                        "2025-12-16"
                    ]
                },
                {
                    "metrics": [
                        3029
                    ],
                    "dimensions": [
                        "2025-12-15"
                    ]
                },
                {
                    "metrics": [
                        2075
                    ],
                    "dimensions": [
                        "2025-12-14"
                    ]
                },
                {
                    "metrics": [
                        1881
                    ],
                    "dimensions": [
                        "2025-12-13"
                    ]
                },
                {
                    "metrics": [
                        2717
                    ],
                    "dimensions": [
                        "2025-12-12"
                    ]
                }
            ]
        }
        ```
      </Tab>

      <Tab title="Page Visits by Provider">
        Get a count of page visits by bot type, scoped to a provider:

        <Info>
          Note the OpenAI **Platforms** selection in the top right.
        </Info>

        <img src="https://mintcdn.com/profound-37face47/_84snNj2y4O4wlvX/images/rest-api/aa-examples/get-page-visits-by-provider.png?fit=max&auto=format&n=_84snNj2y4O4wlvX&q=85&s=2234a9d846acd32bf2379d7ceca88089" alt="Page Visits by Provider" width="3680" height="2390" data-path="images/rest-api/aa-examples/get-page-visits-by-provider.png" />

        <Tip>
          See metrics for all providers by removing the filter.
        </Tip>

        ```http theme={null}
        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",
          "dimensions": ["path"],
          "filters": [
              {"field": "bot_provider", "operator": "is", "value": "openai"}
          ],
          "order_by": {"citations": "desc"},
          "metrics": ["citations", "indexing", "training"],
          "pagination": {
              "limit": 10,
              "offset": 0
          }
        }
        ```

        ```json theme={null}
        {
          "info": {},  // removed for brevity
          "data": [
              {
                "metrics": [
                  1255,
                  1614,
                  38
                ],
                "dimensions": [
                  "/"
                ]
              },
              {
                "metrics": [
                  643,
                  5,
                  1
                ],
                "dimensions": [
                  "/guides/generative-engine-optimization-geo-guide-2025"
                ]
              },
              {
                "metrics": [
                  603,
                  18,
                  3
                ],
                "dimensions": [
                  "/blog/now-tracking-gpt-5-2-in-chatgpt"
                ]
              },
              {
                "metrics": [
                  584,
                  7,
                  3
                ],
                "dimensions": [
                  "/blog/ai-platform-citation-patterns"
                ]
              },
              {
                "metrics": [
                  445,
                  1,
                  0
                ],
                "dimensions": [
                  "/blog/best-generative-engine-optimization-tools"
                ]
              },
              {
                "metrics": [
                  396,
                  14,
                  1
                ],
                "dimensions": [
                  "/profound-index"
                ]
              },
              {
              "metrics": [
                  385,
                  6,
                  1
              ],
              "dimensions": [
                  "/guides/what-is-answer-engine-optimization"
              ]
              },
              {
                "metrics": [
                  376,
                  2,
                  0
                ],
                "dimensions": [
                  "/blog/semrush-ai-visibility-toolkit-review"
                ]
              },
              {
                "metrics": [
                  372,
                  5,
                  2
                ],
                "dimensions": [
                  "/blog/understanding-grok-a-comprehensive-guide-to-grok-websearch-grok-deepsearch"
                ]
              },
              {
                "metrics": [
                  371,
                  7,
                  1
                ],
                "dimensions": [
                  "/blog/choosing-ai-visibility-provider"
                ]
              }
          ]
        }
        ```
      </Tab>
    </Tabs>

    ## Referral Reports

    <Tabs>
      <Tab title="Referrals By Platform">
        Get a count of referrals broken down by platform:

        <Info>
          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.
        </Info>

        <img src="https://mintcdn.com/profound-37face47/_84snNj2y4O4wlvX/images/rest-api/aa-examples/get-referrals-by-platform.png?fit=max&auto=format&n=_84snNj2y4O4wlvX&q=85&s=d4ef5e6ecb21e0f05cd03cbcc07fa22b" alt="Referrals By Platform" width="3680" height="2390" data-path="images/rest-api/aa-examples/get-referrals-by-platform.png" />

        ```http theme={null}
        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"]
        }
        ```

        ```json theme={null}
        {
          "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"
              ]
            }
          ]
        }
        ```
      </Tab>

      <Tab title="Bot Referrals By Day">
        Get a count of referrals from AI bots broken down by day:

        <img src="https://mintcdn.com/profound-37face47/_84snNj2y4O4wlvX/images/rest-api/aa-examples/get-referrals-by-day.png?fit=max&auto=format&n=_84snNj2y4O4wlvX&q=85&s=4af067d50a0ec61cba78d505098338a8" alt="Bot Referrals By Day" width="3680" height="2390" data-path="images/rest-api/aa-examples/get-referrals-by-day.png" />

        ```http theme={null}
        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": ["date"],
          "filters": [
            {"field": "referral_source", "operator": "not_in", "value": ["none", "other", "internal"]}
          ],
          "order_by": {"date": "desc"},
          "metrics": ["visits"]
        }
        ```

        ```json theme={null}
        {
          "info": {},  // removed for brevity
          "data": [
            {
              "metrics": [
                977
              ],
              "dimensions": [
                "2025-12-18"
              ]
            },
            {
              "metrics": [
                906
              ],
              "dimensions": [
                "2025-12-17"
              ]
            },
            {
              "metrics": [
                719
              ],
              "dimensions": [
                "2025-12-16"
              ]
            },
            {
              "metrics": [
                571
              ],
              "dimensions": [
                "2025-12-15"
              ]
            },
            {
              "metrics": [
                665
              ],
              "dimensions": [
                "2025-12-14"
              ]
            },
            {
              "metrics": [
                655
              ],
              "dimensions": [
                "2025-12-13"
              ]
            },
            {
              "metrics": [
                844
              ],
              "dimensions": [
                "2025-12-12"
              ]
            }
          ]
        }
        ```
      </Tab>

      <Tab title="Page Level Referrals">
        Get a count of referrals broken down by a given page:

        <Info>
          Note `/blog` in the search bar.
        </Info>

        <img src="https://mintcdn.com/profound-37face47/_84snNj2y4O4wlvX/images/rest-api/aa-examples/get-referrals-by-page.png?fit=max&auto=format&n=_84snNj2y4O4wlvX&q=85&s=bcd6917a05026d5aae2d3d95391101c9" alt="Page Level Referrals" width="3680" height="2390" data-path="images/rest-api/aa-examples/get-referrals-by-page.png" />

        <Tip>
          **% of Bot Referrals** can be calculated by summing the total number of referrals, and dividing each bot's referrals by the total.
        </Tip>

        ```http theme={null}
        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": ["path"],
          "filters": [
            {"field": "referral_source", "operator": "not_in", "value": ["none", "other", "internal"]},
            {"field": "path", "operator": "contains", "value": "/blog"}
          ],
          "metrics": ["visits"],
          "order_by": {"visits": "desc"},
          "pagination": {"limit": 10, "offset": 0}
        }
        ```

        ```json theme={null}
        {
          "info": {},  // removed for brevity
          "data": [
            {
              "metrics": [
                915
              ],
              "dimensions": [
                "/blog/ai-platform-citation-patterns"
              ]
            },
            {
              "metrics": [
                350
              ],
              "dimensions": [
                "/blog/bring-profound-data-directly-into-your-ai-workflow-with-mcp"
              ]
            },
            {
              "metrics": [
                99
              ],
              "dimensions": [
                "/blog/citation-overlap-strategy"
              ]
            },
            {
              "metrics": [
                87
              ],
              "dimensions": [
                "/blog/the-data-on-reddit-and-ai-search"
              ]
            },
            {
              "metrics": [
                65
              ],
              "dimensions": [
                "/blog/best-generative-engine-optimization-tools"
              ]
            },
            {
              "metrics": [
                58
              ],
              "dimensions": [
                "/blog/chatgpt-entity-update"
              ]
            },
            {
              "metrics": [
                56
              ],
              "dimensions": [
                "/blog/prompt-volumes-the-new-way-to-see-what-customers-ask-answer-engines"
              ]
            },
            {
              "metrics": [
                50
              ],
              "dimensions": [
                "/blog/seeing-what-customers-see-direct-ai-search-engine-monitoring-vs-api-limitations"
              ]
            },
            {
              "metrics": [
                40
              ],
              "dimensions": [
                "/blog/choosing-ai-visibility-provider"
              ]
            },
            {
              "metrics": [
                33
              ],
              "dimensions": [
                "/blog/ai-search-volatility"
              ]
            }
          ]
        }
        ```
      </Tab>

      <Tab title="Referrals By Bot">
        Get a count of referrals broken down by bot:

        <img src="https://mintcdn.com/profound-37face47/_84snNj2y4O4wlvX/images/rest-api/aa-examples/get-referrals-by-bot.png?fit=max&auto=format&n=_84snNj2y4O4wlvX&q=85&s=a50dbee002c88fe8a851dc3c3de364fa" alt="Referrals By Bot" width="3680" height="2390" data-path="images/rest-api/aa-examples/get-referrals-by-bot.png" />

        <Tip>
          **% of Referrals** here means the proportion of referred visits from non-internal sources that came from this bot.

          To calculate this, sum the total number of referrals in the response:

          `total_referrals = 222126 + 5172 + 102 + 39 + 22 + 2 = 227481`

          Then, for each bot, divide its referrals by the total:

          `ChatGPT % = (5172 / 227481) * 100 = 2.27%`

          ...
        </Tip>

        ```http theme={null}
        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"],
          "order_by": {"visits": "desc"}
        }
        ```

        ```json theme={null}
        {
          "info": {},  // removed for brevity
          "data": [
            {
              "metrics": [
                222126
              ],
              "dimensions": [
                "other"
              ]
            },
            {
              "metrics": [
                5172
              ],
              "dimensions": [
                "openai"
              ]
            },
            {
              "metrics": [
                102
              ],
              "dimensions": [
                "perplexity"
              ]
            },
            {
              "metrics": [
                39
              ],
              "dimensions": [
                "gemini"
              ]
            },
            {
              "metrics": [
                22
              ],
              "dimensions": [
                "anthropic"
              ]
            },
            {
              "metrics": [
                2
              ],
              "dimensions": [
                "deepseek"
              ]
            }
          ]
        }
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Hourly Reports (V2)">
    V2 endpoints provide reports at **hourly granularity**, with data bucketed by UTC hour. They support all the same dimensions, metrics and filters as V1, plus new fields unique to the hourly tables - **UTM** and **referral** traffic distinction.

    V1 daily aggregates are fixed to ET, which means users in other timezones had no way to get data bucketed into their own local days. V2 solves this: because data is bucketed by UTC hour, you can convert your local day boundaries to UTC and query data that lines up with your own calendar days.

    <Info>
      **V1 vs V2:** Use the **V1 (daily)** tab for daily pre-aggregated reports
      (EST-based). V2 is for hour-level granularity (UTC). Raw per-execution
      prompt-answer rows are available through `POST /v2/prompts/answers`.
    </Info>

    <Warning>
      **Fractional-offset timezones:** If your local timezone uses a fractional UTC offset (e.g. IST +5:30, Nepal +5:45), a single local hour spans two UTC hour buckets. When querying at hour-level granularity, request **2 consecutive hours** to get complete data for that local hour. See [Date Ranges & Timezones](/rest-api/date-ranges#fractional-offset-timezones) for details.
    </Warning>

    ## Bot Reports

    Returns bot traffic data aggregated from the hourly bot breakdown table.

    <Tabs>
      <Tab title="Bot Highlights">
        Get a count of visits by bot type:

        <img src="https://mintcdn.com/profound-37face47/_84snNj2y4O4wlvX/images/rest-api/aa-examples/get-bot-visit-highlights.png?fit=max&auto=format&n=_84snNj2y4O4wlvX&q=85&s=f61cba46eb807a2712365c4ad71b8e1e" alt="Dashboard Metrics" width="3680" height="2390" data-path="images/rest-api/aa-examples/get-bot-visit-highlights.png" />

        ```http theme={null}
        POST /v2/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"]
        }
        ```
      </Tab>

      <Tab title="Citations by Day">
        Get a count of ChatGPT citations by day:

        <img src="https://mintcdn.com/profound-37face47/_84snNj2y4O4wlvX/images/rest-api/aa-examples/get-citations-by-bot-by-day.png?fit=max&auto=format&n=_84snNj2y4O4wlvX&q=85&s=42042eb802d987cc0f20ede22bedfe1a" alt="By Day Breakdown" width="3680" height="2390" data-path="images/rest-api/aa-examples/get-citations-by-bot-by-day.png" />

        ```http theme={null}
        POST /v2/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",
          "dimensions": ["date"],
          "filters": [
            { "field": "bot_name", "operator": "is", "value": "ChatGPT-User" }
          ],
          "order_by": { "date": "desc" },
          "metrics": ["citations"]
        }
        ```
      </Tab>

      <Tab title="Page Visits by Provider">
        Get top paths by citations for a specific provider:

        <img src="https://mintcdn.com/profound-37face47/_84snNj2y4O4wlvX/images/rest-api/aa-examples/get-page-visits-by-provider.png?fit=max&auto=format&n=_84snNj2y4O4wlvX&q=85&s=2234a9d846acd32bf2379d7ceca88089" alt="Page Visits by Provider" width="3680" height="2390" data-path="images/rest-api/aa-examples/get-page-visits-by-provider.png" />

        ```http theme={null}
        POST /v2/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",
          "dimensions": ["path"],
          "filters": [
            { "field": "bot_provider", "operator": "is", "value": "openai" }
          ],
          "order_by": { "citations": "desc" },
          "metrics": ["citations", "indexing", "training"],
          "pagination": { "limit": 10, "offset": 0 }
        }
        ```
      </Tab>

      <Tab title="Hourly Bot Traffic">
        Get hourly bot traffic breakdown for a UTC day. Use UTC timestamps to align the query to your local calendar day:

        ```http theme={null}
        POST /v2/reports/bots HTTP/1.1
        Content-Type: application/json
        X-API-Key: your_api_key

        {
          "domain": "www.tryprofound.com",
          "start_date": "2025-12-16T00:00:00Z",
          "end_date": "2025-12-16T23:59:59Z",
          "dimensions": ["hour"],
          "metrics": ["count", "citations"],
          "order_by": { "hour": "asc" }
        }
        ```
      </Tab>
    </Tabs>

    ### Request body

    <table style={{ tableLayout: "fixed", width: "100%" }}>
      <colgroup>
        <col style={{ width: "26%" }} />

        <col style={{ width: "9%" }} />

        <col style={{ width: "8%" }} />

        <col style={{ width: "17%" }} />

        <col style={{ width: "40%" }} />
      </colgroup>

      <thead>
        <tr>
          <th style={{ whiteSpace: "nowrap" }}>Field</th>
          <th>Type</th>
          <th>Required</th>
          <th>Default</th>
          <th style={{ fontSize: "0.9em" }}>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td style={{ whiteSpace: "nowrap" }}><code>domain</code></td>
          <td>string</td>
          <td>yes</td>
          <td>-</td>
          <td style={{ fontSize: "0.9em" }}>Domain to query (e.g. <code>[www.tryprofound.com](http://www.tryprofound.com)</code>)</td>
        </tr>

        <tr>
          <td style={{ whiteSpace: "nowrap" }}><code>start\_date</code></td>
          <td>string</td>
          <td>yes</td>
          <td>-</td>
          <td style={{ fontSize: "0.9em" }}>Start date in UTC. Accepts <code>YYYY-MM-DD</code>, <code>YYYY-MM-DD HH:MM</code>, <code>YYYY-MM-DD HH:MM:SS</code>, or full ISO timestamp</td>
        </tr>

        <tr>
          <td style={{ whiteSpace: "nowrap" }}><code>end\_date</code></td>
          <td>string</td>
          <td>no</td>
          <td>now (UTC)</td>
          <td style={{ fontSize: "0.9em" }}>End date in UTC. Same formats as start\_date</td>
        </tr>

        <tr>
          <td style={{ whiteSpace: "nowrap" }}><code>metrics</code></td>
          <td>string\[]</td>
          <td>yes</td>
          <td>-</td>
          <td style={{ fontSize: "0.9em" }}>One or more metrics to return (see below)</td>
        </tr>

        <tr>
          <td style={{ whiteSpace: "nowrap" }}><code>dimensions</code></td>
          <td>string\[]</td>
          <td>no</td>
          <td><code>\[]</code></td>
          <td style={{ fontSize: "0.9em" }}>Fields to group results by (see below)</td>
        </tr>

        <tr>
          <td style={{ whiteSpace: "nowrap" }}><code>filters</code></td>
          <td>filter\[]</td>
          <td>no</td>
          <td><code>\[]</code></td>
          <td style={{ fontSize: "0.9em" }}>Filters to narrow results (see below)</td>
        </tr>

        <tr>
          <td style={{ whiteSpace: "nowrap" }}><code>date\_interval</code></td>
          <td>string</td>
          <td>no</td>
          <td><code>"day"</code></td>
          <td style={{ fontSize: "0.9em" }}>Bucket size for <code>date</code> dimension: <code>"hour"</code> or <code>"day"</code></td>
        </tr>

        <tr>
          <td style={{ whiteSpace: "nowrap" }}><code>order\_by</code></td>
          <td>object</td>
          <td>no</td>
          <td>first metric desc</td>
          <td style={{ fontSize: "0.9em" }}>Map of field -> <code>"asc"</code> or <code>"desc"</code></td>
        </tr>

        <tr>
          <td style={{ whiteSpace: "nowrap" }}><code>pagination</code></td>
          <td>object</td>
          <td>no</td>
          <td><code>{'{'} limit: 10000, offset: 0 {'}'}</code></td>
          <td style={{ fontSize: "0.9em" }}>Pagination settings</td>
        </tr>
      </tbody>
    </table>

    ### Metrics

    | Metric       | Description                                                               |
    | ------------ | ------------------------------------------------------------------------- |
    | `count`      | Total unique bot visits (all bot types)                                   |
    | `citations`  | Unique visits from AI assistant bots (e.g. ChatGPT-User, Perplexity-User) |
    | `indexing`   | Unique visits from web indexing bots (e.g. Googlebot, bingbot)            |
    | `training`   | Unique visits from AI training bots (e.g. GPTBot, ClaudeBot)              |
    | `last_visit` | Most recent visit timestamp                                               |

    ### Dimensions

    | Dimension      | Description                                                                                    |
    | -------------- | ---------------------------------------------------------------------------------------------- |
    | `date`         | Bucketed by `date_interval` (day or hour). UTC-based                                           |
    | `hour`         | Raw UTC hour bucket — equivalent to `date` + `date_interval: "hour"` with no extra aggregation |
    | `path`         | URL path                                                                                       |
    | `bot_name`     | Bot name (e.g. `ChatGPT-User`, `GPTBot`)                                                       |
    | `bot_provider` | Bot provider (e.g. `openai`, `anthropic`)                                                      |
    | `bot_type`     | Bot category: `ai_assistant`, `index`, `ai_training`, `ai_agent`                               |

    ### Filters

    | Field          | Operators                                                  | Values                                             |
    | -------------- | ---------------------------------------------------------- | -------------------------------------------------- |
    | `path`         | `is`, `not_is`, `contains`, `not_contains`, `in`, `not_in` | URL path string                                    |
    | `bot_name`     | `is`, `not_is`, `contains`, `not_contains`, `in`, `not_in` | Bot name string                                    |
    | `bot_provider` | `is`, `not_is`, `contains`, `not_contains`, `in`, `not_in` | Provider string                                    |
    | `bot_type`     | `is`, `not_is`, `in`, `not_in`                             | `ai_assistant`, `index`, `ai_training`, `ai_agent` |

    ***

    ## Referral Reports

    Returns referral traffic data aggregated from the hourly referral breakdown table.

    <Tabs>
      <Tab title="Referrals By Platform">
        Get a count of referrals broken down by platform (excluding internal traffic):

        <img src="https://mintcdn.com/profound-37face47/_84snNj2y4O4wlvX/images/rest-api/aa-examples/get-referrals-by-platform.png?fit=max&auto=format&n=_84snNj2y4O4wlvX&q=85&s=d4ef5e6ecb21e0f05cd03cbcc07fa22b" alt="Referrals By Platform" width="3680" height="2390" data-path="images/rest-api/aa-examples/get-referrals-by-platform.png" />

        ```http theme={null}
        POST /v2/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"]
        }
        ```
      </Tab>

      <Tab title="Bot Referrals By Day">
        Get a count of referrals from AI bots broken down by day:

        <img src="https://mintcdn.com/profound-37face47/_84snNj2y4O4wlvX/images/rest-api/aa-examples/get-referrals-by-day.png?fit=max&auto=format&n=_84snNj2y4O4wlvX&q=85&s=4af067d50a0ec61cba78d505098338a8" alt="Bot Referrals By Day" width="3680" height="2390" data-path="images/rest-api/aa-examples/get-referrals-by-day.png" />

        ```http theme={null}
        POST /v2/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": ["date"],
          "filters": [
            { "field": "referral_source", "operator": "not_in", "value": ["none", "other", "internal"] }
          ],
          "order_by": { "date": "desc" },
          "metrics": ["visits"]
        }
        ```
      </Tab>

      <Tab title="Page Level Referrals">
        Get top blog paths by external referral visits:

        <img src="https://mintcdn.com/profound-37face47/_84snNj2y4O4wlvX/images/rest-api/aa-examples/get-referrals-by-page.png?fit=max&auto=format&n=_84snNj2y4O4wlvX&q=85&s=bcd6917a05026d5aae2d3d95391101c9" alt="Page Level Referrals" width="3680" height="2390" data-path="images/rest-api/aa-examples/get-referrals-by-page.png" />

        ```http theme={null}
        POST /v2/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": ["path"],
          "filters": [
            { "field": "referral_source", "operator": "not_in", "value": ["none", "other", "internal"] },
            { "field": "path", "operator": "contains", "value": "/blog" }
          ],
          "metrics": ["visits"],
          "order_by": { "visits": "desc" },
          "pagination": { "limit": 10, "offset": 0 }
        }
        ```
      </Tab>

      <Tab title="Referrals By Bot">
        Get top referral sources ranked by visits:

        <img src="https://mintcdn.com/profound-37face47/_84snNj2y4O4wlvX/images/rest-api/aa-examples/get-referrals-by-bot.png?fit=max&auto=format&n=_84snNj2y4O4wlvX&q=85&s=a50dbee002c88fe8a851dc3c3de364fa" alt="Referrals By Bot" width="3680" height="2390" data-path="images/rest-api/aa-examples/get-referrals-by-bot.png" />

        ```http theme={null}
        POST /v2/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"],
          "order_by": { "visits": "desc" }
        }
        ```
      </Tab>

      <Tab title="UTM Traffic">
        Get UTM referral traffic by Hour:

        <img src="https://mintcdn.com/profound-37face47/gM-2pDTh8T5hVvln/images/rest-api/aa-examples/get-utm-traffic-hourly.png?fit=max&auto=format&n=gM-2pDTh8T5hVvln&q=85&s=ef4d4e3f68a345f9a9cd96705066c04e" alt="Hourly UTM Traffic" width="3456" height="1984" data-path="images/rest-api/aa-examples/get-utm-traffic-hourly.png" />

        ```http theme={null}
        POST /v2/reports/referrals HTTP/1.1
        Content-Type: application/json
        X-API-Key: your_api_key

        {
          "domain": "www.tryprofound.com",
          "start_date": "2025-12-16",
          "end_date": "2025-12-17",
          "dimensions": ["hour"],
          "filters": [
            { "field": "referral_type", "operator": "is", "value": "utm" }
          ],
          "metrics": ["visits"],
          "order_by": { "hour": "asc" }
        }
        ```
      </Tab>
    </Tabs>

    ### Request body

    <table style={{ tableLayout: "fixed", width: "100%" }}>
      <colgroup>
        <col style={{ width: "26%" }} />

        <col style={{ width: "9%" }} />

        <col style={{ width: "8%" }} />

        <col style={{ width: "17%" }} />

        <col style={{ width: "40%" }} />
      </colgroup>

      <thead>
        <tr>
          <th style={{ whiteSpace: "nowrap" }}>Field</th>
          <th>Type</th>
          <th>Required</th>
          <th>Default</th>
          <th style={{ fontSize: "0.9em" }}>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td style={{ whiteSpace: "nowrap" }}><code>domain</code></td>
          <td>string</td>
          <td>yes</td>
          <td>-</td>
          <td style={{ fontSize: "0.9em" }}>Domain to query</td>
        </tr>

        <tr>
          <td style={{ whiteSpace: "nowrap" }}><code>start\_date</code></td>
          <td>string</td>
          <td>yes</td>
          <td>-</td>
          <td style={{ fontSize: "0.9em" }}>Start date in UTC. Accepts <code>YYYY-MM-DD</code>, <code>YYYY-MM-DD HH:MM</code>, <code>YYYY-MM-DD HH:MM:SS</code>, or full ISO timestamp</td>
        </tr>

        <tr>
          <td style={{ whiteSpace: "nowrap" }}><code>end\_date</code></td>
          <td>string</td>
          <td>no</td>
          <td>now (UTC)</td>
          <td style={{ fontSize: "0.9em" }}>End date in UTC. Same formats as start\_date</td>
        </tr>

        <tr>
          <td style={{ whiteSpace: "nowrap" }}><code>metrics</code></td>
          <td>string\[]</td>
          <td>yes</td>
          <td>-</td>
          <td style={{ fontSize: "0.9em" }}>One or more metrics to return (see below)</td>
        </tr>

        <tr>
          <td style={{ whiteSpace: "nowrap" }}><code>dimensions</code></td>
          <td>string\[]</td>
          <td>no</td>
          <td><code>\[]</code></td>
          <td style={{ fontSize: "0.9em" }}>Fields to group results by (see below)</td>
        </tr>

        <tr>
          <td style={{ whiteSpace: "nowrap" }}><code>filters</code></td>
          <td>filter\[]</td>
          <td>no</td>
          <td><code>\[]</code></td>
          <td style={{ fontSize: "0.9em" }}>Filters to narrow results (see below)</td>
        </tr>

        <tr>
          <td style={{ whiteSpace: "nowrap" }}><code>date\_interval</code></td>
          <td>string</td>
          <td>no</td>
          <td><code>"day"</code></td>
          <td style={{ fontSize: "0.9em" }}>Bucket size for <code>date</code> dimension: <code>"hour"</code> or <code>"day"</code></td>
        </tr>

        <tr>
          <td style={{ whiteSpace: "nowrap" }}><code>order\_by</code></td>
          <td>object</td>
          <td>no</td>
          <td>first metric desc</td>
          <td style={{ fontSize: "0.9em" }}>Map of field -> <code>"asc"</code> or <code>"desc"</code></td>
        </tr>

        <tr>
          <td style={{ whiteSpace: "nowrap" }}><code>pagination</code></td>
          <td>object</td>
          <td>no</td>
          <td><code>{'{'} limit: 10000, offset: 0 {'}'}</code></td>
          <td style={{ fontSize: "0.9em" }}>Pagination settings</td>
        </tr>
      </tbody>
    </table>

    ### Metrics

    | Metric       | Description                 |
    | ------------ | --------------------------- |
    | `visits`     | Unique page visits          |
    | `last_visit` | Most recent visit timestamp |

    ### Dimensions

    | Dimension         | Description                                                                                    |
    | ----------------- | ---------------------------------------------------------------------------------------------- |
    | `date`            | Bucketed by `date_interval` (day or hour). UTC-based                                           |
    | `hour`            | Raw UTC hour bucket — equivalent to `date` + `date_interval: "hour"` with no extra aggregation |
    | `path`            | URL path                                                                                       |
    | `referral_source` | Referral source (e.g. `openai`, `perplexity`, `anthropic`, `other`, `internal`, `none`)        |
    | `referral_type`   | Traffic category: `internal`, `referer`, `utm`, `none`                                         |

    ### Filters

    | Field             | Operators                                                  | Values                               |
    | ----------------- | ---------------------------------------------------------- | ------------------------------------ |
    | `path`            | `is`, `not_is`, `contains`, `not_contains`, `in`, `not_in` | URL path string                      |
    | `referral_source` | `is`, `not_is`, `contains`, `not_contains`, `in`, `not_in` | Referral source string               |
    | `referral_type`   | `is`, `not_is`, `in`, `not_in`                             | `internal`, `referer`, `utm`, `none` |

    ***
  </Tab>
</Tabs>

## Raw Data

<Warning>
  The raw Agent Analytics endpoints `POST /v1/logs/raw` and
  `POST /v1/logs/raw/bots` were retired on 2026-06-10. Use the [V2 bot and
  referral report examples](/rest-api/examples/agent-analytics) for aggregated traffic data,
  or [V2 prompt answers](/rest-api/reports/query-answers-v2) for raw
  per-execution rows.
</Warning>