Execute Agent Judge

Records the submission and queues it. Returns immediately; the evaluation itself runs asynchronously and is retrieved with GET /v2/judge/agent/{evaluation_id}. Runs the full agent-server decompose pipeline and returns a written assessment. For deterministic numeric scoring, use POST /v2/judge/llm instead.

POST /v2/judge/agent

Submit an Agent Judge evaluation

cURL

curl --request POST \
  --url https://api.eu.linqalpha.com/v2/judge/agent \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "query": "<string>",
  "answer": "<string>",
  "time_window": {
    "end_time": "2026-08-19T05:32:11Z",
    "start_time": "2025-01-01T00:00:00Z"
  },
  "references": [],
  "search_type": "external"
}
'

202

{
  "error": null,
  "payload": {
    "evaluation_id": "2fde560a-e7eb-45e0-8cd3-04e57c50d1d3",
    "status": "pending"
  }
}

What it does

Submits a question and an answer your own agent or LLM produced, and returns an evaluation_id immediately. The judge reads the answer’s claims, checks the material ones against primary sources, and writes an expert-style assessment.

That takes minutes, not seconds, so this endpoint does not return the assessment. 202 means the submission is recorded and will be evaluated — never that it has been.

POST /v2/judge/agent                  ->  202  { evaluation_id, status: "pending" }
                                     |
                                     |  the judge runs on our side
                                     v
GET  /v2/judge/agent/{evaluation_id}  ->  the assessment, once it settles

status is pending for a new submission, but read it rather than assuming it. An Idempotency-Key retry returns the evaluation that key already names — which may have finished in the meantime — so it can come back completed, excluded or failed. The value set is the same one Get Agent Judge Evaluation returns.

Retrieve the result with Get Agent Judge Evaluation.

Example

import requests

resp = requests.post(
    "https://api.eu.linqalpha.com/v2/judge/agent",
    headers={
        "X-API-KEY": "<your-api-key>",
        "Content-Type": "application/json",
        # Optional but recommended: makes a retry safe.
        "Idempotency-Key": "run-2026-08-18-0001",
    },
    json={
        "query": "How did NVIDIA's data center segment perform in FY2025?",
        "answer": (
            "Data center revenue reached $115.2B in FY2025, up 142% year over year, "
            "driven by Hopper shipments to hyperscalers."
        ),
        # The inclusive time range used by the selected search profile. `start_time`
        # is optional; omit it when only an upper cutoff is needed.
        "time_window": {
            "start_time": "2025-01-01T00:00:00Z",
            "end_time": "2026-08-18T05:32:11Z",
        },
        # Optional. `external` is the default; use `rms` for RMS-only answers and
        # `all` when the answer combines RMS and external sources.
        "search_type": "external",
        # Structured references only. `metadata` is an optional free-form JSON object.
        "references": [
            {
                "title": "NVIDIA FY2025 Q4 CFO Commentary",
                "content": "Data center revenue was $115.2 billion, up 142% from a year ago.",
                # Optional locator for the source the excerpt came from.
                "url": "https://investor.nvidia.com/financial-info/financial-reports-and-filings/",
                "metadata": {
                    "published_at": "2025-02-26T16:00:00-08:00",
                    "source_type": "earnings_release",
                },
            },
        ],
    },
)

evaluation_id = resp.json()["payload"]["evaluation_id"]

The fields

These are the fields this endpoint reads; anything else in the body is ignored.

Built for organization-bound API keys. The organization and user are taken from your key. The evaluation is filed under that organization, and RMS verification uses that user’s document visibility.

Platform-wide keys are not a supported configuration for this endpoint — it has not been designed or tested against them, and the behaviour you get is whatever the shared authentication layer does rather than something this endpoint guarantees. If you hold a platform key, talk to your LinqAlpha contact before integrating.

Field	Required	Notes
query	Yes	The question the answer responds to. Must contain non-whitespace text.
answer	Yes	The answer to evaluate. Must contain non-whitespace text.
time_window	Yes	Inclusive search window. end_time is required and start_time is optional. Both use RFC 3339 timestamps with a timezone offset. start_time must be earlier than or equal to end_time; a future end_time is rejected.
references	No	Defaults to []. Each element is { "title"?, "content", "url"?, "metadata"? }. content is required; the rest are optional. url must be HTTP(S). metadata accepts any JSON object, including nested objects and arrays. A bare URL string and undeclared reference-level fields are not accepted.
search_type	No	Verifier source scope: rms, external, or all. Defaults to external; use all when the answer combines RMS and external sources.

