Visibility analytics | Signal API Documentation

Visibility analytics as MarkdownUse a clean Markdown version of this page with an agent or local tooling.

Visibility

Measure brand visibility, compare competitors, and track performance trends across AI models for a project or location.

Choose Project or Location above to set the analytics scope. Date ranges default to seven days and can span up to three months. Path identifiers accept either Ceyo UUIDs or partner external IDs.

Percentage metricsVisibility, coverage, and share of voice are percentages from 0 to 100. Competitor timeseries are keyed by tracked entity, with selected model keys returned separately in models.

GET

Get visibility overview

/projects/{project_id}/visibility/summary

Returns aggregate visibility and citation metrics for matching responses in the selected project.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required

Parameters

Query parameters

startdate

First run date to include, in YYYY-MM-DD format.

OptionalDefault: 6 days before end

enddate

Last run date to include, in YYYY-MM-DD format.

OptionalDefault: Today

modelsstring

Comma-separated or repeated model keys, such as chatgpt,claude,perplexity.

OptionalDefault: All model keys present in matching responses

topic_idsstring

Comma-separated or repeated topic UUIDs.

Optional

topic_iduuid

Alias for topic_ids when filtering by one topic UUID.

Optional

prompt_iduuid

Restrict results to one prompt in the selected scope.

Optional

Response

Response envelope

start:dateend:datemodels:string[]summary:object

startdate

Resolved start date.

enddate

Resolved end date.

modelsstring[]

Model keys included in the calculation. When omitted from the request, this contains every model key present in matching responses.

summaryobject

Aggregate visibility metrics.

Object

Summary object

primary_mentionsinteger

Responses in which the primary tracked entity was mentioned.

visibility_percentagenumber

Share of responses that mentioned the primary tracked entity, rounded to two decimals.

average_positionnumber | null

Average 1-based position for primary-entity mentions with a detected position.

citationsinteger

Total citation occurrences across matching responses.

Metric definitionsvisibility_percentage is the share of matching responses that mention the primary entity. average_position uses only primary mentions with a detected position, and citations counts citation occurrences.

Request and response

curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/visibility/summary?start=2026-07-24&end=2026-07-30&models=chatgpt,perplexity' \
  --header 'Authorization: Bearer ceyo_platform_...'

{
  "start": "2026-07-24",
  "end": "2026-07-30",
  "models": ["chatgpt", "perplexity"],
  "summary": {
    "primary_mentions": 17,
    "visibility_percentage": 42.5,
    "average_position": 2.82,
    "citations": 31
  }
}

ErrorsResponse format and status codes

Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}

Errors

Status codes

400invalid_date_range | range_too_large

A date is invalid or the requested window exceeds three months.

401invalid_api_key

The Bearer API key is missing or invalid.

403forbidden

The API key is valid but is not allowed to access this resource.

404not_found

The project, location, or visibility scope was not found.

422visibility_unavailable

Project-level visibility is unavailable for a locations-only container; use a location scope.

429rate_limit_exceeded

Too many requests were made.

GET

Compare competitors

/projects/{project_id}/visibility/competitors

Compares the primary entity plus tracked competitors for the selected project, ordered with primary first, then by share_of_voice descending and name.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required

Parameters

Query parameters

startdate

First run date to include, in YYYY-MM-DD format.

OptionalDefault: 6 days before end

enddate

Last run date to include, in YYYY-MM-DD format.

OptionalDefault: Today

modelsstring

Comma-separated or repeated model keys, such as chatgpt,claude,perplexity.

OptionalDefault: All model keys present in matching responses

topic_idsstring

Comma-separated or repeated topic UUIDs.

Optional

topic_iduuid

Alias for topic_ids when filtering by one topic UUID.

Optional

prompt_iduuid

Restrict results to one prompt in the selected scope.

Optional

Response

Response envelope

start:dateend:datemodels:string[]total_mentions:integerentities:object[]

