The sources analytics endpoint returns a comprehensive view of source domain activity — aggregate stats, category breakdown, daily performance of top domains, and opportunity domains where your brand is not yet mentioned.
Get sources analytics
GET /projects/{project_id}/sources/analytics
Path parameters
| Param | Type | Description |
|---|
project_id | string (UUID) | The project ID |
Query parameters
| Param | Type | Default | Description |
|---|
duration_days | integer | 7 | Days to look back |
date_from | string | — | Start date (YYYY-MM-DD) |
date_to | string | — | End date (YYYY-MM-DD) |
providers | string | — | Comma-separated provider filter |
curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/sources/analytics?duration_days=7" \
-H "X-API-Key: tk_live_..."
resp = client.get(f"/projects/{project_id}/sources/analytics", params={"duration_days": 7})
const resp = await fetch(`${BASE}/projects/${projectId}/sources/analytics?duration_days=7`, { headers });
Response
{
"success": true,
"data": {
"stats": {
"total_sources": 245,
"total_citations": 1832
},
"category_breakdown": {
"corporate": 12.5,
"editorial": 35.2,
"institutional": 18.0,
"reference": 22.1,
"ugc": 8.7,
"other": 3.5
},
"performance_chart": {
"dates": ["2026-02-28", "2026-03-01", "2026-03-02"],
"series": [
{
"domain": "techcrunch.com",
"values": [8.2, 7.5, 9.1]
},
{
"domain": "forbes.com",
"values": [6.0, 5.8, 6.3]
}
]
},
"top_domains": [
{
"source_id": "s1t2u3v4-...",
"domain": "techcrunch.com",
"category": 1,
"reference_count": 127
},
{
"source_id": "w5x6y7z8-...",
"domain": "forbes.com",
"category": 1,
"reference_count": 89
}
],
"opportunities": [
{
"domain": "reddit.com",
"citation_count": 45,
"category": 4,
"category_name": "ugc"
}
]
}
}
SourcesAnalyticsResponse fields
| Field | Type | Description |
|---|
stats | SourcesStats | Aggregate source and citation counts |
category_breakdown | CategoryBreakdown | Citation distribution by domain category (percentages) |
performance_chart | SourcePerformanceChart | Daily citation share for the top 10 domains |
top_domains | SourceDomainResponse[] | Top 20 domains by citation count |
opportunities | SourceOpportunity[] | High-citation domains where your brand is not mentioned |
SourcesStats fields
| Field | Type | Description |
|---|
total_sources | integer | Distinct source domains cited in the date range |
total_citations | integer | Total citation count across all sources |
CategoryBreakdown fields
Each field is a percentage (0—100) of total citations belonging to that category.
| Field | Category ID | Description |
|---|
corporate | 0 | Company and brand websites |
editorial | 1 | News outlets and media publications |
institutional | 2 | Government, academic, and non-profit sites |
reference | 3 | Encyclopedias, documentation, and knowledge bases |
ugc | 4 | User-generated content (forums, social media, Q&A) |
other | 5 | Uncategorized domains |
| Field | Type | Description |
|---|
dates | string[] | Sorted date strings in YYYY-MM-DD format |
series | DomainChartSeries[] | One entry per top-10 domain |
DomainChartSeries fields
| Field | Type | Description |
|---|
domain | string | Domain name |
values | float[] | Daily citation share as a percentage of all citations that day, aligned to dates |
SourceDomainResponse fields
| Field | Type | Description |
|---|
source_id | string (UUID) | Source ID |
domain | string | Domain name |
category | integer | Domain category ID (see CategoryBreakdown) |
reference_count | integer | Total citations in the date range |
SourceOpportunity fields
| Field | Type | Description |
|---|
domain | string | Domain name |
citation_count | integer | Total citations where your brand was not mentioned |
category | integer | Domain category ID |
category_name | string | Human-readable category name |
Opportunities are domains cited 3 or more times where your brand is either not mentioned or has mentioned = false. These represent sources you could target for brand placement to increase visibility.
Use cases
Category distribution
Performance trends
Identify opportunities
Use category_breakdown to understand which types of sources AI providers cite most. A high ugc percentage may indicate opportunities to improve presence on community platforms.
Plot performance_chart as a stacked area or line chart to see how the citation share of top domains shifts over time.
The opportunities array surfaces high-traffic sources where your brand is absent. Prioritize outreach to these domains to improve your visibility in AI responses.
