> ## 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="JavaScript">
    ```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>