Results and evidence

A scan has two separate outcomes: whether the analysis finished, and what it found. Check both before acting on the content.

Why the response contains jobs

Every scan uses the same status, input, extraction, coverage, usage, and jobs envelope. A completed anonymous request contains its jobs directly; those inline jobs have no status_url and cannot be polled. An authenticated URL or file request normally returns 202 accepted with job references and uses GET /api/v1/scan/{job_id} for completed jobs. A URL has one job per extracted segment; a file has one job per file. Top-level metadata describes the submission, while categories, decision, and safety_status describe each completed job. Completed inline responses also include those fields at the top level for existing clients.

ark_version is the version of the internal Ark result contract that the Control Plane interpreted to produce the response. It is currently "1" and is present on accepted, completed, and polled scan responses. This is distinct from the public /api/v1 route version, extraction.version, and usage.unit_version.

URL responses include segments: each item has a stable id, a kind describing the extracted surface, its graphemes, and, once complete, its category results and evidence. The canonical text sent to Ark starts with a short source label for the segment kind; chunk offsets refer to that labeled text. Static URL extraction reports partial on both access paths because dynamic page content is not scanned. This coverage metadata does not change an otherwise complete final classification.

The job status is only lifecycle state: running, completed, or failed. The decision summarizes how an application should handle the result:

Decision	Meaning
allow	Final classifications for the requested categories are benign.
block	At least one requested category reported a finding.
review	A final classification is missing or inconclusive.

safety_status is attack for a final attack. With a benign final result it is review only when the category result has level: "L3", decision_evidence.stage is union, and a decisive attack chunk from source: "l3" differs from the final class with confidence strictly greater than 0.1; otherwise it is benign. With a benign final result, decision stays allow. Extraction coverage is reported separately; clients can apply their own policy to partial coverage.

For PDFs, coverage.input_tokens counts the extracted text sent to analysis, not the binary file size. Images, fonts, layout data, and compression increase PDF bytes without becoming text tokens. pages_scanned / pages_total shows how many pages supplied a readable text layer; pages without one produce partial coverage because OCR is not currently performed.

Read a result in this order

1. Job status: continue polling running; stop on completed or failed.
2. Extraction and coverage: partial means some supplied content was not represented in canonical scan text; make a separate coverage decision.
3. Completion: inspect completion.state and any failures. A completed job can still have degraded analysis.
4. Categories: read each requested category’s classification and evidence. Missing results do not establish that an input is clean.
5. Application policy: decide what to allow, block, redact, or send for review.

Situation	Interpretation	Suggested handling
Completed, complete analysis, expected safe classification	The requested analysis finished without a reported failure.	Apply your policy; a scan cannot guarantee the absence of risk.
Completed, complete analysis, detection reported	Analysis finished and found a signal.	Use category results and evidence to choose an action.
Completed, degraded analysis	Some analysis failed or was unavailable.	Review or use a fallback; do not silently treat it as clean.
Failed job or failed completion	Analysis did not complete successfully.	Handle the failure explicitly.
Missing completion or requested category	Insufficient information for a complete result.	Use your fallback policy.

These are handling examples, not fixed classifications. class_name, decision, model identifiers, and evidence labels are open strings. Do not infer an allow decision from HTTP 200, accepted, or confidence alone.

Example: degraded analysis

This example shows why a terminal job still needs a completion check. Its classification values are illustrative.

{
  "job_id": "job_0123456789abcdef0123456789abcdef",
  "source": "text",
  "status": "completed",
  "input": {"kind": "text", "media_types": ["text/plain"]},
  "extraction": {"version": "document-v1", "state": "complete", "documents_total": 1, "documents_scanned": 1, "warnings": []},
  "coverage": {"state": "complete", "input_tokens": 12, "documents_total": 1, "documents_scanned": 1},
  "usage": {"input_tokens": 12, "scan_units": 1, "request_units": 1, "unit_version": "scan-unit-v1"},
  "progress": {},
  "categories": {
    "injection": {
      "class_name": "safe",
      "confidence": 0.99,
      "evidence_spans": []
    }
  },
  "completion": {
    "state": "degraded",
    "failures": [{"stage": "l2", "kind": "timeout", "retryable": true}]
  }
}

Evidence

The two evidence fields answer different questions:

