> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sources analytics

> Rich analytics for source domains: category breakdown, performance trends, and opportunities.

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 |

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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_..."
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.get(f"/projects/{project_id}/sources/analytics", params={"duration_days": 7})
    ```
  </Tab>

  <Tab title="Node.js (server-side)">
    ```javascript theme={null}
    const resp = await fetch(`${BASE}/projects/${projectId}/sources/analytics?duration_days=7`, { headers });
    ```
  </Tab>
</Tabs>

### Response

```json theme={null}
{
  "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 |

<Note>
  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.
</Note>

### Use cases

<Tabs>
  <Tab title="Category distribution">
    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.
  </Tab>

  <Tab title="Performance trends">
    Plot `performance_chart` as a stacked area or line chart to see how the citation share of top domains shifts over time.
  </Tab>

  <Tab title="Identify opportunities">
    The `opportunities` array surfaces high-traffic sources where your brand is absent. Prioritize outreach to these domains to improve your visibility in AI responses.
  </Tab>
</Tabs>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.