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

curl --request GET \
  --url https://api.eu.linqalpha.com/v2/judge/agent/{evaluation_id} \
  --header 'X-API-KEY: <api-key>'

200

{
  "error": null,
  "payload": {
    "evaluation_id": "2fde560a-e7eb-45e0-8cd3-04e57c50d1d3",
    "status": "completed",
    "evaluation": "The answer's central figure is well supported..."
  }
}

What it does

Returns the current state of one Agent Judge run, using the evaluation_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

A 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. An evaluation_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.

Authorizations

X-API-KEY · string · header · required

Path Parameters

evaluation_id · string<uuid> · required

The id returned by POST /v2/judge/agent.

Response

200

application/json

The evaluation's current state. Same shape in every status.

error · unknown

payload · object

Show child attributes