Citations

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

Fetch successful model responses and the sources cited across a project or location.

The default window is seven days and the maximum window is three months. Only successful model responses are returned. Project and location identifiers may be supplied as Ceyo UUIDs or partner external IDs. The API key requires the visibility:read capability.

GET

List prompt citations

/projects/{project_id}/prompts/{prompt_id}/citations

Aggregates every citation attached to responses for one prompt in the selected project. Repeated citations are combined and counted across the requested date range.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required

prompt_iduuid

Prompt 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. For example: chatgpt,claude,perplexity.

OptionalDefault: All enabled models

pageinteger

The 1-based page number.

OptionalDefault: 1

per_pageinteger

Number of records per page. Maximum: 50.

OptionalDefault: 15

Response

Response envelope

project_id:uuidprompt_id:uuidstart:dateend:datemodels:string[]rows:Citation[]pagination:Pagination

project_iduuid

Resolved Ceyo project identifier.

prompt_iduuid

Prompt represented by the response.

startdate

Resolved start date.

enddate

Resolved end date.

modelsstring[]

Model keys included in the response.

rowsCitation[]

Paginated citation pages.

paginationPagination

Pagination metadata.

Object

Citation

domainstring

Normalized citation hostname.

pagestring

Normalized page value used for grouping and display.

urlstring

Canonical citation URL.

titlestring | null

Stored page title when supplied by the response provider.

frequencyinteger

Citation occurrences across the selected responses.

model_keysstring[]

Models that cited the page at least once.

model_frequenciesRecord<string, integer>

Citation frequency keyed by model.

Object

Pagination

pageinteger

Current 1-based page number.

per_pageinteger

Requested number of records per page.

totalinteger

Total records matching the request.

total_pagesinteger

Total available pages.

Request and response

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

