Get Site Score
curl --request POST \
--url https://api.velt.dev/v2/agents/checks/score/get \
--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>",
"pagesCursor": "<string>",
"pageSize": 123
}
}
'import requests
url = "https://api.velt.dev/v2/agents/checks/score/get"
payload = { "data": {
"organizationId": "<string>",
"documentId": "<string>",
"pagesCursor": "<string>",
"pageSize": 123
} }
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>',
pagesCursor: '<string>',
pageSize: 123
}
})
};
fetch('https://api.velt.dev/v2/agents/checks/score/get', 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/score/get",
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>',
'pagesCursor' => '<string>',
'pageSize' => 123
]
]),
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/score/get"
payload := strings.NewReader("{\n \"data\": {\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"pagesCursor\": \"<string>\",\n \"pageSize\": 123\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/score/get")
.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 \"pagesCursor\": \"<string>\",\n \"pageSize\": 123\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/agents/checks/score/get")
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 \"pagesCursor\": \"<string>\",\n \"pageSize\": 123\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"status": "success",
"message": "Site score retrieved",
"data": {
"siteScore": null,
"recentRuns": [],
"pages": [],
"nextPagesCursor": null,
"totalPages": 0,
"excludedCount": 0,
"nextScanAt": null
}
}
}
Checks
Get Site Score
POST
/
v2
/
agents
/
checks
/
score
/
get
Get Site Score
curl --request POST \
--url https://api.velt.dev/v2/agents/checks/score/get \
--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>",
"pagesCursor": "<string>",
"pageSize": 123
}
}
'import requests
url = "https://api.velt.dev/v2/agents/checks/score/get"
payload = { "data": {
"organizationId": "<string>",
"documentId": "<string>",
"pagesCursor": "<string>",
"pageSize": 123
} }
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>',
pagesCursor: '<string>',
pageSize: 123
}
})
};
fetch('https://api.velt.dev/v2/agents/checks/score/get', 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/score/get",
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>',
'pagesCursor' => '<string>',
'pageSize' => 123
]
]),
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/score/get"
payload := strings.NewReader("{\n \"data\": {\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"pagesCursor\": \"<string>\",\n \"pageSize\": 123\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/score/get")
.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 \"pagesCursor\": \"<string>\",\n \"pageSize\": 123\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/agents/checks/score/get")
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 \"pagesCursor\": \"<string>\",\n \"pageSize\": 123\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"status": "success",
"message": "Site score retrieved",
"data": {
"siteScore": null,
"recentRuns": [],
"pages": [],
"nextPagesCursor": null,
"totalPages": 0,
"excludedCount": 0,
"nextScanAt": null
}
}
}
Use this API to get a project’s site score, its last runs and its pages with their scores, lowest score first. The pages come a page at a time. See Score.
The schema uses
Errors:
Endpoint
POST https://api.velt.dev/v2/agents/checks/score/get
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
The
nextPagesCursor of the previous read, passed back exactly as it came. It is opaque: do not build or edit one. At most 4,096 characters.number
Pages per read. Whole number, 1 to 1,000. Default:
500..strict(): unknown fields are rejected.
Example Requests
1. First read
{
"data": {
"organizationId": "org_acme",
"documentId": "acme-marketing-site",
"pageSize": 100
}
}
2. Next read
{
"data": {
"organizationId": "org_acme",
"documentId": "acme-marketing-site",
"pageSize": 100,
"pagesCursor": "p1WzgzLjMsImh0dHBzOi8vZXhhbXBsZS5jb20vcHJpY2luZyIsImM4MmYxYjVlIl0"
}
}
Response
Success Response
{
"result": {
"status": "success",
"message": "Site score retrieved",
"data": {
"siteScore": 94.8,
"recentRuns": [
{
"runId": "exec_9Jn3Pq5Rs1",
"siteScore": 94.8,
"at": 1761465600000,
"trigger": "standalone",
"agentId": "broken-links"
}
],
"pages": [
{
"url": "https://www.example.com/pricing",
"urlHash": "c82f1b5e",
"score": 91.5,
"openCount": 2,
"lastCheckedAt": 1761465600000
},
{
"url": "https://www.example.com/",
"urlHash": "a41c9e07",
"score": 95,
"openCount": 1,
"lastCheckedAt": 1761465600000
}
],
"nextPagesCursor": null,
"totalPages": 2,
"excludedCount": 1,
"nextScanAt": null
}
}
}
| Field | Type | Description |
|---|---|---|
data.siteScore | number | null | The site score, 0 to 100. null before the first run. |
data.recentRuns | object[] | The last runs (at most 30), newest first: runId, the siteScore after it, at (epoch ms), the run’s trigger (for example "standalone", or "resolve" for a verify rescan), and the agentId that ran. |
data.pages | object[] | One page of the pages, lowest score first. |
pages[].url | string | The page. |
pages[].urlHash | string | Hash of url. |
pages[].score | number | null | The page’s score, 0 to 100. null when no check applies to it. |
pages[].openCount | number | Open comments on the page. An excluded check’s comments are not counted. |
pages[].lastCheckedAt | number | null | When an agent last checked the page (epoch ms). |
data.nextPagesCursor | string | null | Pass as pagesCursor for the next read. It marks a place in the order (lowest score first, then URL), not a page, so a page marked gone or rescored since never fails the next read. null at the end. |
data.totalPages | number | Pages across every read. |
data.excludedCount | number | Checks excluded for the project. |
data.nextScanAt | null | Reserved. Always null today. |
Failure Response
{
"error": {
"message": "The pages cursor is not the nextPagesCursor of a previous read",
"status": "INVALID_ARGUMENT",
"details": {
"reason": "CHECKS_INVALID_PAGES_CURSOR"
}
}
}
INVALID_ARGUMENT (a body outside the schema: a malformed pagesCursor, a pageSize outside 1..1000, or an unknown field; or CHECKS_INVALID_PAGES_CURSOR when pagesCursor does not decode to a position in the list) / NOT_FOUND with CHECKS_WORKSPACE_NOT_FOUND (the workspace has no store database).
{
"result": {
"status": "success",
"message": "Site score retrieved",
"data": {
"siteScore": null,
"recentRuns": [],
"pages": [],
"nextPagesCursor": null,
"totalPages": 0,
"excludedCount": 0,
"nextScanAt": null
}
}
}
Was this page helpful?

