> ## Documentation Index > Fetch the complete documentation index at: https://docs.linqalpha.com/llms.txt > Use this file to discover all available pages before exploring further. # Analytics V2 Judge > Runs a source-grounding judge over one Analytics answer. You supply the answer's `chat_message_id` plus your own judging `prompt` (and an optional `response_schema`); we resolve the original prompt, the generated answer, and every reference the answer cited, run a tool-less GPT-4.1 over them, and return a verdict shaped by your schema. **Usage flow:** 1. Call `POST /v2/analytics/sse`; while consuming the stream, capture the `chat_message_id` event. 2. POST that id here with your `prompt` — your prompt is the entire judging instruction; we add no criteria of our own — and an optional `response_schema`. 3. The verdict scores how well each claim is grounded in the sources the answer actually cited (a number that contradicts its source, or is absent from all sources, is flagged as not grounded). Tenant-scoped: you can only judge answers generated by your own organization; others return 404. ## What it does The judge takes an answer you already generated and returns a structured verdict on how well each claim is backed by the sources that answer cited. For every cited source it reads the verbatim quoted text plus its metadata (document, type, tickers, dates, publisher, and FactSet fields), then checks each claim against that source. A figure that contradicts its source, or that appears in no cited source, is flagged. The check is deterministic (`temperature` 0); your `prompt` is the entire judging instruction and your `response_schema` defines the verdict shape, so we add no criteria of our own. ## Getting the `chat_message_id` As you consume the [Analytics V2 SSE stream](/api-reference/basic/analytics-sse-v2) (`POST /v2/analytics/sse`), the id arrives as its own event: ``` data: {"event_name": "chat_message_id", "data": {"chat_message_id": "5b37f46c-f5de-4b8a-af09-5058dd4779b3"}} ``` Capture the event whose `event_name == "chat_message_id"` and keep `data.chat_message_id`. ## Example ```python theme={null} import requests resp = requests.post( "https://api.linqalpha.com/v2/analytics/messages/5b37f46c-f5de-4b8a-af09-5058dd4779b3/judge", headers={"X-API-KEY": "", "Content-Type": "application/json"}, json={ # Your judge prompt, used verbatim as the judge's instruction. "prompt": ( "For each section of the answer, return: (1) a score from 0 to 10 reflecting how well its " "claims are grounded in the cited sources [N], (2) a concise summary, and (3) a short report " "covering Strengths, Weaknesses, and any Contradicted or unverifiable facts. Any figure or " "rating absent from the cited sources must appear under Contradicted or unverifiable." ), # Optional. Any valid JSON Schema (dynamic-key maps supported); omit for the default verdict shape. "response_schema": { "type": "object", "properties": { "section_scores": {"type": "object", "additionalProperties": {"type": "number"}}, "section_content_summaries": {"type": "object", "additionalProperties": {"type": "string"}}, "report": {"type": "string"}, }, "required": ["section_scores", "section_content_summaries", "report"], }, }, timeout=160, ) resp.raise_for_status() payload = resp.json()["payload"] print(payload["verdict"], payload["judge_model"], payload["references_evaluated"]) ``` You can only judge answers generated by your own organization; judging another org's answer returns `404`. The call is a single long-running LLM request, so allow a generous client timeout (\~160s). ## OpenAPI ````yaml POST /v2/analytics/messages/{chat_message_id}/judge 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.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/analytics/messages/{chat_message_id}/judge: post: tags: - Search summary: Analytics V2 Judge (source-grounding) description: >- Runs a source-grounding judge over one Analytics answer. You supply the answer's `chat_message_id` plus your own judging `prompt` (and an optional `response_schema`); we resolve the original prompt, the generated answer, and every reference the answer cited, run a tool-less GPT-4.1 over them, and return a verdict shaped by your schema. **Usage flow:** 1. Call `POST /v2/analytics/sse`; while consuming the stream, capture the `chat_message_id` event. 2. POST that id here with your `prompt` — your prompt is the entire judging instruction; we add no criteria of our own — and an optional `response_schema`. 3. The verdict scores how well each claim is grounded in the sources the answer actually cited (a number that contradicts its source, or is absent from all sources, is flagged as not grounded). Tenant-scoped: you can only judge answers generated by your own organization; others return 404. parameters: - name: chat_message_id in: path description: >- The assistant answer's ChatMessage UUID. Emitted as the `chat_message_id` event on the Analytics SSE V2 stream. required: true schema: type: string format: uuid example: 5b37f46c-f5de-4b8a-af09-5058dd4779b3 requestBody: required: true content: application/json: schema: type: object required: - prompt properties: prompt: type: string maxLength: 50000 description: >- Your judging instruction, used verbatim as the judge's system prompt. response_schema: type: object additionalProperties: true description: >- Optional JSON Schema for the verdict shape (must serialize to at most 100000 bytes). Omit to use the default verdict schema. example: prompt: >- For each section of the answer, return: (1) a score from 0 to 10 reflecting how well its claims are grounded in the cited sources [N], (2) a concise summary, and (3) a short report covering Strengths, Weaknesses, and any Contradicted or unverifiable facts. Any figure or rating absent from the cited sources must appear under Contradicted or unverifiable. response_schema: type: object properties: section_scores: type: object additionalProperties: type: number section_content_summaries: type: object additionalProperties: type: string report: type: string required: - section_scores - section_content_summaries - report responses: '200': description: Grounding verdict, shaped by your `response_schema`. content: application/json: schema: type: object properties: error: type: object nullable: true payload: type: object properties: chat_message_id: type: string format: uuid verdict: type: object additionalProperties: true judge_model: type: string references_evaluated: type: integer example: error: null payload: chat_message_id: 5b37f46c-f5de-4b8a-af09-5058dd4779b3 verdict: section_scores: Market Snapshot: 9.5 What CLSA Says: 8 section_content_summaries: Market Snapshot: >- Index levels and deltas match the cited FactSet/market-data sources. What CLSA Says: >- Ratings and targets trace to the cited CLSA notes; one target could not be verified against any cited source. report: >- ## Market Snapshot - Strengths: index levels match the cited sources. - Contradicted or unverifiable: none. ## What CLSA Says - Weaknesses: one price target is absent from the cited notes (flagged). judge_model: gpt-4.1 references_evaluated: 24 '400': description: >- Bad Request — invalid `chat_message_id` or body (e.g. missing `prompt`). content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: error: code: INVALID_REQUEST_BODY msg: prompt is required message: prompt is required payload: null '401': description: Unauthorized — missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '404': description: >- Not found — the answer does not exist or was not generated by your organization. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '422': description: Unprocessable Entity — invalid `response_schema`. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '502': description: Bad Gateway — upstream judge failure. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '504': description: Gateway Timeout — the judge is a long-running LLM call. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' components: schemas: 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 ````