---
title: "List Segments"
method: GET
path: "/api/folders/documents/{document_id}/segments"
tags: ["domains"]
---

# List Segments

`GET /api/folders/documents/{document_id}/segments`

## Request

- Base URL: `https://app.thinqos.com` (the document declares no server; this is the origin it was published from)
- URL: `https://app.thinqos.com/api/folders/documents/{document_id}/segments`
- Auth: none declared

List a document's chunks, in document order.

Keyset-paginated over ``(segment_index, id)`` (TOS-3280): ``segment_index``
alone is this document's natural order but is not declared unique at the
ORM level, so ``id`` breaks ties to keep the ordering total. 400 on a
malformed cursor.

## Path parameters

- `document_id` string, uuid, required

## Query parameters

- `cursor` string, nullable
- `limit` integer, nullable

## Headers

- `x-impersonate-identity-id` string, nullable

## Response `200`

Successful Response

- SegmentListResponse: A keyset-paginated page of one document's chunks (TOS-3280). Ordered by ``segment_index`` - the document's own natural reading order, not upload/creation time - so a page boundary lands where the chunk viewer would expect it: "the next chunk after the one you were looking at", not "the next chunk indexed after it". ``next_cursor`` is ``None`` exactly when no later chunks remain.
  - `segments` SegmentResponse[], required
    - `id` string, uuid, required
    - `segment_index` integer, required
    - `content` string, required
    - `content_tokens` integer, required
    - `effective_date` string, nullable, required
  - `next_cursor` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/thinqos/apis/thinqos-api.md) · [All operations](https://skmtc.dev/thinqos/apis/thinqos-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thinqos/apis/thinqos-api/revisions/5387b4ded614?raw)