startdate

Resolved start date.

enddate

Resolved end date.

modelsstring[]

Model keys included in the calculation. When omitted from the request, this contains every model key present in matching responses.

total_mentionsinteger

Mentions across all returned entities.

entitiesobject[]

The primary entity plus tracked competitors, ordered with primary first, then by share_of_voice descending and name.

Object

Entity

tracked_entity_iduuid

Tracked primary brand or competitor identifier.

kindprimary | competitor

Entity relationship to the selected scope.

namestring

Tracked entity name.

domainstring | null

Normalized entity domain when configured.

statusactive

Current tracked-entity status. Only active entities are returned.

mentionsinteger

Responses in which this entity was mentioned.

coverage_percentagenumber

Share of matching responses that mentioned the entity.

share_of_voicenumber

Entity mentions divided by mentions across all returned entities, multiplied by 100.

average_positionnumber | null

Average detected 1-based position when the entity was mentioned.

Metric definitionsCoverage uses all matching responses as its denominator. Share of voice uses mentions across the returned primary entity and tracked competitors. Results place the primary entity first, followed by competitors ordered by share_of_voice descending and then name. When there are no mentions, both percentages are 0.0 and average position is null.

Request and response

curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/visibility/competitors?start=2026-07-24&end=2026-07-30&topic_ids=ab20526b-6bb2-436c-8c93-5bf77ea43848' \
  --header 'Authorization: Bearer ceyo_platform_...'

{
  "start": "2026-07-24",
  "end": "2026-07-30",
  "models": ["chatgpt", "perplexity"],
  "total_mentions": 33,
  "entities": [
    {
      "tracked_entity_id": "f3385d92-8f24-49f2-9819-18412e93427f",
      "kind": "primary",
      "name": "Ceyo",
      "domain": "ceyo.ai",
      "status": "active",
      "mentions": 17,
      "coverage_percentage": 42.5,
      "share_of_voice": 51.52,
      "average_position": 2.82
    },
    {
      "tracked_entity_id": "2e230599-4918-49a7-bb08-b30711836aa8",
      "kind": "competitor",
      "name": "Example Competitor",
      "domain": "competitor.example",
      "status": "active",
      "mentions": 16,
      "coverage_percentage": 40.0,
      "share_of_voice": 48.48,
      "average_position": 3.13
    }
  ]
}

ErrorsResponse format and status codes

Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}

Errors

Status codes

400invalid_date_range | range_too_large

A date is invalid or the requested window exceeds three months.

401invalid_api_key

The Bearer API key is missing or invalid.

403forbidden

The API key is valid but is not allowed to access this resource.

404not_found

The project, location, or visibility scope was not found.

422visibility_unavailable

Project-level visibility is unavailable for a locations-only container; use a location scope.

429rate_limit_exceeded

Too many requests were made.

GET

Get competitor trends

/projects/{project_id}/visibility/competitors/timeseries

Returns dated coverage, mention, and position series for the primary entity and competitors in the selected project.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required

Parameters

Query parameters

startdate

First run date to include, in YYYY-MM-DD format.

OptionalDefault: 6 days before end

enddate

Last run date to include, in YYYY-MM-DD format.

OptionalDefault: Today

modelsstring

Comma-separated or repeated model keys, such as chatgpt,claude,perplexity.

OptionalDefault: All model keys present in matching responses

topic_idsstring

Comma-separated or repeated topic UUIDs.

Optional

topic_iduuid

Alias for topic_ids when filtering by one topic UUID.

Optional

prompt_iduuid

Restrict results to one prompt in the selected scope.

Optional

Response

Response envelope

start:dateend:datemodels:string[]entities:object[]points:object[]

startdate

Resolved start date.

enddate

Resolved end date.

modelsstring[]

Model keys included in the calculation. When omitted from the request, this contains every model key present in matching responses.

entitiesobject[]

Metadata for each keyed series.

