> ## 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.

# Overview

> Get aggregated prompt-level analysis with competitor mentions.

The overview endpoint returns a per-prompt summary of your project's GEO performance -- visibility, sentiment, position, and which competitors appear alongside your brand. Use this to build dashboards or leaderboard views.

## Get overview

```
GET /projects/{project_id}/overview
```

Returns aggregated metrics for all prompts in a project, with competitor mention counts per prompt.

### 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`)           |
| `prompt_type`   | string  | `active` | Filter by `active` or `suggested` |
| `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}/overview?duration_days=7&prompt_type=active" \
      -H "X-API-Key: tk_live_..."
    ```
  </Tab>

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

  <Tab title="JavaScript">
    ```javascript theme={null}
    const resp = await fetch(`${BASE}/projects/${projectId}/overview?duration_days=7&prompt_type=active`, { headers });
    ```
  </Tab>
</Tabs>

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "items": [
      {
        "prompt_id": "e5f6a7b8-...",
        "content": "What is the best project management tool?",
        "prompt_type": "active",
        "created_at": "2026-01-15T10:30:00+00:00",
        "topic_id": "t1u2v3w4-...",
        "topic_name": "Product comparisons",
        "visibility": 85.0,
        "sentiment": 72.0,
        "position": 2.3,
        "volume": 2400,
        "intent": "commercial",
        "cvr": 45.0,
        "competitors_mentioned": [
          {
            "competitor_id": "c1d2e3f4-...",
            "name": "Competitor A",
            "mention_count": 15,
            "icon_url": "https://logo.clearbit.com/competitor-a.com",
            "icon_urls": [
              "https://logo.clearbit.com/competitor-a.com",
              "https://www.google.com/s2/favicons?domain=competitor-a.com&sz=64"
            ]
          }
        ]
      }
    ]
  }
}
```

### OverviewPromptItem fields

| Field                   | Type                         | Nullable | Description                                                        |
| ----------------------- | ---------------------------- | -------- | ------------------------------------------------------------------ |
| `prompt_id`             | string (UUID)                | No       | Prompt ID                                                          |
| `content`               | string                       | No       | The AI search query text                                           |
| `prompt_type`           | string                       | No       | `active`, `pending`, `suggested`, `inactive`, or `url_recommended` |
| `created_at`            | string (ISO 8601)            | No       | Prompt creation timestamp                                          |
| `topic_id`              | string (UUID)                | Yes      | Topic this prompt belongs to                                       |
| `topic_name`            | string                       | Yes      | Topic display name                                                 |
| `visibility`            | float                        | No       | Brand visibility percentage (0--100) for the date range            |
| `sentiment`             | float                        | No       | Average brand sentiment score for the date range                   |
| `position`              | float                        | No       | Average brand position in responses                                |
| `volume`                | integer                      | Yes      | Estimated AI search demand for this prompt                         |
| `intent`                | string                       | Yes      | `informational`, `commercial`, `navigational`, or `transactional`  |
| `cvr`                   | float                        | Yes      | Content visibility rate (percentage)                               |
| `competitors_mentioned` | OverviewCompetitorMention\[] | No       | Competitors that appeared in responses to this prompt              |

### OverviewCompetitorMention fields

| Field           | Type          | Nullable | Description                                     |
| --------------- | ------------- | -------- | ----------------------------------------------- |
| `competitor_id` | string (UUID) | No       | Competitor ID                                   |
| `name`          | string        | No       | Competitor brand name as it appeared            |
| `mention_count` | integer       | No       | Total mentions across responses for this prompt |
| `icon_url`      | string        | Yes      | Primary logo URL                                |
| `icon_urls`     | string\[]     | No       | Multiple logo URL sources                       |

### Errors

| Status | Detail                                        | Cause                                 |
| ------ | --------------------------------------------- | ------------------------------------- |
| `400`  | `prompt_type must be 'active' or 'suggested'` | Invalid `prompt_type` query parameter |