Reading comments - Adclear Manual

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

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"

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

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"]

Response (200 OK):

{
  "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.