Sources analytics

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

Returns source statistics, category distribution, a performance chart for the top 10 domains, the top 20 domains by citation count, and opportunity domains.

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
Python
Node.js (server-side)

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

SourcePerformanceChart fields

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.

Getting started

Authorized AI agent setup

Endpoints

Get sources analytics

Path parameters

Query parameters

Response

SourcesAnalyticsResponse fields

SourcesStats fields

CategoryBreakdown fields

SourcePerformanceChart fields

DomainChartSeries fields

SourceDomainResponse fields

SourceOpportunity fields

Use cases

​Get sources analytics

​Path parameters

​Query parameters

​Response

​SourcesAnalyticsResponse fields

​SourcesStats fields

​CategoryBreakdown fields

​SourcePerformanceChart fields

​DomainChartSeries fields

​SourceDomainResponse fields

​SourceOpportunity fields

​Use cases

Get sources analytics

Path parameters

Query parameters

Response

SourcesAnalyticsResponse fields

SourcesStats fields

CategoryBreakdown fields

SourcePerformanceChart fields

DomainChartSeries fields

SourceDomainResponse fields

SourceOpportunity fields

Use cases