Analytics Endpoints

The Analytics endpoints provide access to brand visibility metrics, sentiment analysis, source tracking, and prompt performance data.

Required Scope: read:analytics Tier: Basic (Tier 1)

Dashboard

Get brand visibility dashboard metrics.

Request

GET /api/v1/dashboard

Parameters

Parameter	Type	Required	Description
`start_date`	date	No	Start date (YYYY-MM-DD). Defaults to 30 days ago
`end_date`	date	No	End date (YYYY-MM-DD). Defaults to today
`models`	array	No	Filter by AI provider names (openai, anthropic, google, perplexity)
`model_ids`	array	No	Filter by specific model IDs (gpt-4o-mini, claude-3-5-haiku, etc.)
`tags`	array	No	Filter by prompt template tags

Workspace Isolation: The workspace is automatically determined from your API key. You don't need to pass a workspace_id parameter.

Example Request

curl -X GET "https://api.nudg3.ai/api/v1/dashboard?start_date=2026-01-01&end_date=2026-01-31" \
  -H "Authorization: Bearer nudg3_live_ak_your_key"

Response

{
  "success": true,
  "data": {
    "brands": {
      "YourBrand": {
        "visibility_score": 78.5,
        "sentiment_avg": 0.72,
        "position_avg": 2.3,
        "mention_count": 150
      },
      "Competitor1": {
        "visibility_score": 65.2,
        "sentiment_avg": 0.58,
        "position_avg": 3.1,
        "mention_count": 98
      }
    },
    "total_mentions": 1250,
    "total_sources": 85,
    "date_range": {
      "start": "2026-01-01",
      "end": "2026-01-31"
    }
  },
  "message": "Dashboard analytics retrieved for 5 brands"
}

Brands

Get list of brands/competitors for the workspace.

List Brands

GET /api/v1/brands

Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`per_page`	integer	No	Items per page (max 100, default: 50)
`discovery_status`	string	No	Filter by discovery status
`is_active`	boolean	No	Filter by active status (default: true)

Example Request

curl -X GET "https://api.nudg3.ai/api/v1/brands?page=1&per_page=20" \
  -H "Authorization: Bearer nudg3_live_ak_your_key"

Response

{
  "success": true,
  "data": {
    "competitors": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "YourBrand",
        "domain": "yourbrand.com",
        "icon_url": "https://logo.clearbit.com/yourbrand.com",
        "is_primary": true,
        "is_active": true
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "Competitor",
        "domain": "competitor.com",
        "icon_url": "https://logo.clearbit.com/competitor.com",
        "is_primary": false,
        "is_active": true
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total_items": 5,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false
    }
  },
  "message": "Retrieved 5 brands"
}

Get Brand Details

GET /api/v1/brands/{brand_id}

Get detailed visibility metrics for a specific brand.

Parameters

Parameter	Type	Required	Description
`brand_id`	UUID	Yes	Brand ID (path parameter)
`start_date`	date	No	Start date for analytics period (YYYY-MM-DD)
`end_date`	date	No	End date for analytics period (YYYY-MM-DD)
`models`	array	No	Filter by AI provider names
`model_ids`	array	No	Filter by specific model IDs
`tags`	array	No	Filter by prompt template tags

Prompts

Get prompt templates with performance metrics.

List Prompts

GET /api/v1/prompts

Parameters

Parameter	Type	Required	Description
`brand_id`	UUID	Yes	Brand ID to get prompt performance for
`start_date`	date	No	Filter start date
`end_date`	date	No	Filter end date
`models`	array	No	Filter by AI provider names
`model_ids`	array	No	Filter by model IDs
`tags`	array	No	Filter by prompt template tags

Example Request

curl -X GET "https://api.nudg3.ai/api/v1/prompts?brand_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer nudg3_live_ak_your_key"

Response

{
  "success": true,
  "data": {
    "prompts": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "text": "What is the best CRM software for small businesses?",
        "tags": ["crm", "small-business"],
        "is_active": true,
        "performance": {
          "response_count": 245,
          "avg_visibility": 72.3
        }
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total_items": 25,
      "total_pages": 1
    }
  }
}

Get Prompt Details

GET /api/v1/prompts/{prompt_id}

Sources

Get domain-level source analytics with authority scores and usage metrics.

Request

GET /api/v1/sources

Parameters

Parameter	Type	Required	Description
`start_date`	date	No	Filter start date (YYYY-MM-DD)
`end_date`	date	No	Filter end date (YYYY-MM-DD)
`models`	array	No	Filter by AI provider names
`model_ids`	array	No	Filter by model IDs
`tags`	array	No	Filter by prompt template tags
`prompt_template_id`	UUID	No	Filter by specific prompt template
`page`	integer	No	Page number (default: 1)
`per_page`	integer	No	Items per page (max 100, default: 20)

