NUDG3 Admin - Analytics API
The Admin - Analytics API from NUDG3 — 3 operation(s) for admin - analytics.
The Admin - Analytics API from NUDG3 — 3 operation(s) for admin - analytics.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/nudg3-ai:nudg3-ai-admin-analytics-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Nudg3 Admin - Analytics API
description: '# Nudg3 Brand Intelligence API
The Nudg3 API provides programmatic access to brand visibility analytics across AI providers.
## Public API v1
The Public API (`/api/v1/`) is designed for third-party integrations and provides:
### Analytics Endpoints (Tier 1 - Basic)
- Brand visibility scores and trends
- Sentiment analysis across AI responses
- Source citation tracking
- Prompt performance metrics
- Google AI Overview (AIO) coverage
### Export Endpoints (Tier 2 - Premium)
- Full response data exports (CSV/TSV)
- Source citations bulk download
- Dashboard time-series data
- Prompt-mention pair exports
## Authentication
### API Key (Public API v1)
```bash
curl -H "Authorization: Bearer nudg3_live_ak_xxx..." \
https://api.nudg3.com/api/v1/dashboard
```
### JWT (Dashboard API)
```bash
curl -H "Authorization: Bearer eyJ..." \
https://api.nudg3.com/analytics/dashboard
```
## Rate Limits
| Tier | Per Minute | Per Hour | Monthly Quota |
|------|------------|----------|---------------|
| Basic | 60 | 600 | 5,000 |
| Premium | 300 | 3,000 | 50,000 |
## Response Format
All responses follow a standard envelope:
```json
{
"success": true,
"data": { ... },
"message": "Success"
}
```
## Support
- Documentation: https://docs.nudg3.com
- API Status: https://status.nudg3.com
- Support: support@nudg3.com'
version: 1.1.0
termsOfService: https://nudg3.com/terms
contact:
name: Nudg3 API Support
url: https://nudg3.com/support
email: support@nudg3.com
license:
name: Proprietary
url: https://nudg3.com/license
servers:
- url: https://api.nudg3.com
description: Production API
- url: https://api-staging.nudg3.com
description: Staging API (for testing)
- url: http://localhost:8000
description: Local Development
tags:
- name: Admin - Analytics
paths:
/admin/analytics/revenue:
get:
tags:
- Admin - Analytics
summary: Get revenue overview
description: Get comprehensive revenue metrics including MRR, ARPU, and revenue by plan (super user only)
operationId: get_revenue_overview_admin_analytics_revenue_get
security:
- HTTPBearer: []
parameters:
- name: start_date
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: 'null'
description: Start date for trend analysis (ISO 8601)
title: Start Date
description: Start date for trend analysis (ISO 8601)
- name: end_date
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: 'null'
description: End date for trend analysis (ISO 8601)
title: End Date
description: End date for trend analysis (ISO 8601)
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RevenueOverviewResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/admin/analytics/trial-health:
get:
tags:
- Admin - Analytics
summary: Get trial health dashboard
description: Get trial conversion metrics and identify at-risk trials (super user only)
operationId: get_trial_health_admin_analytics_trial_health_get
security:
- HTTPBearer: []
parameters:
- name: days_ahead
in: query
required: false
schema:
type: integer
maximum: 90
minimum: 1
description: Days ahead to check for expiring trials
default: 7
title: Days Ahead
description: Days ahead to check for expiring trials
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TrialHealthResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/admin/analytics/churn-risk:
get:
tags:
- Admin - Analytics
summary: Get churn risk dashboard
description: Get subscriptions at risk of churn (failed payments, grace periods, cancellations) (super user only)
operationId: get_churn_risk_admin_analytics_churn_risk_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ChurnRiskResponse'
security:
- HTTPBearer: []
components:
schemas:
AtRiskTrials:
properties:
count:
type: integer
title: Count
description: Number of at-risk trials
workspaces:
items:
$ref: '#/components/schemas/AtRiskTrial'
type: array
title: Workspaces
description: At-risk trial details
type: object
required:
- count
title: AtRiskTrials
description: List of at-risk trials
SuspendedSubscription:
properties:
subscription_id:
type: string
title: Subscription Id
description: Subscription UUID
workspace_id:
type: string
title: Workspace Id
description: Workspace UUID
workspace_name:
type: string
title: Workspace Name
description: Workspace name
company_name:
type: string
title: Company Name
description: Company name
plan_name:
type: string
title: Plan Name
description: Subscription plan name
suspended_at:
anyOf:
- type: string
- type: 'null'
title: Suspended At
description: Suspension date (ISO 8601)
failed_payment_count:
type: integer
title: Failed Payment Count
description: Number of failed payment attempts
type: object
required:
- subscription_id
- workspace_id
- workspace_name
- company_name
- plan_name
- failed_payment_count
title: SuspendedSubscription
description: Suspended subscription
ConversionMetrics:
properties:
total_trials:
type: integer
title: Total Trials
description: Total trials started in period
conversions:
type: integer
title: Conversions
description: Trials converted to paid
conversion_rate:
type: number
title: Conversion Rate
description: Conversion rate percentage
period_days:
type: integer
title: Period Days
description: Analysis period in days
type: object
required:
- total_trials
- conversions
- conversion_rate
- period_days
title: ConversionMetrics
description: Trial conversion statistics
FailedPayments:
properties:
count:
type: integer
title: Count
description: Number of subscriptions with failed payments
subscriptions:
items:
$ref: '#/components/schemas/FailedPaymentSubscription'
type: array
title: Subscriptions
description: Failed payment details
type: object
required:
- count
title: FailedPayments
description: List of subscriptions with failed payments
FailedPaymentSubscription:
properties:
subscription_id:
type: string
title: Subscription Id
description: Subscription UUID
workspace_id:
type: string
title: Workspace Id
description: Workspace UUID
workspace_name:
type: string
title: Workspace Name
description: Workspace name
company_name:
type: string
title: Company Name
description: Company name
plan_name:
type: string
title: Plan Name
description: Subscription plan name
failed_payment_count:
type: integer
title: Failed Payment Count
description: Number of failed payment attempts
status:
type: string
title: Status
description: Subscription status
grace_period_ends:
anyOf:
- type: string
- type: 'null'
title: Grace Period Ends
description: Grace period end date (ISO 8601)
type: object
required:
- subscription_id
- workspace_id
- workspace_name
- company_name
- plan_name
- failed_payment_count
- status
title: FailedPaymentSubscription
description: Subscription with failed payments
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ChurnRiskResponse:
properties:
failed_payments:
$ref: '#/components/schemas/FailedPayments'
description: Subscriptions with failed payments
grace_period:
$ref: '#/components/schemas/GracePeriodSubscriptions'
description: Subscriptions in grace period
scheduled_cancellations:
$ref: '#/components/schemas/ScheduledCancellations'
description: Subscriptions with scheduled cancellations
suspended:
$ref: '#/components/schemas/SuspendedSubscriptions'
description: Suspended subscriptions
type: object
required:
- failed_payments
- grace_period
- scheduled_cancellations
- suspended
title: ChurnRiskResponse
description: Complete churn risk dashboard response
example:
failed_payments:
count: 5
subscriptions:
- company_name: Acme Corp
failed_payment_count: 2
grace_period_ends: '2025-01-15'
plan_name: Base Package
status: ACTIVE
subscription_id: 123e4567-e89b-12d3-a456-426614174000
workspace_id: 123e4567-e89b-12d3-a456-426614174001
workspace_name: Marketing Analytics
grace_period:
count: 3
subscriptions: []
scheduled_cancellations:
count: 8
subscriptions: []
suspended:
count: 1
subscriptions: []
RevenueTrendPoint:
properties:
date:
type: string
title: Date
description: Date (ISO 8601)
mrr:
type: number
title: Mrr
description: MRR on this date (ZAR)
type: object
required:
- date
- mrr
title: RevenueTrendPoint
description: Single data point in revenue trend
TrialHealthResponse:
properties:
conversion_metrics:
$ref: '#/components/schemas/ConversionMetrics'
description: Conversion statistics
expiring_soon:
$ref: '#/components/schemas/ExpiringTrials'
description: Trials expiring soon
at_risk:
$ref: '#/components/schemas/AtRiskTrials'
description: Trials at risk of not converting
type: object
required:
- conversion_metrics
- expiring_soon
- at_risk
title: TrialHealthResponse
description: Complete trial health dashboard response
example:
at_risk:
count: 3
workspaces: []
conversion_metrics:
conversion_rate: 68.0
conversions: 102
period_days: 90
total_trials: 150
expiring_soon:
count: 12
workspaces:
- company_id: 123e4567-e89b-12d3-a456-426614174001
company_name: Acme Corp
days_remaining: 5
trial_end_date: '2025-01-15'
trial_started_at: '2024-12-15'
workspace_id: 123e4567-e89b-12d3-a456-426614174000
workspace_name: Marketing Analytics
GracePeriodSubscriptions:
properties:
count:
type: integer
title: Count
description: Number of subscriptions in grace period
subscriptions:
items:
$ref: '#/components/schemas/GracePeriodSubscription'
type: array
title: Subscriptions
description: Grace period details
type: object
required:
- count
title: GracePeriodSubscriptions
description: List of subscriptions in grace period
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
ScheduledCancellations:
properties:
count:
type: integer
title: Count
description: Number of scheduled cancellations
subscriptions:
items:
$ref: '#/components/schemas/ScheduledCancellation'
type: array
title: Subscriptions
description: Scheduled cancellation details
type: object
required:
- count
title: ScheduledCancellations
description: List of scheduled cancellations
RevenueSummary:
properties:
total_mrr:
type: number
title: Total Mrr
description: Total Monthly Recurring Revenue (ZAR)
active_subscriptions:
type: integer
title: Active Subscriptions
description: Number of active subscriptions
arpu:
type: number
title: Arpu
description: Average Revenue Per User (ZAR)
calculated_at:
type: string
title: Calculated At
description: When metrics were calculated (ISO 8601)
type: object
required:
- total_mrr
- active_subscriptions
- arpu
- calculated_at
title: RevenueSummary
description: Summary revenue metrics
ScheduledCancellation:
properties:
subscription_id:
type: string
title: Subscription Id
description: Subscription UUID
workspace_id:
type: string
title: Workspace Id
description: Workspace UUID
workspace_name:
type: string
title: Workspace Name
description: Workspace name
company_name:
type: string
title: Company Name
description: Company name
plan_name:
type: string
title: Plan Name
description: Subscription plan name
cancels_at:
type: string
title: Cancels At
description: Cancellation date (ISO 8601)
days_until_cancellation:
type: integer
title: Days Until Cancellation
description: Days until cancellation
cancelled_at:
anyOf:
- type: string
- type: 'null'
title: Cancelled At
description: When cancellation was requested (ISO 8601)
type: object
required:
- subscription_id
- workspace_id
- workspace_name
- company_name
- plan_name
- cancels_at
- days_until_cancellation
title: ScheduledCancellation
description: Subscription with scheduled cancellation
SuspendedSubscriptions:
properties:
count:
type: integer
title: Count
description: Number of suspended subscriptions
subscriptions:
items:
$ref: '#/components/schemas/SuspendedSubscription'
type: array
title: Subscriptions
description: Suspended subscription details
type: object
required:
- count
title: SuspendedSubscriptions
description: List of suspended subscriptions
PlanRevenue:
properties:
plan_name:
type: string
title: Plan Name
description: Subscription plan name
plan_slug:
type: string
title: Plan Slug
description: Plan slug identifier
price_monthly:
type: number
title: Price Monthly
description: Plan monthly price (ZAR)
subscription_count:
type: integer
title: Subscription Count
description: Number of active subscriptions
plan_revenue:
type: number
title: Plan Revenue
description: Total revenue from this plan (ZAR)
type: object
required:
- plan_name
- plan_slug
- price_monthly
- subscription_count
- plan_revenue
title: PlanRevenue
description: Revenue breakdown by subscription plan
AtRiskTrial:
properties:
workspace_id:
type: string
title: Workspace Id
description: Workspace UUID
workspace_name:
type: string
title: Workspace Name
description: Workspace name
company_name:
type: string
title: Company Name
description: Company name
trial_end_date:
type: string
title: Trial End Date
description: Trial end date (ISO 8601)
days_remaining:
type: integer
title: Days Remaining
description: Days until trial expires
onboarded:
type: boolean
title: Onboarded
description: Whether workspace completed onboarding
active_prompts:
type: integer
title: Active Prompts
description: Number of active prompt templates
risk_factors:
items:
type: string
type: array
title: Risk Factors
description: Identified risk factors
type: object
required:
- workspace_id
- workspace_name
- company_name
- trial_end_date
- days_remaining
- onboarded
- active_prompts
title: AtRiskTrial
description: Workspace at risk of not converting
ExpiringTrial:
properties:
workspace_id:
type: string
title: Workspace Id
description: Workspace UUID
workspace_name:
type: string
title: Workspace Name
description: Workspace name
company_id:
type: string
title: Company Id
description: Company UUID
company_name:
type: string
title: Company Name
description: Company name
trial_end_date:
type: string
title: Trial End Date
description: Trial end date (ISO 8601)
days_remaining:
type: integer
title: Days Remaining
description: Days until trial expires
trial_started_at:
anyOf:
- type: string
- type: 'null'
title: Trial Started At
description: Trial start date (ISO 8601)
type: object
required:
- workspace_id
- workspace_name
- company_id
- company_name
- trial_end_date
- days_remaining
title: ExpiringTrial
description: Workspace with trial expiring soon
RevenueOverviewResponse:
properties:
summary:
$ref: '#/components/schemas/RevenueSummary'
by_plan:
items:
$ref: '#/components/schemas/PlanRevenue'
type: array
title: By Plan
description: Revenue breakdown by plan
trend:
items:
$ref: '#/components/schemas/RevenueTrendPoint'
type: array
title: Trend
description: Revenue trend over time
type: object
required:
- summary
title: RevenueOverviewResponse
description: Complete revenue overview response
example:
by_plan:
- plan_name: Base Package
plan_revenue: 25415.0
plan_slug: base-package
price_monthly: 299.0
subscription_count: 85
summary:
active_subscriptions: 125
arpu: 360.0
calculated_at: '2025-01-10T12:00:00'
total_mrr: 45000.0
trend:
- date: '2025-01-01'
mrr: 42000.0
ExpiringTrials:
properties:
count:
type: integer
title: Count
description: Number of expiring trials
workspaces:
items:
$ref: '#/components/schemas/ExpiringTrial'
type: array
title: Workspaces
description: Expiring trial details
type: object
required:
- count
title: ExpiringTrials
description: List of expiring trials
GracePeriodSubscription:
properties:
subscription_id:
type: string
title: Subscription Id
description: Subscription UUID
workspace_id:
type: string
title: Workspace Id
description: Workspace UUID
workspace_name:
type: string
title: Workspace Name
description: Workspace name
company_name:
type: string
title: Company Name
description: Company name
plan_name:
type: string
title: Plan Name
description: Subscription plan name
grace_period_ends:
type: string
title: Grace Period Ends
description: Grace period end date (ISO 8601)
days_remaining:
type: integer
title: Days Remaining
description: Days remaining in grace period
failed_payment_count:
type: integer
title: Failed Payment Count
description: Number of failed payment attempts
type: object
required:
- subscription_id
- workspace_id
- workspace_name
- company_name
- plan_name
- grace_period_ends
- days_remaining
- failed_payment_count
title: GracePeriodSubscription
description: Subscription in grace period
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: '
API Key authentication for Public API v1 endpoints.
**Format:** `nudg3_live_ak_xxx...` or `nudg3_test_ak_xxx...`
**Usage:**
```
Authorization: Bearer nudg3_live_ak_your_key_here
```
Or use the header:
```
X-API-Key: nudg3_live_ak_your_key_here
```
**Obtain API Keys:**
Generate API keys from your Nudg3 dashboard under Settings > API Keys.
**Tiers:**
- **Basic:** `read:analytics` scope - Analytics endpoints only
- **Premium:** `read:analytics` + `export:data` scopes - Analytics + Exports
'
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: '
JWT authentication for internal dashboard endpoints.
Obtain tokens via `/auth/login` endpoint.
'
externalDocs:
description: Nudg3 API Documentation
url: https://docs.nudg3.com/api