• decision_evidence locates the analyzed chunk associated with a decision candidate. For injection and other document-level classifiers, use decisive_chunks[].span to locate it in the canonical scan text. These offsets are character offsets.
• evidence_spans contains detected entities with a label, score, text, and optional byte or character offsets. This is the primary evidence shape for PII and DLP. It can legitimately be empty for an injection result even when decision_evidence identifies a decisive chunk.

Confidence values

For a completed job, read the confidence values inside the relevant category:

Value	JSON path	Meaning
Final decision confidence	jobs[i].categories.<category>.final_result.confidence	Confidence of the final category classification that contributes to decision. If final_result is absent, use jobs[i].categories.<category>.confidence, which is the category verdict exposed by older or simpler Ark results.
Decisive chunk confidence	jobs[i].categories.<category>.decision_evidence.decisive_chunks[j].confidence	Confidence of that chunk-level candidate. Read class_name, source, chunk_id, and optional span from the same item.

For synchronous compatibility fields, the same category object can also appear at top-level as categories.<category>. Prefer jobs[i].categories.<category> when jobs is present so the confidence stays associated with the correct input segment or file. A decisive chunk can disagree with the final result, so never treat its confidence as the final decision confidence.

{
  "jobs": [{
    "status": "completed",
    "decision": "allow",
    "categories": {
      "injection": {
        "final_result": { "class_name": "benign", "confidence": 0.88, "source": "default" },
        "decision_evidence": {
          "stage": "union",
          "decisive_chunks": [{
            "chunk_id": 121,
            "class_name": "attack",
            "confidence": 0.1195,
            "source": "l3",
            "span": { "start": 115625, "end": 116533 }
          }]
        }
      }
    }
  }]
}

detectors lists every model that reported a result for each category. The category’s model is the final model selected for the verdict; an earlier detector such as native:dlp can therefore appear in detectors.dlp even when a later DLP model determines the final classification. Both synchronous and asynchronous account jobs include this field.

decision_evidence can also describe a rejected risk candidate. A chunk may have class_name: "attack" while the final injection category has class_name: "benign", accepted: false, and final_result.class_name: "benign". With category level: "L3", evidence stage: "union", chunk source: "l3", and attack confidence above 0.1, the response is decision: "allow" and safety_status: "review". At 0.1 or below, at another stage or level, or from another chunk source, it is allow and benign. A final attack yields decision: "block" and safety_status: "attack".

Public responses include only decisive chunks. Per-chunk contributor diagnostics are internal because they do not explain the final verdict and can make document responses very large.

Preserve the original input when using offsets to highlight text; changing whitespace or Unicode normalization can move the corresponding positions. For extracted documents, offsets refer to the canonical text produced by extraction, not necessarily the original binary file layout.

final_result, when present, provides the final category classification. timings.total_ms is the end-to-end scan latency reported by the scan backend; the other timing keys break down processing stages. Timing fields are diagnostic data, not an additional safety decision.

Response schemas

Optional fields may be absent. Clients should tolerate additional response fields in future versions and avoid depending on specific model names or timing keys for enforcement.

Accepted

Field	Type	Details
ark_version	string	Required. Version of the internal Ark result contract interpreted by the Control Plane.
status	string	Required.
input	InputMetadata	Required.
extraction	ExtractionMetadata	Required.
coverage	CoverageMetadata	Required.
segments	UrlSegment[]	Optional. Extracted URL surfaces, with results after completion.
jobs	AcceptedJob[]	Required.
usage	ScanUsage	Required. Usage for the submission; supplied on successful POST responses.

AcceptedJob

Field	Type	Details
job_id	string	Required.
source	string	Required.
status_url	string	Required. Relative API path. Poll with the same account and scan:read permission.

CompletedSubmission

Field	Type	Details
ark_version	string	Required. Version of the internal Ark result contract interpreted by the Control Plane.
jobs	SubmissionJob[]	Required.
status	string	Required.
input	InputMetadata	Required.
extraction	ExtractionMetadata	Required.
coverage	CoverageMetadata	Required.
segments	UrlSegment[]	Optional.
categories	Map<string, CategoryResult>	Optional.
decision	allow | review | block	Optional.
safety_status	SafetyStatus	Optional.
usage	ScanUsage	Required.

SubmissionJob

