Single Comparison

Get one N-Shot comparison for a document-field pair: per-shot values with confidence and source text, agreement score, overrides, and judge recommendation.

GET /v1/jobs/runs/{runId}/nshot/comparison retrieves a single N-Shot comparison for one document-field cell, selected by the document_id and field_name query parameters. Use it when you need the full detail of one comparison: the value, confidence, and source text each shot produced, the agreement score, any existing override, and the LLM judge recommendation with its reasoning.

Comparisons are unique per (run, document, field) triple, so this endpoint always resolves to at most one row. It is typically called after identifying a problematic cell in the [comparisons list](nshot-list-shots) — or directly from the links.self URL that every list entry carries, which encodes the correct query string for you (the field_name is URL-encoded there, which matters for field names containing spaces).

Inspect the values array to see what each shot extracted and from where: entries carry confidence and source_text alongside the raw value, so you can distinguish a normalization disagreement (same source text, differently formatted values) from a genuine source ambiguity (different source passages). Then check the judgement object — when the run had the LLM judge enabled, it holds a recommended_shot, recommended_value, and a reasoning string explaining the recommendation.

If judgement.accepted is null, the recommendation is pending: submit a decision via [POST /v1/jobs/runs/{runId}/nshot/judge-decision](nshot-judge-decision) to accept or decline it. If you disagree with both the majority and the judge, select the correct shot directly with [POST /v1/jobs/runs/{runId}/nshot/override](nshot-select). Either path leaves a full audit record on the comparison.

curl "https://api.talonic.com/v1/jobs/runs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/nshot/comparison?document_id=d4e5f6a7-b8c9-0123-defa-234567890123&field_name=total_amount" \
  -H "Authorization: Bearer tlnc_your_api_key"

Response

{
  "id": "5f8e2b1a-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
  "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "document_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "field_name": "total_amount",
  "status": "yellow",
  "agreement_score": 0.6667,
  "majority_value": "12450.00",
  "comparison_method": "exact",
  "values": [
    { "shot_number": 1, "value": "12450.00", "confidence": 0.95, "source_text": "Total due: 12,450.00 EUR" },
    { "shot_number": 2, "value": "12450.00", "confidence": 0.94, "source_text": "Total due: 12,450.00 EUR" },
    { "shot_number": 3, "value": "12,450.00", "confidence": 0.91, "source_text": "Total due: 12,450.00 EUR" }
  ],
  "override": null,
  "judgement": {
    "recommended_shot": 1,
    "recommended_value": "12450.00",
    "reasoning": "Shots agree on the amount; shot 3 kept the thousands separator. The canonical decimal form matches the field's number type.",
    "accepted": null,
    "decided_by": null,
    "decided_at": null
  },
  "created_at": "2026-07-14T10:32:00.000Z",
  "links": {
    "self": "/v1/jobs/runs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/nshot/comparison?document_id=d4e5f6a7-b8c9-0123-defa-234567890123&field_name=total_amount"
  }
}

Errors