Retrieve an Agent Judge evaluation
curl --request GET \
--url https://api.eu.linqalpha.com/v2/judge/agent/{evaluation_id} \
--header 'X-API-KEY: <api-key>'import requests
url = "https://api.eu.linqalpha.com/v2/judge/agent/{evaluation_id}"
headers = {"X-API-KEY": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};
fetch('https://api.eu.linqalpha.com/v2/judge/agent/{evaluation_id}', 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.eu.linqalpha.com/v2/judge/agent/{evaluation_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-KEY: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.eu.linqalpha.com/v2/judge/agent/{evaluation_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-KEY", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.eu.linqalpha.com/v2/judge/agent/{evaluation_id}")
.header("X-API-KEY", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.eu.linqalpha.com/v2/judge/agent/{evaluation_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"error": null,
"payload": {
"evaluation_id": "2fde560a-e7eb-45e0-8cd3-04e57c50d1d3",
"status": "completed",
"evaluation": "The answer's central figure is well supported..."
}
}{
"error": {
"code": "INVALID_REQUEST_BODY",
"msg": "evaluation_id must be a valid UUID",
"message": "evaluation_id must be a valid UUID"
},
"payload": null
}{
"error": {
"code": "UNAUTHORIZED",
"msg": "Invalid API key",
"message": "Invalid API key"
},
"payload": null
}{
"error": {
"code": "JUDGE_EVALUATION_NOT_FOUND",
"msg": "Evaluation not found",
"message": "Evaluation not found"
},
"payload": null
}{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"msg": "Rate limit exceeded",
"message": "Rate limit exceeded"
},
"payload": null
}{
"error": {
"code": "JUDGE_EVALUATION_FAIL",
"msg": "Failed to load the evaluation",
"message": "Failed to load the evaluation"
},
"payload": null
}{
"error": {
"code": "JUDGE_EVALUATION_FAIL",
"msg": "Evaluation lookup timed out",
"message": "Evaluation lookup timed out"
},
"payload": null
}Evaluations
Get Agent Judge Evaluation
Returns HTTP 200 in every state, including while still running. Branch on status, not on the status code.
GET
/
v2
/
judge
/
agent
/
{evaluation_id}
Retrieve an Agent Judge evaluation
curl --request GET \
--url https://api.eu.linqalpha.com/v2/judge/agent/{evaluation_id} \
--header 'X-API-KEY: <api-key>'import requests
url = "https://api.eu.linqalpha.com/v2/judge/agent/{evaluation_id}"
headers = {"X-API-KEY": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};
fetch('https://api.eu.linqalpha.com/v2/judge/agent/{evaluation_id}', 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.eu.linqalpha.com/v2/judge/agent/{evaluation_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-KEY: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.eu.linqalpha.com/v2/judge/agent/{evaluation_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-KEY", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.eu.linqalpha.com/v2/judge/agent/{evaluation_id}")
.header("X-API-KEY", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.eu.linqalpha.com/v2/judge/agent/{evaluation_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"error": null,
"payload": {
"evaluation_id": "2fde560a-e7eb-45e0-8cd3-04e57c50d1d3",
"status": "completed",
"evaluation": "The answer's central figure is well supported..."
}
}{
"error": {
"code": "INVALID_REQUEST_BODY",
"msg": "evaluation_id must be a valid UUID",
"message": "evaluation_id must be a valid UUID"
},
"payload": null
}{
"error": {
"code": "UNAUTHORIZED",
"msg": "Invalid API key",
"message": "Invalid API key"
},
"payload": null
}{
"error": {
"code": "JUDGE_EVALUATION_NOT_FOUND",
"msg": "Evaluation not found",
"message": "Evaluation not found"
},
"payload": null
}{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"msg": "Rate limit exceeded",
"message": "Rate limit exceeded"
},
"payload": null
}{
"error": {
"code": "JUDGE_EVALUATION_FAIL",
"msg": "Failed to load the evaluation",
"message": "Failed to load the evaluation"
},
"payload": null
}{
"error": {
"code": "JUDGE_EVALUATION_FAIL",
"msg": "Evaluation lookup timed out",
"message": "Evaluation lookup timed out"
},
"payload": null
}What it does
Returns the current state of one Agent Judge run, using theevaluation_id from
Execute Agent Judge. The response shape is identical in every
state — three fields, always present — so a client reads status and never has to branch on the
body’s shape.
This returns HTTP
200 while the judge is still running. Branch on the status field, not on the
status code.Statuses
status | Meaning | evaluation | Retry? |
|---|---|---|---|
pending | Queued or running. | null | Keep polling |
completed | Finished. | The assessment | No |
excluded | Not an error. The submission could not be judged fairly — see below. | One of a small whitelisted set of public-safe reasons | After fixing the input |
failed | Something broke on our side. | null | Yes |
GET immediately after a POST returns pending. That is expected, not an error.
excluded is a verdict, not a failure
Some submissions cannot be judged fairly, and saying so is more honest than inventing a score. A
question that depends on context you did not send, or an answer whose task cannot be reconstructed
from the fields you sent, is excluded rather than marked wrong.
On excluded, evaluation carries one of a small whitelisted set of public-safe reasons the
server maps untrusted model text into — for example, “The request depends on information that was
not provided, so it cannot be evaluated.” Use it to decide what to change before resubmitting.
The distinction between excluded (fix your input and resubmit) and failed (server-side, safe
to retry) is carried by status; on failed, no reason text ships on the wire.
Polling
Poll no more than once every 10 seconds. Typical runs settle in a few minutes; a sensible client gives up after around 30 minutes and treats the run as failed.import time
import requests
url = f"https://api.eu.linqalpha.com/v2/judge/agent/{evaluation_id}"
headers = {"X-API-KEY": "<your-api-key>"}
deadline = time.time() + 30 * 60 # give up after ~30 minutes
while time.time() < deadline:
payload = requests.get(url, headers=headers).json()["payload"]
if payload["status"] == "completed":
print(payload["evaluation"])
break
if payload["status"] == "excluded":
# Not an error: the submission could not be judged fairly.
# `evaluation` carries the public-safe reason -- use it to decide what to
# change (query / answer / references) before resubmitting.
print("excluded:", payload["evaluation"])
break
if payload["status"] == "failed":
# Server-side, safe to retry.
print("failed — retry the same submission")
break
time.sleep(10) # still pending
Response
{
"error": null,
"payload": {
"evaluation_id": "2fde560a-e7eb-45e0-8cd3-04e57c50d1d3",
"status": "completed",
"evaluation": "The answer's central figure is well supported..."
}
}
evaluation is non-null on completed (the written assessment) and on excluded (a public-safe
reason from a small whitelisted set); pending and failed return "evaluation": null.
Per-claim factual results, the evidence behind them, source-conflict details, and internal scoring
are used to produce the assessment but are not part of this response in any state.
Isolation
Judge runs are scoped to the organization that submitted them. Anevaluation_id belonging to
another organization returns 404, exactly as an id that does not exist — the two are
indistinguishable by design.
That organization comes from your API key, so an organization-bound key reads exactly the
evaluations it submitted. Platform-wide keys are not a supported configuration here either —
see Execute Agent Judge.
A malformed evaluation_id is rejected with 400 before any lookup.