Overview

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

cURL
Python
Node.js (server-side)

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_..."

resp = client.get(f"/projects/{project_id}/overview", params={"duration_days": 7, "prompt_type": "active"})

const resp = await fetch(`${BASE}/projects/${projectId}/overview?duration_days=7&prompt_type=active`, { headers });

Response

{
  "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

Getting started

Authorized AI agent setup

Endpoints

Get overview

Path parameters

Query parameters

Response

OverviewPromptItem fields

OverviewCompetitorMention fields

Errors

​Get overview

​Path parameters

​Query parameters

​Response

​OverviewPromptItem fields

​OverviewCompetitorMention fields

​Errors

Get overview

Path parameters

Query parameters

Response

OverviewPromptItem fields

OverviewCompetitorMention fields

Errors