time_window controls the selected search scope

start_time and end_time are inclusive bounds applied to the selected search_type. When search_type is all, the same window applies to both RMS and external search. Omit start_time to search everything up to and including end_time.

The offset is required, and that is deliberate. 2026-08-19T14:32:11 without one is ambiguous, and reading it as UTC would move a Seoul timestamp nine hours. The result of that is not an error you would see: it is a plausible assessment judged against the wrong instant. Send Z or your own offset — both name the same instant and both are accepted.

start_time must be earlier than or equal to end_time. A future end_time is rejected; a few minutes of clock skew is tolerated.

references — structured shape, content required

Each element is { "title"?, "content", "url"?, "metadata"? }. content is the verbatim excerpt the judge source-grounds against — a link alone has nothing for it to check, so bare URL strings are refused. The reference object only accepts these four fields.

url is an optional HTTP(S) locator for the original source. It points at where the excerpt came from; it does not replace content, and neither the URL nor its domain is treated as proof that the excerpt or its attribution is correct.

metadata is a free-form JSON object. Its keys and nested structure are not prescribed, so it can carry a source date such as published_at, identifiers, tags, nested objects, arrays, numbers, booleans, and null values. The metadata value itself must be an object.

Omit references entirely and the answer is still fact-checked independently.

Idempotency

Send an Idempotency-Key header to make retries safe. Within your organization:

• Same key, same body → the original evaluation_id, no second judge run.
• Same key, different body → 409 Conflict.

Use it whenever a network error leaves you unsure whether a submission landed. Without it, a retry starts a second run and you are billed for both.

A retry still answers 202, but the status it carries is the original evaluation’s current status — not necessarily pending. If that evaluation already finished, you get completed, excluded or failed straight from the retry and there is nothing left to poll.

Limits

	Max
query	10,000 UTF-16 code units
answer	200,000 UTF-16 code units
references	200 items
Whole body, serialized	1,000,000 bytes (UTF-8)
Whole body, tokenized	~100,000 tokens

Oversized submissions are rejected with 400 at submission time — nothing is queued and nothing is billed, so a request that is too large costs only the round trip.

Two of these are easy to trip without noticing.

The character counts are UTF-16 code units, which is what "…".length returns in JavaScript. Characters outside the Basic Multilingual Plane — emoji, some rarer CJK — count as two. If your text is plain prose the distinction never comes up.

The token cap is separate from the byte cap, and applies to the request as a whole. Dense CJK text can pass 200,000 code units and still exceed 100,000 tokens, so a long Korean or Japanese answer may be refused while a longer English one is not.

These may be raised as we see real usage. A raise never breaks a client that was within the old figure, so code against them as minimums. If you are running close to one, tell us rather than splitting a submission.

Authorizations

X-API-KEY · string · header · required

Headers

Idempotency-Key · string

Makes a retry safe. Same key + same body returns the original evaluation_id; same key + different body is a 409.

Maximum string length: 255

Body

application/json

query · string · required

The question the answer responds to.

Maximum string length: 10000

answer · string · required

The answer to evaluate.

Maximum string length: 200000

time_window · object · required

Inclusive bounds applied to the selected search_type. For all, the same window applies to both RMS and external search. A bare date, missing timezone offset, or nonexistent instant is rejected.

Show child attributes

references · object[]

Sources the answer relied on. Optional; the answer is fact-checked independently regardless.

Maximum array length: 200

Show child attributes

search_type · enum<string> · default: external

Verifier source scope: rms, external, or all. Defaults to external; use all when the answer combines RMS and external sources.

Available options: rms, external, all

Response

202

application/json

Accepted and durably recorded. Not evaluated yet — unless this was an Idempotency-Key retry naming an evaluation that has since finished, in which case status reports that evaluation's current state. Read status; do not assume pending.

error · unknown

payload · object

Show child attributes