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