Visibility trends

The visibility trends endpoint returns daily time-series metrics for every active competitor in a project. Use it to chart how brand visibility, sentiment, and position change over time across AI providers.

Get visibility trends

GET /projects/{project_id}/visibility

Returns daily visibility, sentiment, and position values for each active competitor, averaged across selected providers.

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}/visibility?duration_days=7" \
  -H "X-API-Key: tk_live_..."

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

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

Response

{
  "success": true,
  "data": {
    "dates": ["2026-02-28", "2026-03-01", "2026-03-02", "2026-03-03"],
    "period": "2026-02-28 to 2026-03-03",
    "series": [
      {
        "competitor_id": "00000000-0000-0000-0000-000000000000",
        "name": "Acme Corp",
        "website": "https://acme.com",
        "icon_url": "https://logo.clearbit.com/acme.com",
        "is_own_brand": true,
        "visibility": [82.5, 85.0, 83.2, 86.1],
        "sentiment": [70.0, 72.0, 71.5, 73.0],
        "position": [1.8, 1.6, 1.9, 1.5]
      },
      {
        "competitor_id": "c1d2e3f4-...",
        "name": "Competitor A",
        "website": "https://competitor-a.com",
        "icon_url": "https://logo.clearbit.com/competitor-a.com",
        "is_own_brand": false,
        "visibility": [60.0, 62.5, null, 65.0],
        "sentiment": [55.0, 58.0, null, 60.0],
        "position": [3.2, 3.0, null, 2.8]
      }
    ]
  }
}

VisibilityTrendsResponse fields

Field	Type	Description
`dates`	string[]	Sorted date strings in `YYYY-MM-DD` format
`period`	string	Human-readable date range (e.g., `2026-02-28 to 2026-03-03`)
`series`	CompetitorSeries[]	One entry per active competitor

CompetitorSeries fields

Field	Type	Nullable	Description
`competitor_id`	string (UUID)	No	Competitor ID
`name`	string	No	Competitor brand name
`website`	string	No	Competitor website URL
`icon_url`	string	Yes	Primary logo URL
`is_own_brand`	boolean	No	`true` if this is your own brand
`visibility`	float[]	No	Daily visibility scores aligned to `dates`. `null` for days with no data
`sentiment`	float[]	No	Daily sentiment scores aligned to `dates`. `null` for days with no data
`position`	float[]	No	Daily position values aligned to `dates`. `null` for days with no data

When multiple providers have data for the same day, values are averaged. A null entry means no data was collected for that competitor on that date.

Use cases

Chart over time
Compare competitors
Filter by provider

Plot each competitor as a line on a time-series chart. The dates array provides x-axis labels and each series’ visibility, sentiment, and position arrays provide y-axis values.

Use is_own_brand to highlight your brand against competitors. Compare trends to see if your visibility is growing faster or slower than the competition.

Pass ?providers=chatgpt to isolate trends for a single AI provider and compare performance across platforms.

Getting started

Authorized AI agent setup

Endpoints

Get visibility trends

Path parameters

Query parameters

Response

VisibilityTrendsResponse fields

CompetitorSeries fields

Use cases

​Get visibility trends

​Path parameters

​Query parameters

​Response

​VisibilityTrendsResponse fields

​CompetitorSeries fields

​Use cases

Get visibility trends

Path parameters

Query parameters

Response

VisibilityTrendsResponse fields

CompetitorSeries fields

Use cases