{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "prompt_id": "4de5e484-ce6a-4e45-ad7c-bd48db2549af",
  "start": "2026-07-24",
  "end": "2026-07-30",
  "models": ["chatgpt", "perplexity"],
  "rows": [
    {
      "domain": "example.com",
      "page": "example.com/ai-visibility",
      "url": "https://example.com/ai-visibility",
      "title": "A guide to AI visibility",
      "frequency": 6,
      "model_keys": ["chatgpt", "perplexity"],
      "model_frequencies": {
        "chatgpt": 4,
        "perplexity": 2
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 15,
    "total": 8,
    "total_pages": 1
  }
}

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": "invalid_date_range",
    "message": "The requested date range is invalid.",
    "details": null,
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}

Errors

Status codes

400invalid_date_range | range_too_large | invalid_filter

The requested filters or date range are invalid.

401invalid_api_key

Authorization is absent or invalid.

403forbidden

The API key cannot access this resource.

404not_found

The project, location, or prompt was not found.

422visibility_unavailable

Visibility is unavailable for the selected scope.

429rate_limit_exceeded

Too many requests were made.

GET

List project citations

/projects/{project_id}/citations

Returns citation frequency across every matching prompt response in the selected project. Results can be grouped by individual page or by domain.

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. For example: chatgpt,claude,perplexity.

OptionalDefault: All enabled models

topic_idsstring

Comma-separated topic UUIDs.

Optional

grouppage | domain

Return page rows or domain groups containing their top pages.

OptionalDefault: page

qstring

Search citation domains, URLs, and titles.

Optional

domainstring

Restrict results to one normalized domain.

Optional

exclude_competitorsboolean

Exclude tracked competitor domains and subdomains.

OptionalDefault: true

pageinteger

The 1-based page number.

OptionalDefault: 1

per_pageinteger

Number of records per page. Maximum: 100.

OptionalDefault: 25

Response

Response envelope

project_id:uuidstart:dateend:datemodels:string[]group:page | domainrows:Citation[]groups:CitationDomainGroup[]pagination:Pagination

project_iduuid

Resolved Ceyo project identifier.

startdate

Resolved start date.

enddate

Resolved end date.

modelsstring[]

Model keys included in the response.

grouppage | domain

Resolved grouping mode.

rowsCitation[]

Page citations when group is page; otherwise empty.

groupsCitationDomainGroup[]

Domain groups when group is domain; otherwise empty.

paginationPagination

Pagination metadata for the selected grouping.

Object

Citation

domainstring

Normalized citation hostname.

pagestring

Normalized page value used for grouping and display.

urlstring

Canonical citation URL.

titlestring | null

Stored page title when supplied by the response provider.

frequencyinteger

Citation occurrences across the selected responses.

model_keysstring[]

Models that cited the page at least once.

model_frequenciesRecord<string, integer>

Citation frequency keyed by model.

Object

CitationDomainGroup

domainstring

Normalized citation hostname.

frequencyinteger

Citation occurrences across every page in the domain.

model_keysstring[]

Models that cited the domain.

model_frequenciesRecord<string, integer>

Domain citation frequency keyed by model.

pagesCitation[]

Highest-frequency pages within the domain.

Object

Pagination

pageinteger

Current 1-based page number.

per_pageinteger

Requested number of records per page.

totalinteger

Total records matching the request.

total_pagesinteger

Total available pages.

GroupingWhen group=page, results are returned in rows. When group=domain, rows is empty and domain results are returned in groups.

Request and response

curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/citations?start=2026-07-01&end=2026-07-30&group=domain' \
  --header 'Authorization: Bearer ceyo_platform_...'

{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "start": "2026-07-01",
  "end": "2026-07-30",
  "models": ["chatgpt", "perplexity"],
  "group": "domain",
  "rows": [],
  "groups": [
    {
      "domain": "example.com",
      "frequency": 19,
      "model_keys": ["chatgpt", "perplexity"],
      "model_frequencies": {
        "chatgpt": 12,
        "perplexity": 7
      },
      "pages": [
        {
          "domain": "example.com",
          "page": "example.com/ai-visibility",
          "url": "https://example.com/ai-visibility",
          "title": "A guide to AI visibility",
          "frequency": 11,
          "model_keys": ["chatgpt", "perplexity"],
          "model_frequencies": {
            "chatgpt": 7,
            "perplexity": 4
          }
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 12,
    "total_pages": 1
  }
}

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": "invalid_date_range",
    "message": "The requested date range is invalid.",
    "details": null,
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}

Errors

Status codes

400invalid_date_range | range_too_large | invalid_filter

The requested filters or date range are invalid.

401invalid_api_key

Authorization is absent or invalid.

403forbidden

The API key cannot access this resource.

404not_found

The project, location, or prompt was not found.

422visibility_unavailable

Visibility is unavailable for the selected scope.

429rate_limit_exceeded

Too many requests were made.

GET

Get citation trends

/projects/{project_id}/citations/timeseries

Returns daily citation totals for the selected project, including a count for each requested model. Dates with no citations are returned with zero values.

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. For example: chatgpt,claude,perplexity.

OptionalDefault: All enabled models

topic_idsstring

Comma-separated topic UUIDs.

Optional

exclude_competitorsboolean

Exclude tracked competitor domains and subdomains.

OptionalDefault: true

groupdomain | page

Control whether top citations represent domains or pages.

OptionalDefault: domain

Response

Response envelope

project_id:uuidstart:dateend:datemodels:string[]points:CitationTimeseriesPoint[]

project_iduuid

Resolved Ceyo project identifier.

startdate

Resolved start date.

enddate

Resolved end date.

modelsstring[]

Model keys included in the response.

pointsCitationTimeseriesPoint[]

One zero-filled point for each date in the range.

Object

CitationTimeseriesPoint

datedate

Calendar date represented by the point.

totalsRecord<string, integer>

Citation count keyed by model.

totalinteger

Total citations across the selected models.

top_citationsTopCitation[]

Up to five highest-frequency domains or pages.

Object

TopCitation

domainstring

Normalized citation hostname.

urlstring | null

Citation URL when grouping by page.

titlestring | null

Stored page title when grouping by page.

frequencyinteger

Citation occurrences for this date.

Request and response

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

{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "start": "2026-07-24",
  "end": "2026-07-30",
  "models": ["chatgpt", "perplexity"],
  "points": [
    {
      "date": "2026-07-30",
      "totals": {
        "chatgpt": 12,
        "perplexity": 8
      },
      "total": 20,
      "top_citations": [
        {
          "domain": "example.com",
          "url": "https://example.com/ai-visibility",
          "title": "A guide to AI visibility",
          "frequency": 7
        }
      ]
    }
  ]
}

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": "invalid_date_range",
    "message": "The requested date range is invalid.",
    "details": null,
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}

Errors

Status codes

400invalid_date_range | range_too_large | invalid_filter

The requested filters or date range are invalid.

401invalid_api_key

Authorization is absent or invalid.

403forbidden

The API key cannot access this resource.

404not_found

The project, location, or prompt was not found.

422visibility_unavailable

Visibility is unavailable for the selected scope.

429rate_limit_exceeded

Too many requests were made.