# Surveys

> Read customer satisfaction (CSAT) survey results and stats.

Source: https://tickos.dev/docs/surveys

Surveys capture customer satisfaction after a ticket is resolved. TickOS sends a short survey (star rating + optional questions and comment) and records the response. The API is read-only: surveys are configured and sent from the dashboard, and you query their results here.

## GET /v1/surveys -- List survey responses

Permission: read. Returns surveys newest first (by created_at), with their rating and the linked customer and ticket. Supports standard pagination (limit, offset). The list is returned under the surveys key, not data. An invalid status or a rating outside 1-5 returns 400.

| Query param | Type | Description |
|---|---|---|
| inbox_id | string | Filter by inbox. |
| status | string | pending, sending, sent, responded, expired or cancelled. |
| rating | number | Filter by star rating (1-5). |
| customer_id | string | Filter by customer. |
| ticket_id | string | Filter by ticket. |
| from | string | ISO 8601 lower bound (created_at). |
| to | string | ISO 8601 upper bound (created_at). |
| limit | number | Page size (max 100, default 50). |
| offset | number | Pagination offset. |

```json
{
  "surveys": [
    {
      "id": "srv_xxxxxxxx",
      "ticket_id": "tck-xxxxxxxx",
      "customer_id": "cst-xxxxxxxx",
      "inbox_id": "inb_xxxxxxxx",
      "status": "responded",
      "rating": 5,
      "answered_question": true,
      "communication_clear": true,
      "comment": "Fast and helpful, thanks!",
      "scheduled_at": "2026-07-10T12:00:00Z",
      "sent_at": "2026-07-10T12:01:00Z",
      "responded_at": "2026-07-10T13:20:00Z",
      "created_at": "2026-07-10T11:59:00Z",
      "customer": { "id": "cst-xxxxxxxx", "name": "Jane Doe", "email": "jane@example.com" },
      "ticket": { "id": "tck-xxxxxxxx", "client_id": "SUP-00042", "subject": "Cannot access my account" }
    }
  ],
  "pagination": { "total": 128, "limit": 50, "offset": 0 }
}
```

## GET /v1/surveys/stats -- Survey statistics

Permission: read. Returns aggregated CSAT metrics in the response root (no data wrapper). Optionally filter with inbox_id, from and to (ISO 8601 bounds on created_at). Rates are percentages from 0 to 100 rounded to 2 decimals, and are null when there is nothing to compute them from.

| Field | Type | Description |
|---|---|---|
| total_sent | number | Surveys that were delivered: status sent, responded or expired. |
| total_responded | number | Surveys with status responded. |
| response_rate | number \| null | total_responded / total_sent as a percentage (0-100, 2 decimals). null when total_sent is 0. |
| average_rating | number \| null | Mean star rating across responded surveys (1-5, 2 decimals). null when there are no ratings. |
| rating_distribution | object | Count of responses per star: { "1": n, ..., "5": n }. |
| answered_question_yes_rate | number \| null | Percentage (0-100) of "yes" among responded surveys that answered this question. null when none answered it. |
| communication_clear_yes_rate | number \| null | Percentage (0-100) of "yes" among responded surveys that answered this question. null when none answered it. |
| by_status | object | Counts per status: pending, sending, sent, responded, expired, cancelled. |

```json
{
  "total_sent": 120,
  "total_responded": 48,
  "response_rate": 40,
  "average_rating": 4.38,
  "rating_distribution": { "1": 1, "2": 2, "3": 4, "4": 10, "5": 31 },
  "answered_question_yes_rate": 91.67,
  "communication_clear_yes_rate": 95.83,
  "by_status": { "pending": 3, "sending": 0, "sent": 60, "responded": 48, "expired": 12, "cancelled": 2 }
}
```

```bash
curl "https://api.tickos.dev/v1/surveys/stats?inbox_id=inb_xxx&from=2026-07-01" \
  -H 'Authorization: Bearer sk_your_api_key'
```