> ## Documentation Index
> Fetch the complete documentation index at: https://docs.feedal.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> API endpoints for listing sessions, reading session detail, and the public respondent API for starting sessions and submitting answers.

A **session** represents one respondent's traversal through a form. Sessions are created when a respondent starts a form and completed when they reach an End screen.

***

## List sessions (authenticated)

```
GET /api/v2/form/{slug}/responses/
```

Returns paginated sessions for a form.

**Query parameters**

| Parameter         | Description                                          |
| ----------------- | ---------------------------------------------------- |
| `status`          | Filter by `completed`, `in_progress`, or `abandoned` |
| `version`         | Filter by published version number                   |
| `started_at_from` | ISO date — sessions started on or after this date    |
| `started_at_to`   | ISO date — sessions started on or before this date   |
| `page`            | Page number                                          |

**Response**

```json theme={null}
{
  "count": 142,
  "next": "...",
  "previous": null,
  "results": [
    {
      "id": "uuid",
      "status": "completed",
      "version_number": 3,
      "total_score": 42,
      "answers_count": 5,
      "duration_seconds": 204,
      "started_at": "2026-03-17T09:00:00Z",
      "completed_at": "2026-03-17T09:03:24Z"
    }
  ]
}
```

***

## Get session detail (authenticated)

```
GET /api/v2/form/{slug}/responses/{session_id}/
```

Returns the full session including all answers and the traversal path.

**Response**

```json theme={null}
{
  "id": "uuid",
  "status": "completed",
  "version_number": 3,
  "total_score": 42,
  "score_breakdown": {
    "node_q1": 10,
    "node_q2": 32
  },
  "traversal_path": ["node_welcome", "node_q1", "node_q2", "node_end"],
  "answers": [
    {
      "id": "uuid",
      "node_id": "node_q1",
      "question_type": "short_text",
      "answer": "Jane Smith",
      "score_awarded": 10,
      "time_spent_seconds": 12,
      "shown_at": "2026-03-17T09:00:05Z",
      "answered_at": "2026-03-17T09:00:17Z"
    },
    {
      "id": "uuid",
      "node_id": "node_q2",
      "question_type": "opinion_scale",
      "answer": 9,
      "score_awarded": 32,
      "time_spent_seconds": 8,
      "shown_at": "2026-03-17T09:00:18Z",
      "answered_at": "2026-03-17T09:00:26Z"
    }
  ],
  "started_at": "2026-03-17T09:00:00Z",
  "completed_at": "2026-03-17T09:03:24Z",
  "duration_seconds": 204
}
```

***

## Export sessions as CSV (authenticated)

```
GET /api/v2/form/{slug}/responses/export/
```

Streams a CSV file. Supports the same query parameters as the list endpoint. Returns `Content-Type: text/csv` and a `Content-Disposition: attachment` header.

***

## Public respondent API

These endpoints are open — no authentication required. They are used by the form renderer to run a live session.

### Get a published form

```
GET /api/v2/r/{slug}/
```

Returns the current published form graph and theme snapshot. Used to initialise the form renderer.

**Response**

```json theme={null}
{
  "form": {
    "id": "uuid",
    "slug": "a1b2c3d4e5f6",
    "title": "Customer feedback"
  },
  "graph": { "schema_version": "2.0", "nodes": [...], "edges": [...], ... },
  "theme": { ... },
  "version_number": 3
}
```

### Start a session

```
POST /api/v2/r/{slug}/start/
```

Creates a new session and returns the first node to display.

**Response**

```json theme={null}
{
  "id": "uuid",
  "current_node_id": "node_welcome",
  "traversal_path": ["node_welcome"],
  "status": "in_progress",
  "started_at": "2026-03-17T10:00:00Z"
}
```

### Submit an answer

```
POST /api/v2/r/session/{session_id}/next/
```

Submits an answer for the current node and returns the next node to display.

**Request body**

```json theme={null}
{
  "node_id": "node_q1",
  "value": "Jane Smith"
}
```

**Response**

```json theme={null}
{
  "next_node_id": "node_q2",
  "is_complete": false,
  "traversal_path": ["node_welcome", "node_q1", "node_q2"]
}
```

When `is_complete` is `true`, the session has reached an End node. Call `complete/` to finalise it.

### Complete a session

```
POST /api/v2/r/session/{session_id}/complete/
```

Marks the session as completed and triggers any connected integrations. Returns `200 OK`.

***

## Next steps

<CardGroup cols={2}>
  <Card title="Responses" icon="message-square" href="/developer/api-reference/responses">
    Individual node-level answer endpoints.
  </Card>

  <Card title="Integrations" icon="plug" href="/developer/api-reference/integrations">
    Manage form integrations via API.
  </Card>
</CardGroup>