pointsobject[]

One point for each date containing matching responses.

Object

Timeseries entity

keystring

Stable series key in the form entity:{tracked_entity_id}.

tracked_entity_iduuid

Tracked entity identifier.

kindprimary | competitor

Entity relationship to the selected scope.

namestring

Tracked entity name.

domainstring | null

Normalized entity domain when configured.

aliasesstring[]

Additional names recognized as mentions of this entity.

Object

Timeseries point

datedate

Visibility measurement date.

mentionsobject

Mention count keyed by entity series key.

average_positionsobject

Average 1-based position or null, keyed by entity series key.

Series keys and datesJoin each object in mentions and average_positions to entity metadata through key. Dates without matching responses are omitted; returned entity values are zero-filled for dates that have responses.

Request and response

curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/visibility/competitors/timeseries?start=2026-07-24&end=2026-07-30&models=chatgpt,perplexity' \
  --header 'Authorization: Bearer ceyo_platform_...'

{
  "start": "2026-07-24",
  "end": "2026-07-30",
  "models": ["chatgpt", "perplexity"],
  "entities": [
    {
      "key": "entity:f3385d92-8f24-49f2-9819-18412e93427f",
      "tracked_entity_id": "f3385d92-8f24-49f2-9819-18412e93427f",
      "kind": "primary",
      "name": "Ceyo",
      "domain": "ceyo.ai",
      "aliases": ["Ceyo AI"]
    }
  ],
  "points": [
    {
      "date": "2026-07-30",
      "mentions": {
        "entity:f3385d92-8f24-49f2-9819-18412e93427f": 4
      },
      "average_positions": {
        "entity:f3385d92-8f24-49f2-9819-18412e93427f": 2.5
      }
    }
  ]
}

ErrorsResponse format and status codes

Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}

Errors

Status codes

400invalid_date_range | range_too_large

A date is invalid or the requested window exceeds three months.

401invalid_api_key

The Bearer API key is missing or invalid.

403forbidden

The API key is valid but is not allowed to access this resource.

404not_found

The project, location, or visibility scope was not found.

422visibility_unavailable

Project-level visibility is unavailable for a locations-only container; use a location scope.

429rate_limit_exceeded

Too many requests were made.

GET

Get model visibility trends

/projects/{project_id}/visibility/model-trends

Returns daily and range-level primary-brand visibility by model, plus an aggregate across models, for the selected project.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required

Parameters

Query parameters

startdate

First run date to include, in YYYY-MM-DD format.

OptionalDefault: 6 days before end

enddate

Last run date to include, in YYYY-MM-DD format.

OptionalDefault: Today

modelsstring

Comma-separated or repeated model keys, such as chatgpt,claude,perplexity.

OptionalDefault: All model keys present in matching responses

topic_idsstring

Comma-separated or repeated topic UUIDs.

Optional

topic_iduuid

Alias for topic_ids when filtering by one topic UUID.

Optional

prompt_iduuid

Restrict results to one prompt in the selected scope.

Optional

Response

Response envelope

start:dateend:datemodels:string[]aggregate:objectmodel_summaries:object[]days:object[]

startdate

Resolved start date.

enddate

Resolved end date.

modelsstring[]

Model keys included in the calculation. When omitted from the request, this contains every model key present in matching responses.

aggregateobject

Primary-brand visibility across all returned models.

model_summariesobject[]

Range-level primary-brand visibility for each returned model, ordered by model key.

daysobject[]

Daily primary-brand visibility in ascending date order. Dates without matching responses are omitted.

Object

Aggregate object

mentionsinteger

Responses in which the primary tracked brand was mentioned across all returned models.

visibility_percentagenumber

Share of responses that mentioned the primary tracked brand, rounded to two decimals.

comparisonobject | null

Comparison with the immediately preceding window of the same length, or null when that window has no matching responses.

Object

Model summary object

modelstring

