# Responses

Source: https://ceyo.ai/docs/signal/responses

### Responses

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

**Scope:** Project

### List prompt responses

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

#### Path parameters

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `project_id` | project UUID \| project external ID | Required | Project identifier. |
| `prompt_id` | uuid | Required | Prompt identifier. |

#### Query parameters

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `start` | date | Optional; Default: 6 days before end | First run date to include, in YYYY-MM-DD format. |
| `end` | date | Optional; Default: Today | Last run date to include, in YYYY-MM-DD format. |
| `models` | string | Optional; Default: All enabled models | Comma-separated or repeated model keys. For example: chatgpt,claude,perplexity. |
| `page` | integer | Optional; Default: 1 | The 1-based page number. |
| `per_page` | integer | Optional; Default: 15 | Number of records per page. Maximum: 50. |

#### Response envelope

`project_id`:**uuid**`prompt_id`:**uuid**`start`:**date**`end`:**date**`models`:**string\[\]**`rows`:**Response\[\]**`pagination`:**Pagination**

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `project_id` | uuid |  | Resolved Ceyo project identifier. |
| `prompt_id` | uuid |  | Prompt represented by the response. |
| `start` | date |  | Resolved start date. |
| `end` | date |  | Resolved end date. |
| `models` | string\[\] |  | Model keys included in the response. |
| `rows` | Response\[\] |  | Paginated model responses. |
| `pagination` | Pagination |  | Pagination metadata. |

#### Response

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `run_on` | date |  | Calendar date assigned to the visibility run. |
| `model_key` | string |  | Model that generated the response. |
| `status` | string |  | Response status. Returned rows have succeeded. |
| `response_text` | string \| null |  | Full stored response text. |
| `brand_present` | boolean |  | Whether the primary tracked brand was mentioned. |
| `position` | integer \| null |  | 1-based brand position when a ranked list was detected. |
| `sentiment` | Sentiment |  | Sentiment status, score, and label for the primary brand. |
| `entities` | EntityResult\[\] |  | Mention and position results for the brand and competitors. |
| `citations_count` | integer |  | Total citations attached to the response. |
| `citations` | CitationPreview\[\] |  | Preview of up to three citations. Use citations endpoints for all. |
| `finished_at` | datetime \| null |  | Time response processing completed. |

#### Sentiment

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `status` | string |  | not\_requested, pending, running, succeeded, failed, or skipped. |
| `score` | number \| null |  | Sentiment score from 0 to 10. |
| `label` | string \| null |  | negative, neutral, or positive. |

#### EntityResult

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `tracked_entity_id` | uuid |  | Tracked brand or competitor identifier. |
| `name` | string |  | Entity name captured when the response was processed. |
| `kind` | primary \| competitor |  | Relationship of the entity to the scope. |
| `mentioned` | boolean |  | Whether the entity appeared in the response. |
| `position` | integer \| null |  | 1-based entity position when a ranked list was detected. |

#### CitationPreview

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `domain` | string |  | Normalized citation hostname. |
| `url` | string |  | Citation URL. |
| `position` | integer |  | 1-based citation order in the model response. |

#### Pagination

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `page` | integer |  | Current 1-based page number. |
| `per_page` | integer |  | Requested number of records per page. |
| `total` | integer |  | Total records matching the request. |
| `total_pages` | integer |  | Total available pages. |

> **Citation preview**
>
> The `citations` array contains at most three entries. Use the prompt citations endpoint to retrieve the complete set.

#### Request and response

```curl
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_...'
```

```json
{
  "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
  }
}
```

#### Errors

#### Error response envelope

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `error` | Error |  | Structured error payload. |

#### Error

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `code` | string |  | Stable snake\_case code suitable for programmatic handling. |
| `message` | string |  | Human-readable explanation of the failure. |
| `details` | object \| array \| null |  | Structured validation or request context when available. |
| `request_id` | string |  | Identifier to provide when requesting support. |

```json
{
  "error": {
    "code": "invalid_date_range",
    "message": "The requested date range is invalid.",
    "details": null,
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
```

#### Status codes

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `400` | invalid\_date\_range \| range\_too\_large \| invalid\_filter |  | The requested filters or date range are invalid. |
| `401` | invalid\_api\_key |  | Authorization is absent or invalid. |
| `403` | forbidden |  | The API key cannot access this resource. |
| `404` | not\_found |  | The project, location, or prompt was not found. |
| `422` | visibility\_unavailable |  | Visibility is unavailable for the selected scope. |
| `429` | rate\_limit\_exceeded |  | Too many requests were made. |