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

# Reading comments

> Read the AI and human review comments on a promotion version, grouped into threads.

Comments are the feedback left on a promotion version, both Adclear AI findings and human review notes. Read them to bring compliance feedback into your own workflow without opening the Adclear interface. Comments are returned per version, grouped into threads.

## Get comments

<CodeGroup>
  ```bash curl theme={null}
  curl -s "$API_BASE/v1/promotions/$PROMOTION_ID/versions/$VERSION_ID/comments?limit=20&offset=0" \
    -H "Authorization: Bearer $ADCLEAR_API_KEY" \
    -H "X-External-User-ID: $USER_ID"
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(
    `${API_BASE}/v1/promotions/${promotionId}/versions/${versionId}/comments?limit=20&offset=0`,
    { headers },
  );
  const { threads, pagination } = await res.json();
  ```

  ```python Python theme={null}
  res = requests.get(
      f"{API_BASE}/v1/promotions/{promotion_id}/versions/{version_id}/comments",
      headers=headers,
      params={"limit": 20, "offset": 0},
  )
  threads = res.json()["threads"]
  ```
</CodeGroup>

**Response (200 OK):**

```json theme={null}
{
  "threads": [
    {
      "id": "thread-uuid-...",
      "createdAt": "2026-08-10T12:00:00.000Z",
      "comment": {
        "id": "comment-uuid-...",
        "author": { "type": "ai", "userId": "adclear-ai", "name": "Adclear AI" },
        "content": "This claim needs a risk disclaimer.",
        "createdAt": "2026-08-10T12:00:00.000Z",
        "editedAt": null
      },
      "replies": [
        {
          "id": "comment-uuid-2",
          "author": { "type": "reviewer", "userId": "user-...", "name": "Jane Doe" },
          "content": "Agreed, disclaimer added in the next version.",
          "createdAt": "2026-08-10T12:05:00.000Z",
          "editedAt": null
        }
      ]
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "totalThreads": 1, "hasMore": false },
  "correlationId": "corr-uuid-..."
}
```

Each thread has one top-level `comment` and its `replies` in chronological order. Threads are ordered oldest first. The `promotionId` and `versionId` in the path must belong to your workspace, or the request returns `404`.

## Query parameters

| Parameter | Default | Description                         |
| --------- | ------- | ----------------------------------- |
| `limit`   | `20`    | Maximum threads to return, 1 to 100 |
| `offset`  | `0`     | Number of threads to skip           |

Page through with `offset`. Keep requesting until `pagination.hasMore` is `false`.

## Comment fields

| Field       | Description                                        |
| ----------- | -------------------------------------------------- |
| `id`        | Comment identifier                                 |
| `author`    | Who wrote it (see below)                           |
| `content`   | The comment text                                   |
| `createdAt` | When it was posted (ISO 8601)                      |
| `editedAt`  | When it was last edited, or `null` if never edited |

### Author

| Field    | Description                                                                                                             |
| -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `type`   | `ai` for Adclear AI, `reviewer` for a human with review permission, `author` for the person who submitted the promotion |
| `userId` | Author identifier. Always `"adclear-ai"` for AI comments                                                                |
| `name`   | Display name, or `null` if the user has not been synced yet. Fall back to `userId` when `null`                          |

## Pagination fields

| Field          | Description                                    |
| -------------- | ---------------------------------------------- |
| `limit`        | Maximum threads returned in this page          |
| `offset`       | Threads skipped before this page               |
| `totalThreads` | Total threads on this version                  |
| `hasMore`      | `true` when more threads exist after this page |

For cross-cutting errors (401, 403, 429, 502), see [Errors & rate limits](/developer/errors).