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

Responses

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

ProjectLocation
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
/projects/{project_id}/prompts/{prompt_id}/responses

Returns one row per successful model response for a prompt in the selected project. Responses are ordered by run date and completion time, newest first.

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:Response[]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.

rowsResponse[]

Paginated model responses.

paginationPagination

Pagination metadata.

Object

Response

run_ondate

Calendar date assigned to the visibility run.

model_keystring

Model that generated the response.

statusstring

Response status. Returned rows have succeeded.

response_textstring | null

Full stored response text.

brand_presentboolean

Whether the primary tracked brand was mentioned.

positioninteger | null

1-based brand position when a ranked list was detected.

sentimentSentiment

Sentiment status, score, and label for the primary brand.

entitiesEntityResult[]

Mention and position results for the brand and competitors.

citations_countinteger

Total citations attached to the response.

citationsCitationPreview[]

Preview of up to three citations. Use citations endpoints for all.

finished_atdatetime | null

Time response processing completed.

Object

Sentiment

statusstring

not_requested, pending, running, succeeded, failed, or skipped.

scorenumber | null

Sentiment score from 0 to 10.

labelstring | null

negative, neutral, or positive.

Object

EntityResult

tracked_entity_iduuid

Tracked brand or competitor identifier.

namestring

Entity name captured when the response was processed.

kindprimary | competitor

Relationship of the entity to the scope.

mentionedboolean

Whether the entity appeared in the response.

positioninteger | null

1-based entity position when a ranked list was detected.

Object

CitationPreview

domainstring

Normalized citation hostname.

urlstring

Citation URL.

positioninteger

1-based citation order in the model response.

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.

Citation previewThe citations array contains at most three entries. Use the prompt citations endpoint to retrieve the complete set.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/prompts/{prompt_id}/responses?start=2026-07-24&end=2026-07-30&models=chatgpt,perplexity' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "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": [
    {
      "run_on": "2026-07-30",
      "model_key": "chatgpt",
      "status": "succeeded",
      "response_text": "Ceyo is an AI visibility platform...",
      "brand_present": true,
      "position": 2,
      "sentiment": {
        "status": "succeeded",
        "score": 8.2,
        "label": "positive"
      },
      "entities": [
        {
          "tracked_entity_id": "f3385d92-8f24-49f2-9819-18412e93427f",
          "name": "Ceyo",
          "kind": "primary",
          "mentioned": true,
          "position": 2
        }
      ],
      "citations_count": 2,
      "citations": [
        {
          "domain": "example.com",
          "url": "https://example.com/ai-visibility",
          "position": 1
        }
      ],
      "finished_at": "2026-07-30T09:42:16Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 15,
    "total": 14,
    "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.

Example error responseJSON
{
  "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.