Field	Type	Details
job_id	string	Required.
source	string	Required.
status	running | completed | failed	Required.
progress	Map<string, Progress>	Required.
categories	Map<string, CategoryResult>	Required. Results keyed by requested category: injection, dlp, pii, or threat.
detectors	object	Optional. Model identifiers that reported results, keyed by category, including detectors superseded by a later category result.
completion	Completion	Optional.
decision	string	Optional.
safety_status	SafetyStatus	Optional.
segments	UrlSegment[]	Optional.
timings	Timings	Optional.

Job

Field	Type	Details
ark_version	string	Required. Version of the internal Ark result contract interpreted by the Control Plane.
job_id	string	Required.
source	string	Required.
status	running | completed | failed	Required.
input	InputMetadata	Required.
extraction	ExtractionMetadata	Required.
coverage	CoverageMetadata	Required.
progress	Map<string, Progress>	Required.
categories	Map<string, CategoryResult>	Required. Results keyed by requested category: injection, dlp, pii, or threat. Check every requested category; missing results do not establish clean input.
jobs	SubmissionJob[]	Optional.
segments	UrlSegment[]	Optional.
detectors	object	Optional. Model identifiers that reported results, keyed by category, including detectors superseded by a later category result.
completion	Completion	Optional.
decision	string	Optional. Scan decision, when present. The client remains responsible for enforcing its policy.
safety_status	SafetyStatus	Optional.
timings	Timings	Optional.
usage	ScanUsage	Required. Usage for the submission; supplied on successful POST responses.

InputMetadata

Field	Type	Details
kind	text | url | mcp_server | documents	Required.
media_types	string[]	Required.

ExtractionMetadata

Field	Type	Details
version	string	Required.
state	complete | partial	Required.
documents_total	integer	Required.
documents_scanned	integer	Required.
pages_total	integer	Optional.
pages_scanned	integer	Optional.
warnings	string[]	Required.

CoverageMetadata

Field	Type	Details
state	complete | partial	Required.
input_tokens	integer	Required.
documents_total	integer	Required.
documents_scanned	integer	Required.
pages_total	integer	Optional.
pages_scanned	integer	Optional.

ScanUsage

Field	Type	Details
input_tokens	integer	Required. Input tokens summed across the prepared scan contents.
scan_units	integer	Required. Billable Scan Units: max(1, ceil(input_tokens / 1000)) for every input type.
request_units	integer	Required. Compatibility alias for scan_units.
unit_version	string	Required.

Completion

Field	Type	Details
state	complete | degraded | failed	Required.
failures	Failure[]	Optional.

Failure

Field	Type	Details
stage	string	Required.
kind	string	Required.
retryable	boolean	Required.
level	string	Optional.
detector_id	string	Optional.

CategoryResult

Field	Type	Details
category	string	Optional.
class_name	string	Optional.
level	string	Optional.
model	string	Optional.
confidence	number	Optional.
duration_ms	number	Optional.
accepted	boolean	Optional.
final_result	FinalResult	Optional.
decision_evidence	DecisionEvidence	Optional.
evidence_spans	EvidenceSpan[]	Required.

FinalResult

Field	Type	Details
class_name	string	Required.
confidence	number	Required. Confidence of the final category classification. In a completed job, read this at jobs[i].categories.<category>.final_result.confidence.
source	string	Required.

EvidenceSpan

Field	Type	Details
label	string	Required.
text	string	Required.
score	number	Required.
start_byte	integer	Optional.
end_byte	integer	Optional.
start_char	integer	Optional.
end_char	integer	Optional.

DecisionEvidence

Field	Type	Details
stage	string	Optional.
decisive_chunks	EvidenceItem[]	Optional.

EvidenceItem

Field	Type	Details
chunk_id	integer	Optional.
source	string	Optional.
class_name	string	Optional.
confidence	number	Optional. Confidence of this decisive chunk candidate, not of the final decision. Read the final confidence from the category's final_result.confidence.
span	object	Optional.

Progress

Field	Type	Details
category	string	Optional.
model	string	Optional.
stage	string	Optional.
completed_chunks	integer	Optional.
total_chunks	integer	Optional.
inferred_chunks	integer	Optional.
propagated_chunks	integer	Optional.
cache_hits	integer	Optional.
early_exit	boolean	Optional.
coverage	number	Optional.

Timings

Field	Type	Details
queue_wait_ms	number | null	Optional.
worker_submit_ms	number | null	Optional.
worker_ms	number | null	Optional.
total_ms	number | null	Optional.
l2_ms	number | null	Optional.
l2_cache_hit	number | boolean | null	Optional.