Skip to main content

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.

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 /projects/{project_id}/visibility
Returns daily visibility, sentiment, and position values for each active competitor, averaged across selected providers.

​
Path parameters

ParamTypeDescription
project_idstring (UUID)The project ID

​
Query parameters

ParamTypeDefaultDescription
duration_daysinteger7Days to look back
date_fromstring—Start date (YYYY-MM-DD)
date_tostring—End date (YYYY-MM-DD)
providersstring—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_..."

​
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

FieldTypeDescription
datesstring[]Sorted date strings in YYYY-MM-DD format
periodstringHuman-readable date range (e.g., 2026-02-28 to 2026-03-03)
seriesCompetitorSeries[]One entry per active competitor

​
CompetitorSeries fields

FieldTypeNullableDescription
competitor_idstring (UUID)NoCompetitor ID
namestringNoCompetitor brand name
websitestringNoCompetitor website URL
icon_urlstringYesPrimary logo URL
is_own_brandbooleanNotrue if this is your own brand
visibilityfloat[]NoDaily visibility scores aligned to dates. null for days with no data
sentimentfloat[]NoDaily sentiment scores aligned to dates. null for days with no data
positionfloat[]NoDaily 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

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.