List Check Comments
curl --request POST \
--url https://api.velt.dev/v2/agents/checks/comments/list \
--header 'Content-Type: application/json' \
--header 'x-velt-api-key: <x-velt-api-key>' \
--header 'x-velt-auth-token: <x-velt-auth-token>' \
--data '
{
"data": {
"organizationId": "<string>",
"documentId": "<string>",
"ruleKey": "<string>",
"status": "<string>",
"cursor": "<string>",
"limit": 123,
"versionId": "<string>",
"runId": "<string>"
}
}
'import requests
url = "https://api.velt.dev/v2/agents/checks/comments/list"
payload = { "data": {
"organizationId": "<string>",
"documentId": "<string>",
"ruleKey": "<string>",
"status": "<string>",
"cursor": "<string>",
"limit": 123,
"versionId": "<string>",
"runId": "<string>"
} }
headers = {
"x-velt-api-key": "<x-velt-api-key>",
"x-velt-auth-token": "<x-velt-auth-token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-velt-api-key': '<x-velt-api-key>',
'x-velt-auth-token': '<x-velt-auth-token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
data: {
organizationId: '<string>',
documentId: '<string>',
ruleKey: '<string>',
status: '<string>',
cursor: '<string>',
limit: 123,
versionId: '<string>',
runId: '<string>'
}
})
};
fetch('https://api.velt.dev/v2/agents/checks/comments/list', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.velt.dev/v2/agents/checks/comments/list",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'data' => [
'organizationId' => '<string>',
'documentId' => '<string>',
'ruleKey' => '<string>',
'status' => '<string>',
'cursor' => '<string>',
'limit' => 123,
'versionId' => '<string>',
'runId' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-velt-api-key: <x-velt-api-key>",
"x-velt-auth-token: <x-velt-auth-token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.velt.dev/v2/agents/checks/comments/list"
payload := strings.NewReader("{\n \"data\": {\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"ruleKey\": \"<string>\",\n \"status\": \"<string>\",\n \"cursor\": \"<string>\",\n \"limit\": 123,\n \"versionId\": \"<string>\",\n \"runId\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-velt-api-key", "<x-velt-api-key>")
req.Header.Add("x-velt-auth-token", "<x-velt-auth-token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.velt.dev/v2/agents/checks/comments/list")
.header("x-velt-api-key", "<x-velt-api-key>")
.header("x-velt-auth-token", "<x-velt-auth-token>")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"ruleKey\": \"<string>\",\n \"status\": \"<string>\",\n \"cursor\": \"<string>\",\n \"limit\": 123,\n \"versionId\": \"<string>\",\n \"runId\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/agents/checks/comments/list")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-velt-api-key"] = '<x-velt-api-key>'
request["x-velt-auth-token"] = '<x-velt-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"ruleKey\": \"<string>\",\n \"status\": \"<string>\",\n \"cursor\": \"<string>\",\n \"limit\": 123,\n \"versionId\": \"<string>\",\n \"runId\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"status": "success",
"message": "Check comments retrieved",
"data": {
"comments": [],
"nextCursor": null
}
}
}
Checks
List Check Comments
POST
/
v2
/
agents
/
checks
/
comments
/
list
List Check Comments
curl --request POST \
--url https://api.velt.dev/v2/agents/checks/comments/list \
--header 'Content-Type: application/json' \
--header 'x-velt-api-key: <x-velt-api-key>' \
--header 'x-velt-auth-token: <x-velt-auth-token>' \
--data '
{
"data": {
"organizationId": "<string>",
"documentId": "<string>",
"ruleKey": "<string>",
"status": "<string>",
"cursor": "<string>",
"limit": 123,
"versionId": "<string>",
"runId": "<string>"
}
}
'import requests
url = "https://api.velt.dev/v2/agents/checks/comments/list"
payload = { "data": {
"organizationId": "<string>",
"documentId": "<string>",
"ruleKey": "<string>",
"status": "<string>",
"cursor": "<string>",
"limit": 123,
"versionId": "<string>",
"runId": "<string>"
} }
headers = {
"x-velt-api-key": "<x-velt-api-key>",
"x-velt-auth-token": "<x-velt-auth-token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-velt-api-key': '<x-velt-api-key>',
'x-velt-auth-token': '<x-velt-auth-token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
data: {
organizationId: '<string>',
documentId: '<string>',
ruleKey: '<string>',
status: '<string>',
cursor: '<string>',
limit: 123,
versionId: '<string>',
runId: '<string>'
}
})
};
fetch('https://api.velt.dev/v2/agents/checks/comments/list', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.velt.dev/v2/agents/checks/comments/list",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'data' => [
'organizationId' => '<string>',
'documentId' => '<string>',
'ruleKey' => '<string>',
'status' => '<string>',
'cursor' => '<string>',
'limit' => 123,
'versionId' => '<string>',
'runId' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-velt-api-key: <x-velt-api-key>",
"x-velt-auth-token: <x-velt-auth-token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.velt.dev/v2/agents/checks/comments/list"
payload := strings.NewReader("{\n \"data\": {\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"ruleKey\": \"<string>\",\n \"status\": \"<string>\",\n \"cursor\": \"<string>\",\n \"limit\": 123,\n \"versionId\": \"<string>\",\n \"runId\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-velt-api-key", "<x-velt-api-key>")
req.Header.Add("x-velt-auth-token", "<x-velt-auth-token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.velt.dev/v2/agents/checks/comments/list")
.header("x-velt-api-key", "<x-velt-api-key>")
.header("x-velt-auth-token", "<x-velt-auth-token>")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"ruleKey\": \"<string>\",\n \"status\": \"<string>\",\n \"cursor\": \"<string>\",\n \"limit\": 123,\n \"versionId\": \"<string>\",\n \"runId\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/agents/checks/comments/list")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-velt-api-key"] = '<x-velt-api-key>'
request["x-velt-auth-token"] = '<x-velt-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"ruleKey\": \"<string>\",\n \"status\": \"<string>\",\n \"cursor\": \"<string>\",\n \"limit\": 123,\n \"versionId\": \"<string>\",\n \"runId\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"status": "success",
"message": "Check comments retrieved",
"data": {
"comments": [],
"nextCursor": null
}
}
}
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.
Comments people attached to the check come on the first page, with
The schema uses
Errors:
attached: true and isAgent: false.
Endpoint
POST https://api.velt.dev/v2/agents/checks/comments/list
Headers
string
required
Your API key.
string
required
Your Auth Token.
Body
Params
object
required
Show properties
Show properties
string
required
1 to 512 characters. The organization of the project.
string
required
1 to 512 characters. The document of the project.
string
required
The check.
[a-z0-9:-], at most 120 characters.string
required
"open" (Open and In progress, never a rejected comment), "resolved" (never a rejected comment) or "rejected" (the check’s rejected comments, whatever their status).string
The
nextCursor of the previous page. [A-Za-z0-9_-], 1 to 200 characters.number
Comments per page. Whole number, 1 to 100. Default:
50.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.string
An agent execution id. Returns the comments this run first or last saw.
[A-Za-z0-9_-], 1 to 200 characters..strict(): unknown fields are rejected.
Example Requests
1. First page of open comments
{
"data": {
"organizationId": "org_acme",
"documentId": "acme-marketing-site",
"ruleKey": "link-broken",
"status": "open",
"limit": 20
}
}
2. Next page
{
"data": {
"organizationId": "org_acme",
"documentId": "acme-marketing-site",
"ruleKey": "link-broken",
"status": "open",
"limit": 20,
"cursor": "K7mQ2xR9vB4wLdT1sYpN"
}
}
3. Comments one run found
{
"data": {
"organizationId": "org_acme",
"documentId": "acme-marketing-site",
"ruleKey": "link-broken",
"status": "open",
"runId": "exec_8Hk2Lm4Qp9"
}
}
Response
Success Response
{
"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), 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. |
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
{
"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'" }
]
}
}
}
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).
{
"result": {
"status": "success",
"message": "Check comments retrieved",
"data": {
"comments": [],
"nextCursor": null
}
}
}
Was this page helpful?