> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eu.linqalpha.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Agent Judge Evaluation
> Returns HTTP 200 in every state, including while still running. Branch on `status`, not on the status code.
## What it does
Returns the current state of one Agent Judge run, using the `evaluation_id` from
[Execute Agent Judge](/api-reference/evaluations/create). 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.
```python theme={null}
import time
import requests
url = f"https://api.eu.linqalpha.com/v2/judge/agent/{evaluation_id}"
headers = {"X-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
```json theme={null}
{
"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](/api-reference/evaluations/create).
A malformed `evaluation_id` is rejected with `400` before any lookup.
## OpenAPI
````yaml GET /v2/judge/agent/{evaluation_id}
openapi: 3.0.1
info:
title: LinqAlpha API
description: >-
Linq helps finance professionals make informed decisions using
Retrieval-Augmented Generation (RAG)-enhanced answers. By leveraging
cutting-edge Large Language Models (LLM) and supplementary technology, Linq
provides the most optimized responses based on your queries.
version: 1.0.0
license:
name: MIT
servers:
- url: https://api.eu.linqalpha.com
security:
- ApiKeyAuth: []
tags:
- name: Search
description: Search and generate responses
- name: Data
description: Data retrieval and mapping
- name: Feedback
description: Conversation feedback
- name: RMS
description: Research Management System
- name: Source Management
description: Source batch and file management
- name: MCP
description: >-
LinqAlpha MCP — Financial data tools for AI assistants via Model Context
Protocol
- name: Connectors
description: Customer Connectors — customer-owned MCP connector management
- name: Briefing
description: Briefing Agent — automated market briefings with scheduling and delivery
- name: Status
description: Sync status — check organization, document, and container sync progress
paths:
/v2/judge/agent/{evaluation_id}:
get:
tags:
- Evaluations
summary: Retrieve an Agent Judge evaluation
description: >-
Returns HTTP 200 in every state, including while still running. Branch
on `status`, not on the status code.
parameters:
- name: evaluation_id
in: path
required: true
description: The id returned by `POST /v2/judge/agent`.
schema:
type: string
format: uuid
example: 2fde560a-e7eb-45e0-8cd3-04e57c50d1d3
responses:
'200':
description: The evaluation's current state. Same shape in every status.
content:
application/json:
schema:
type: object
properties:
error:
nullable: true
example: null
payload:
$ref: '#/components/schemas/JudgeEvaluationResult'
example:
error: null
payload:
evaluation_id: 2fde560a-e7eb-45e0-8cd3-04e57c50d1d3
status: completed
evaluation: The answer's central figure is well supported...
'400':
description: Malformed `evaluation_id`.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
example:
error:
code: INVALID_REQUEST_BODY
msg: evaluation_id must be a valid UUID
message: evaluation_id must be a valid UUID
payload: null
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
example:
error:
code: UNAUTHORIZED
msg: Invalid API key
message: Invalid API key
payload: null
'404':
description: >-
No such evaluation in your organization. An id owned by another
organization is indistinguishable from one that does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
example:
error:
code: JUDGE_EVALUATION_NOT_FOUND
msg: Evaluation not found
message: Evaluation not found
payload: null
'429':
description: Organization rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
example:
error:
code: RATE_LIMIT_EXCEEDED
msg: Rate limit exceeded
message: Rate limit exceeded
payload: null
'502':
description: Upstream failure while loading the evaluation.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
example:
error:
code: JUDGE_EVALUATION_FAIL
msg: Failed to load the evaluation
message: Failed to load the evaluation
payload: null
'504':
description: Timed out loading the evaluation.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
example:
error:
code: JUDGE_EVALUATION_FAIL
msg: Evaluation lookup timed out
message: Evaluation lookup timed out
payload: null
components:
schemas:
JudgeEvaluationResult:
type: object
required:
- evaluation_id
- status
- evaluation
properties:
evaluation_id:
type: string
format: uuid
status:
type: string
enum:
- pending
- completed
- excluded
- failed
description: >-
`pending` means queued or running. `excluded` is a verdict, not an
error. On `excluded`, `evaluation` carries a public-safe reason
(from a small whitelisted set); on `failed`, no reason text ships on
the wire.
evaluation:
type: string
nullable: true
description: >-
Non-null on `completed` (the written assessment) and on `excluded`
(one of a small whitelisted set of public-safe reasons). `null` on
`pending` and `failed`.
ApiErrorResponse:
type: object
description: Standard error response wrapper
properties:
error:
$ref: '#/components/schemas/ApiError'
payload:
description: Always null for error responses
nullable: true
required:
- error
- payload
ApiError:
type: object
properties:
code:
type: string
description: >-
Error code indicating the type of error. Common codes:
- Authentication: `API_KEY_MISSING`, `INVALID_API_KEY`
- Validation: `INVALID_REQUEST_BODY`, `ORGANIZATION_ID_MISSING`,
`TICKERS_MISSING`, `CHAT_MESSAGE_ID_MISSING`, `DOCUMENT_ID_MISSING`
- Service: `SEARCH_FAIL`, `TTS_FAIL`, `CREATE_CONV_FAIL`,
`GET_STOCK_FAIL`, `CREATE_MSG_FAIL`, `ALPHA_COMP_FAIL`,
`GET_REF_FAIL`
- Connectors: `CONNECTOR_LIST_FAIL`, `CONNECTOR_NOT_FOUND`,
`CONNECTOR_CREATE_FAIL`, `CONNECTOR_UPDATE_FAIL`,
`CONNECTOR_DELETE_FAIL`, `CONNECTOR_TEST_FAIL`
- Not Found: `NOT_FOUND`
example: INVALID_REQUEST_BODY
msg:
type: string
description: Error message (deprecated, use `message` instead)
example: query is required and must be a string
message:
type: string
description: Error message providing more details about the error
example: query is required and must be a string
required:
- code
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
````