Detection

Poll a detection run

The run's current state. status is processing, completed, or failed.

completed carries fields, each with its type, page index, normalized bounds, label, confidence, and a one-line reason for the placement, plus the agent's formatting assessment of the document. When more fields were detected than an envelope may hold, the highest-confidence ones are kept and warning says so.

failed carries error. Detection failing is a distinct signal from an envelope failing: the envelope is untouched, and the caller can force another run or place fields by hand.

Every status carries the run's own metadata: whether it was forced, the agent version, how far it got, its timings, what it cost and where that number came from, and which models answered. reservedCostUsd is what is being held against the daily cap while the run is in flight; costUsd is what it actually spent and stays null until it finishes. A failed run can still have spent real money, so its cost is reported too.

Field coordinates are normalized ratios in the range 0 to 1 against the page box, with the origin at the top-left corner: xRatio and yRatio locate the top-left corner of the field, widthRatio and heightRatio size it. pageIndex is 0-based, matching the page image endpoints. Nothing here is in pixels or points, so the same numbers hold at any render scale.

get/documents/{documentId}/detect/{runId}

Request

  • Base URL: https://inkseal.net/api/v1
  • URL: https://inkseal.net/api/v1/documents/{documentId}/detect/{runId}
  • Auth: HTTP bearer

Response

The run, in whichever state it is currently in.

Example response

{
  "data": {
    "detectionRunId": 4821,
    "status": "completed",
    "forced": true,
    "agentVersion": "2.0.0-party-hints",
    "pagesProcessed": 12,
    "totalPages": 12,
    "modelRequested": "anthropic/claude-sonnet-4",
    "modelUsed": "anthropic/claude-sonnet-4",
    "primaryModelUsed": "anthropic/claude-sonnet-4",
    "fallbackModelsTried": [],
    "tokenUsage": {
      "promptTokens": 18422,
      "completionTokens": 1207,
      "totalTokens": 19629
    },
    "reservedCostUsd": 0.03,
    "costUsd": 0.0184,
    "costSource": "actual",
    "estimatedCostUsd": 0.021,
    "createdAt": "2026-08-21T14:06:44.201Z",
    "startedAt": "2026-08-21T14:06:45.006Z",
    "completedAt": "2026-08-21T14:07:12.884Z",
    "fields": [
      {
        "type": "signature",
        "pageIndex": 11,
        "bounds": {
          "xRatio": 0.1042,
          "yRatio": 0.7318,
          "widthRatio": 0.2604,
          "heightRatio": 0.0455
        },
        "label": "Client signature",
        "detectionConfidence": 0.93,
        "detectionReason": "Signature line beneath \"IN WITNESS WHEREOF\" on the execution page",
        "detectionSource": "agent"
      }
    ],
    "formatting": {
      "documentType": "services agreement",
      "strategy": "anchor-first",
      "placementQuality": "high"
    },
    "error": "Model provider returned no usable output"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.