Stable model key.

mentionsinteger

Responses for this model in which the primary tracked brand was mentioned.

visibility_percentagenumber

Share of this model’s responses that mentioned the primary tracked brand, rounded to two decimals.

comparisonobject | null

Comparison with the same model in the immediately preceding window, or null when that model has no matching responses in the comparison window.

Object

Daily object

datedate

Visibility measurement date in YYYY-MM-DD format.

aggregateobject

Primary-brand visibility across all returned models for this date.

modelsobject[]

Primary-brand visibility for each returned model on this date, ordered by model key.

Object

Daily aggregate object

mentionsinteger

Responses across all returned models that mentioned the primary tracked brand on this date.

visibility_percentagenumber

Share of responses that mentioned the primary tracked brand on this date.

Object

Daily model object

modelstring

Stable model key.

mentionsinteger

Responses for this model that mentioned the primary tracked brand on this date.

visibility_percentagenumber

Share of this model’s responses that mentioned the primary tracked brand on this date.

Object

Comparison object

startdate

First date of the immediately preceding comparison window.

enddate

Last date of the immediately preceding comparison window.

mentionsinteger

Responses that mentioned the primary tracked brand in the comparison window.

visibility_percentagenumber

Primary-brand visibility in the comparison window, expressed as a percentage from 0 to 100.

delta_percentage_pointsnumber

Selected-window visibility_percentage minus comparison-window visibility_percentage, in percentage points.

Ranges, percentages, and comparisonsThe default range is seven days and the maximum range is three months. Every visibility_percentage is a value from 0 to 100 calculated as the share of responses that mention the primary brand. Range-level comparisons use the immediately preceding window of equal length. A positive delta_percentage_points means visibility increased. Dates without matching responses are omitted.

Request and response

curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/visibility/model-trends?start=2026-07-24&end=2026-07-30&models=chatgpt,perplexity' \
  --header 'Authorization: Bearer ceyo_platform_...'

{
  "start": "2026-07-24",
  "end": "2026-07-30",
  "models": ["chatgpt", "perplexity"],
  "aggregate": {
    "mentions": 17,
    "visibility_percentage": 42.5,
    "comparison": {
      "start": "2026-07-17",
      "end": "2026-07-23",
      "mentions": 14,
      "visibility_percentage": 36.84,
      "delta_percentage_points": 5.66
    }
  },
  "model_summaries": [
    {
      "model": "chatgpt",
      "mentions": 10,
      "visibility_percentage": 50.0,
      "comparison": {
        "start": "2026-07-17",
        "end": "2026-07-23",
        "mentions": 8,
        "visibility_percentage": 42.11,
        "delta_percentage_points": 7.89
      }
    },
    {
      "model": "perplexity",
      "mentions": 7,
      "visibility_percentage": 35.0,
      "comparison": {
        "start": "2026-07-17",
        "end": "2026-07-23",
        "mentions": 6,
        "visibility_percentage": 31.58,
        "delta_percentage_points": 3.42
      }
    }
  ],
  "days": [
    {
      "date": "2026-07-30",
      "aggregate": {
        "mentions": 4,
        "visibility_percentage": 50.0
      },
      "models": [
        {
          "model": "chatgpt",
          "mentions": 3,
          "visibility_percentage": 75.0
        },
        {
          "model": "perplexity",
          "mentions": 1,
          "visibility_percentage": 25.0
        }
      ]
    }
  ]
}

ErrorsResponse format and status codes

Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}

Errors

Status codes

400invalid_date_range | range_too_large

A date is invalid or the requested window exceeds three months.

401invalid_api_key

The Bearer API key is missing or invalid.

403forbidden

The API key is valid but is not allowed to access this resource.

404not_found

The project, location, or visibility scope was not found.

422visibility_unavailable

Project-level visibility is unavailable for a locations-only container; use a location scope.

429rate_limit_exceeded

Too many requests were made.