> ## Documentation Index > Fetch the complete documentation index at: https://velt.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # List Check Comments Use this API to list one check's comments in one status, a page at a time. Each row says whether the comment is a page comment or a site comment, where it is, its status and whether it waits for a verify. See [Checks Overview](https://velt.dev/docs/api-reference/rest-apis/v2/agents/checks/overview.md). Comments people [attached](https://velt.dev/docs/api-reference/rest-apis/v2/agents/checks/comments/attach.md) to the check come on the first page, with `attached: true` and `isAgent: false`. # Endpoint `POST https://api.velt.dev/v2/agents/checks/comments/list` # Headers **x-velt-api-key** `string` *required* Your API key. **x-velt-auth-token** `string` *required* Your [Auth Token](https://velt.dev/docs/security/auth-tokens.md). # Body #### Params **data** `object` *required* **properties** **organizationId** `string` *required* 1 to 512 characters. The organization of the project. **documentId** `string` *required* 1 to 512 characters. The document of the project. **ruleKey** `string` *required* The check. `[a-z0-9:-]`, at most 120 characters. **status** `string` *required* `"open"` (Open and In progress, never a rejected comment), `"resolved"` (never a rejected comment) or `"rejected"` (the check's [rejected](https://velt.dev/docs/api-reference/rest-apis/v2/agents/checks/comments/reject.md) comments, whatever their status). **cursor** `string` The `nextCursor` of the previous page. `[A-Za-z0-9_-]`, 1 to 200 characters. **limit** `number` Comments per page. Whole number, 1 to 100. Default: `50`. **versionId** `string` A site version id. Returns the page comments last seen on this version, and the site comments with a page last seen on it. `[A-Za-z0-9_-]`, 1 to 200 characters. **runId** `string` An agent execution id. Returns the comments this run first or last saw. `[A-Za-z0-9_-]`, 1 to 200 characters. The schema uses `.strict()`: unknown fields are rejected. ## **Example Requests** #### 1. First page of open comments ```JSON theme={null} { "data": { "organizationId": "org_acme", "documentId": "acme-marketing-site", "ruleKey": "link-broken", "status": "open", "limit": 20 } } ``` #### 2. Next page ```JSON theme={null} { "data": { "organizationId": "org_acme", "documentId": "acme-marketing-site", "ruleKey": "link-broken", "status": "open", "limit": 20, "cursor": "K7mQ2xR9vB4wLdT1sYpN" } } ``` #### 3. Comments one run found ```JSON theme={null} { "data": { "organizationId": "org_acme", "documentId": "acme-marketing-site", "ruleKey": "link-broken", "status": "open", "runId": "exec_8Hk2Lm4Qp9" } } ``` # Response #### Success Response ```JSON theme={null} { "result": { "status": "success", "message": "Check comments retrieved", "data": { "comments": [ { "annotationId": "K7mQ2xR9vB4wLdT1sYpN", "ruleKey": "link-broken", "pageUrl": "https://www.example.com/", "pagePath": "/", "scope": "site", "pages": [ "https://www.example.com/", "https://www.example.com/pricing", "https://www.example.com/about" ], "pageCount": 14, "pageVersions": { "https://www.example.com/": "ver_20261026a", "https://www.example.com/pricing": "ver_20261026a", "https://www.example.com/about": "ver_20261025b" }, "locationType": "element", "evidence": "footer a[href=\"/careers\"]#h:3f9a1c0b7d2e", "evidenceLabel": "footer a[href=\"/careers\"]", "confidence": 96, "statusId": "OPEN", "statusType": "default", "statusKind": "open", "pendingVerify": false, "createdAt": 1761379200000, "verifiedAt": null, "reopenedCount": 0, "versionId": null, "urlHash": "a41c9e07", "thumbnailUrl": "https://storage.example.com/thumbs/a41c9e07.png", "deepLink": "https://app.example.com/review?commentId=K7mQ2xR9vB4wLdT1sYpN", "title": "Broken link to /careers", "suggestedFix": "Point the link at /jobs, or remove it.", "firstSeenRunId": "exec_8Hk2Lm4Qp9", "lastSeenRunId": "exec_9Jn3Pq5Rs1", "isAgent": true } ], "nextCursor": null } } } ``` | Field | Type | Description | | - | - | - | | `data.comments` | object\[] | The comments of this page. | | `comments[].annotationId` | string | The comment annotation id. | | `comments[].ruleKey` | string | The check. | | `comments[].pageUrl` | string | The page the comment was written on. | | `comments[].pagePath` | string | That page's path. | | `comments[].scope` | string | `"page"` or `"site"`. | | `comments[].pages` | string\[] | Site comments: the pages it is on (at most 1,000 stored). | | `comments[].pageCount` | number | Site comments: the true number of pages. | | `comments[].allPagesMatched` | boolean | Site comments: `true` when `pageCount` is more than `pages` holds. | | `comments[].pageVersions` | object | Site comments: the version each stored page was last seen on, by page. | | `comments[].locationType` | string | `"element"`, `"source"` or `"none"`. | | `comments[].evidence` | string | The exact spot, as the engine keys it. Element evidence ends with `#h:` and a hash of the element. | | `comments[].evidenceLabel` | string | The evidence to show a person, without the hash. | | `comments[].confidence` | number | 0 to 100, from the latest sighting. `0` on an attached comment. | | `comments[].statusId` | string | The comment's status id. | | `comments[].statusType` | string | `"default"`, `"ongoing"` or `"terminal"`. | | `comments[].statusKind` | string | What the status means: `"open"`, `"in_progress"`, `"resolved"`, or `"rejected"` (a person rejected it, whatever its status). | | `comments[].rejectReason` | string | Rejected comments: one of the four reasons, `excluded` (rejected by [Exclude Check](https://velt.dev/docs/api-reference/rest-apis/v2/agents/checks/exclude.md)), or the person's own words. Absent when the reject named no reason. | | `comments[].pendingVerify` | boolean | `true` when the comment is Resolved and waits for the scan that verifies it. | | `comments[].createdAt` | number | When the comment was written (epoch ms). | | `comments[].resolvedAt` | number | When it was resolved (epoch ms). | | `comments[].timeToResolveMs` | number | `resolvedAt` minus `createdAt`. | | `comments[].verifiedAt` | number \| null | When a scan verified it (epoch ms). Only a scan sets it. | | `comments[].resolvedBy` | string | `"scan"`, `"user"`, `"mcp"` or `"suggestion"` (an accepted suggestion). | | `comments[].reopenedCount` | number | Times the comment was reopened. | | `comments[].versionId` | string \| null | Page comments: the site version it was last seen on. `null` for site comments. | | `comments[].urlHash` | string \| null | Hash of `pageUrl`. | | `comments[].thumbnailUrl` | string \| null | A screenshot thumbnail of the page, when one is captured. | | `comments[].deepLink` | string | A link that opens the comment. | | `comments[].title` | string | The comment's title. | | `comments[].suggestedFix` | string | How to fix it, when the agent suggested one. | | `comments[].firstSeenRunId` | string \| null | The run that first found it. `null` on an attached comment. | | `comments[].lastSeenRunId` | string \| null | The run that last found it. `null` on an attached comment. | | `comments[].attached` | boolean | `true` on a person's comment attached to the check. | | `comments[].isAgent` | boolean | `false` on an attached comment. | | `data.nextCursor` | string \| null | Pass as `cursor` for the next page. `null` when there is no more. | > [!NOTE] > > `limit` counts agent comments. The attached comments on the first page come on top of it. A page can also hold fewer than `limit` comments while `nextCursor` is set, so keep reading until `nextCursor` is `null`. #### Failure Response ```JSON theme={null} { "error": { "message": "ERROR_MESSAGE", "status": "INVALID_ARGUMENT", "details": { "issues": [ { "code": "invalid_enum_value", "path": ["status"], "message": "Invalid enum value. Expected 'open' | 'resolved' | 'rejected', received 'closed'" } ] } } } ``` **Errors:** `INVALID_ARGUMENT` (a body outside the schema: a missing `ruleKey` or `status`, a malformed `ruleKey`, `cursor`, `versionId` or `runId`, a `limit` outside `1..100`, or an unknown field) / `NOT_FOUND` with `CHECKS_WORKSPACE_NOT_FOUND` (the workspace has no store database). ```js theme={null} { "result": { "status": "success", "message": "Check comments retrieved", "data": { "comments": [], "nextCursor": null } } } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.