Example Request

curl -X GET "https://api.nudg3.ai/api/v1/sources?start_date=2026-01-01&end_date=2026-01-31" \
  -H "Authorization: Bearer nudg3_live_ak_your_key"

Response

{
  "success": true,
  "data": {
    "sources": [
      {
        "domain": "reddit.com",
        "source_type": "forum",
        "citation_count": 342,
        "authority_score": 85.2,
        "usage_percentage": 27.4,
        "last_cited": "2026-01-12T10:30:00Z",
        "daily_chart": [
          {"date": "2026-01-10", "count": 45},
          {"date": "2026-01-11", "count": 52},
          {"date": "2026-01-12", "count": 38}
        ]
      },
      {
        "domain": "g2.com",
        "source_type": "review_site",
        "citation_count": 198,
        "authority_score": 92.1,
        "usage_percentage": 15.8,
        "last_cited": "2026-01-12T09:15:00Z",
        "daily_chart": [
          {"date": "2026-01-10", "count": 22},
          {"date": "2026-01-11", "count": 28},
          {"date": "2026-01-12", "count": 19}
        ]
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total_items": 85,
      "total_pages": 2,
      "has_next": true,
      "has_prev": false
    }
  },
  "message": "Retrieved 50 sources"
}

URLs

Get URL-level citation data.

List URLs

GET /api/v1/urls

Parameters

Parameter	Type	Required	Description
`start_date`	date	No	Filter start date (YYYY-MM-DD)
`end_date`	date	No	Filter end date (YYYY-MM-DD)
`models`	array	No	Filter by AI provider names
`model_ids`	array	No	Filter by model IDs
`tags`	array	No	Filter by prompt template tags
`source_id`	string	No	Filter by source ID
`page`	integer	No	Page number (default: 1)
`per_page`	integer	No	Items per page (max 100, default: 20)

Example Request

curl -X GET "https://api.nudg3.ai/api/v1/urls?source_id=abc123&page=1" \
  -H "Authorization: Bearer nudg3_live_ak_your_key"

Response

{
  "success": true,
  "data": {
    "urls": [
      {
        "url": "https://reddit.com/r/CRM/comments/abc123",
        "domain": "reddit.com",
        "title": "Best CRM for startups?",
        "citation_count": 45,
        "first_cited": "2026-01-05T14:20:00Z",
        "last_cited": "2026-01-12T10:30:00Z"
      },
      {
        "url": "https://reddit.com/r/smallbusiness/comments/def456",
        "domain": "reddit.com",
        "title": "CRM recommendations thread",
        "citation_count": 32,
        "first_cited": "2026-01-08T09:15:00Z",
        "last_cited": "2026-01-11T16:45:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total_items": 156,
      "total_pages": 4,
      "has_next": true,
      "has_prev": false
    }
  },
  "message": "Retrieved 50 URLs"
}

Detailed URL Analytics

GET /api/v1/urls-detailed

Returns URL analytics with trend data over time.

Parameters

Parameter	Type	Required	Description
`start_date`	date	No	Filter start date (YYYY-MM-DD)
`end_date`	date	No	Filter end date (YYYY-MM-DD)
`models`	array	No	Filter by AI provider names
`model_ids`	array	No	Filter by model IDs
`tags`	array	No	Filter by prompt template tags
`prompt_template_id`	UUID	No	Filter by prompt template ID
`page`	integer	No	Page number (default: 1)
`per_page`	integer	No	Items per page (max 100, default: 20)

Response

{
  "success": true,
  "data": {
    "urls": [
      {
        "url": "https://reddit.com/r/CRM/comments/abc123",
        "domain": "reddit.com",
        "title": "Best CRM for startups?",
        "citation_count": 45,
        "first_cited": "2026-01-05T14:20:00Z",
        "last_cited": "2026-01-12T10:30:00Z",
        "daily_chart": [
          {"date": "2026-01-10", "count": 8},
          {"date": "2026-01-11", "count": 12},
          {"date": "2026-01-12", "count": 5}
        ],
        "providers_citing": ["openai", "anthropic", "perplexity"]
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total_items": 156,
      "total_pages": 4
    }
  }
}
 
---
 
## AI Responses
 
Get list of AI provider responses.
 
### Request

GET /api/v1/responses


### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `start_date` | date | No | Filter start date |
| `end_date` | date | No | Filter end date |
| `models` | array | No | Filter by AI provider names |
| `model_ids` | array | No | Filter by model IDs |
| `tags` | array | No | Filter by prompt template tags |
| `has_content` | boolean | No | Filter by content availability |
| `page` | integer | No | Page number |
| `per_page` | integer | No | Items per page |

### Response

```json
{
  "success": true,
  "data": {
    "responses": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "provider": "openai",
        "model": "gpt-4o",
        "content_preview": "Based on my analysis, the top CRM solutions for small businesses include HubSpot, Salesforce Essentials, and...",
        "created_at": "2026-01-12T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total_items": 1250
    }
  }
}

Response content is truncated to 200 characters in this endpoint. Use the Premium export endpoints to get full response data.

AI Overview Metrics

Get Google AI Overview (AIO) coverage metrics. These metrics track how often your brand appears in Google's AI-generated overview responses.

Request

GET /api/v1/aio-metrics

Parameters

Parameter	Type	Required	Description
`start_date`	date	No	Filter start date (YYYY-MM-DD)
`end_date`	date	No	Filter end date (YYYY-MM-DD)
`tags`	array	No	Filter by prompt template tags
`target_brand_id`	UUID	No	Brand ID to check visibility for

Example Request

curl -X GET "https://api.nudg3.ai/api/v1/aio-metrics?start_date=2026-01-01&end_date=2026-01-31" \
  -H "Authorization: Bearer nudg3_live_ak_your_key"

Response

{
  "success": true,
  "data": {
    "coverage_rate": 68.5,
    "total_queries": 500,
    "queries_with_aio": 342,
    "brand_coverage": {
      "YourBrand": {
        "appearance_rate": 45.2,
        "avg_position": 1.8,
        "total_appearances": 155
      }
    },
    "trend": [
      {"date": "2026-01-10", "coverage_rate": 65.0},
      {"date": "2026-01-11", "coverage_rate": 68.2},
      {"date": "2026-01-12", "coverage_rate": 71.5}
    ]
  },
  "message": "AIO metrics retrieved successfully"
}

Per-Prompt AIO Metrics

GET /api/v1/aio-metrics/prompt/{prompt_id}

Get AIO coverage metrics for a specific prompt template.

Parameters

Parameter	Type	Required	Description
`prompt_id`	UUID	Yes	Prompt template ID (path parameter)
`start_date`	date	No	Filter start date
`end_date`	date	No	Filter end date
`target_brand_id`	UUID	No	Filter metrics for a specific brand

Response

{
  "success": true,
  "data": {
    "prompt_id": "550e8400-e29b-41d4-a716-446655440000",
    "prompt_text": "What is the best CRM software?",
    "coverage_rate": 72.5,
    "total_queries": 120,
    "queries_with_aio": 87,
    "brand_appearances": {
      "YourBrand": 45,
      "Competitor1": 32,
      "Competitor2": 28
    }
  }
}
 
---
 
## Filters
 
Get available filter values for analytics queries. Use this endpoint to populate filter dropdowns in your UI.
 
### Request

GET /api/v1/filters


### Parameters

This endpoint takes no query parameters. The workspace is automatically determined from your API key.

### Example Request

```bash
curl -X GET "https://api.nudg3.ai/api/v1/filters" \
  -H "Authorization: Bearer nudg3_live_ak_your_key"

Response

{
  "success": true,
  "data": {
    "providers": ["openai", "anthropic", "google", "perplexity"],
    "models": [
      {"id": "gpt-4o", "provider": "openai", "name": "GPT-4o"},
      {"id": "gpt-4o-mini", "provider": "openai", "name": "GPT-4o Mini"},
      {"id": "claude-3-5-sonnet", "provider": "anthropic", "name": "Claude 3.5 Sonnet"},
      {"id": "gemini-pro", "provider": "google", "name": "Gemini Pro"}
    ],
    "tags": ["product", "comparison", "review", "pricing", "support"],
    "brands": [
      {"id": "550e8400-e29b-41d4-a716-446655440000", "name": "YourBrand", "is_primary": true},
      {"id": "550e8400-e29b-41d4-a716-446655440001", "name": "Competitor1", "is_primary": false}
    ],
    "date_range": {
      "earliest_data": "2025-06-15",
      "latest_data": "2026-01-12"
    }
  },
  "message": "Filter values retrieved successfully"
}

The date_range field shows the available data range for your workspace. Use this to set appropriate date picker bounds in your UI.

Error Responses

All endpoints may return the following errors:

Code	Error	Description
400	Bad Request	Invalid parameters
401	Unauthorized	Invalid or missing API key
403	Forbidden	Insufficient scope
429	Rate Limit Exceeded	Too many requests

See Error Handling for details.

Analytics Endpoints

On this page