Skip to main content
This guide provides practical examples of common API requests. All examples use JSON format and require authentication via API key.
Replace your_api_key, your_category_id, and your_company_name with your actual values. Category IDs can be obtained from /v1/org/categories.
All examples use simplified date formats. For production use, please read Date Ranges & Timezones to understand timezone handling and avoid common pitfalls with date parameters.

​
Visibility Reports

Retrieve visibility metrics and performance data for companies within specific categories.

​
Top 5 Companies by Visibility Score

Get the companies with the highest visibility metrics in a category: 
POST /v1/reports/visibility HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "category_id": "your_category_id",
  "start_date": "2023-01-01",
  "end_date": "2023-01-07",
  "metrics": ["visibility_score"],
  "dimensions": ["asset_name"],
  "pagination": {
    "limit": 5
  }
}
Use case: Identify market leaders and benchmark against top performers. Track a specific company’s visibility performance with daily granularity: 
POST /v1/reports/visibility HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "category_id": "your_category_id",
  "start_date": "2023-01-01",
  "end_date": "2023-01-07",
  "date_interval": "day",
  "metrics": ["visibility_score"],
  "dimensions": ["date"],
  "filters": [
    {
      "field": "asset_name",
      "operator": "is",
      "value": "your_company_name"
    }
  ]
}
Use case: Monitor daily performance changes and identify trends.

​
Company Visibility by Topic and Prompt

Analyze visibility across different topics and prompt types for a specific company: 

Get the companies with the highest visibility metrics in a category:

```http
POST /v1/reports/visibility HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "category_id": "your_category_id",
  "start_date": "2023-01-01",
  "end_date": "2023-01-07",
  "metrics": ["visibility_score", "share_of_voice"],
  "dimensions": ["prompt", "topic"],
  "filters": [
    {
      "field": "asset_name",
      "operator": "is",
      "value": "your_company_name"
    }
  ]
}
Use case: Analyze visibility across different topics and prompt types for a specific company.

​
Company Visibility And Share of Voice by Platform

Analyze visibility across different platforms for a specific company: 
POST /v1/reports/visibility HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "category_id": "your_category_id",
  "start_date": "2023-01-01",
  "end_date": "2023-01-07",
  "metrics": ["visibility_score", "share_of_voice"],
  "dimensions": ["model"],
  "filters": [
    {
      "field": "asset_name",
      "operator": "is",
      "value": "your_company_name"
    }
  ]
}
Use case: Understand platform-specific performance and opportunities.

​
Company Visibility by Region

Analyze visibility across different regions for a specific company: 
POST /v1/reports/visibility HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "category_id": "your_category_id",
  "start_date": "2023-01-01",
  "end_date": "2023-01-07",
  "metrics": ["visibility_score", "share_of_voice"],
  "dimensions": ["region"],
  "filters": [
    {
      "field": "asset_name",
      "operator": "is",
      "value": "your_company_name"
    }
  ]
}
Use case: Identify regional strengths and weaknesses in visibility.

​
Sentiment Analysis

Analyze sentiment data and emotional responses across companies and topics.

​
Top 5 Companies by Positive Sentiment

Identify companies with the most positive sentiment: 
POST /v1/reports/sentiment HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "category_id": "your_category_id",
  "start_date": "2023-01-01",
  "end_date": "2023-01-07",
  "metrics": ["positive"],
  "dimensions": ["asset_name"],
  "pagination": { "limit": 5 }
}
Use case: Understand which companies have the best reputation and sentiment.

​
Company Sentiment by Theme

Analyze sentiment across different topics for a specific company: 
POST /v1/reports/sentiment HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "category_id": "your_category_id",
  "start_date": "2023-01-01",
  "end_date": "2023-01-07",
  "metrics": ["positive", "negative"],
  "dimensions": ["theme"],
  "pagination": {
    "limit": 5
  },
  "filters": [
    {
      "field": "asset_name",
      "operator": "is",
      "value": "your_company_name"
    }
  ]
}
Use case: Identify themes driving positive or negative sentiment for targeted improvements.

​
Citation Reports

Track mentions, references, and citation patterns across domains and pages.

​
Top 5 Most Cited Domains

Find the domains with the highest citation counts: 
POST /v1/reports/citations HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "category_id": "your_category_id",
  "start_date": "2023-01-01",
  "end_date": "2023-01-07",
  "metrics": ["count"],
  "dimensions": ["hostname"],
  "pagination": {
    "limit": 5
  }
}
Use case: Identify authoritative sources and influential domains in your category.

​
Share of Voice Analysis

Analyze the share of voice across all pages in a category: 
POST /v1/reports/citations HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "category_id": "your_category_id",
  "start_date": "2023-01-01",
  "end_date": "2023-01-07",
  "metrics": ["share_of_voice"],
  "dimensions": ["hostname", "page"]
}
Use case: Understand market share and competitive positioning across different pages.

​
Raw Data Access

Access unprocessed data for custom analysis and reporting.

​
Get Visibility Prompt Data

Retrieve raw visibility data for custom analysis: 
POST /v1/prompts/answers HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "category_id": "your_category_id",
  "start_date": "2023-01-01",
  "end_date": "2023-01-07",
  "filters": [
    {
      "field": "prompt_type",
      "operator": "is",
      "value": "visibility"
    }
  ]
}
Use case: Build custom dashboards and perform specialized analysis with raw data.

​
Agent Analytics

​
Get All Logs

Retrieve total log count 
POST /v1/logs/raw HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "domain": "www.tryprofound.com",
  "start_date": "2025-07-01",
  "end_date": "2025-07-31",
  "dimensions": [],
  "filters": [
    {"field": "method", "operator": "is", "value": "GET"},
    {"field": "status_code", "operator": "is", "value": 200}
  ],
  "metrics": ["count"],
  "pagination": {"limit": 100, "offset": 0}
}
Use case: See total traffic to your website.

​
Count Citations

Count citations for a given path by bot 
POST /v1/logs/raw/bots HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "domain": "www.tryprofound.com",
  "start_date": "2025-07-01",
  "end_date": "2025-07-31",
  "dimensions": ["path", "bot_name"],
  "filters": [
    {"field": "method", "operator": "is", "value": "GET"},
    {"field": "status_code", "operator": "is", "value": 200},
    {"field": "path", "operator": "is", "value": "/blog"},
    {"field": "bot_types", "operator": "contains", "value": "ai_assistant"}
  ],
  "metrics": ["count"],
  "pagination": {"limit": 1000, "offset": 0},
  "order_by": {"count": "desc"}
}
Use case: See which bots are citing this page and how many times.

​
Training Data

Get top 5 pages used for training 
POST /v1/logs/raw/bots HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "domain": "www.tryprofound.com",
  "start_date": "2025-07-01",
  "end_date": "2025-07-31",
  "dimensions": ["path"],
  "filters": [
    {"field": "method", "operator": "is", "value": "GET"},
    {"field": "status_code", "operator": "is", "value": 200},
    {"field": "bot_types", "operator": "contains", "value": "ai_training"}
  ],
  "metrics": ["count"],
  "order_by": {"count": "desc"},
  "pagination": {"limit": 5, "offset": 0}
}
Use case: Understand which pages are being scraped the most for training data.