GET /v1/scan/{id}

Retrieve the status and results of a previously submitted scan. Use this to poll for results after submitting a scan via POST /v1/scan (sync) or POST /v1/scan/async (async). Scan types are determined automatically based on file size.

GET https://api.filesafety.dev/v1/scan/{id}

Authentication

Requires x-api-key header. See Authentication.

Path parameters

Parameter	Type	Description
`id`	string	The scan ID returned by `POST /v1/scan` (e.g., `scn_01HX7Z9K3M2N4P5Q6R7S8T9U0V`).

Example request

curl https://api.filesafety.dev/v1/scan/scn_01HX7Z9K3M2N4P5Q6R7S8T9U0V \
  -H "x-api-key: fs_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345"

Response schema

Field	Type	Present	Description
`scan_id`	string	Always	Unique scan identifier.
`status`	string	Always	Current scan status. See lifecycle below.
`verdict`	string	When complete	Overall result: `clean`, `infected`, `nsfw`, `toxic`, `mixed`, or `failed`.
`virus`	object	When complete	Malware detection results.
`virus.clean`	boolean	When complete	`true` if no virus detected.
`virus.signature`	string \| null	When complete	Name of the detected threat, or `null` if clean.
`nsfw`	object	When complete	Content analysis (images) results.
`nsfw.clean`	boolean	When complete	`true` if no NSFW content detected.
`nsfw.categories`	string[]	When complete	List of detected NSFW categories (empty if clean).
`nsfw.confidence`	number	When complete	Confidence score between 0 and 1.
`text`	object	When complete	Content analysis (text) results. Present when text analysis was applied.
`text.clean`	boolean	When complete	`true` if no text issues detected.
`text.toxic`	object	When complete	Toxicity detection with `labels` and `maxScore`.
`text.pii`	object	When complete	PII detection with `entities` list and `count`.
`text.sentiment`	object	When complete	Sentiment analysis with `dominant` label and `scores`.
`file_hash`	string	When complete	Cryptographic hash of the file, prefixed with `sha256:`.
`completed_at`	string	When complete	ISO 8601 timestamp of when scanning finished.

Status lifecycle

A scan moves through the following statuses:

awaiting_upload → pending → scanning → complete
                                     ↘ failed

Status	Description
`awaiting_upload`	Presigned URL was issued but the file has not been uploaded yet.
`pending`	File received and queued for scanning.
`scanning`	The file is actively being processed.
`complete`	Scanning finished. Verdict and results are available.
`failed`	Scanning could not complete due to an internal error.

Verdict values

The verdict field is present only when status is complete:

Verdict	Meaning
`clean`	No threats detected.
`infected`	Virus or malware detected. Check `virus.signature` for the threat name.
`nsfw`	NSFW content detected. Check `nsfw.categories` for details.
`toxic`	Toxic or harmful text content detected. Check `text.toxic` for details.
`mixed`	Multiple types of issues detected.
`failed`	Scan could not be completed. Retry the scan.

Example responses

Awaiting upload

{
  "scan_id": "scn_01HX8A1B2C3D4E5F6G7H8I9J0K",
  "status": "awaiting_upload"
}

Pending

{
  "scan_id": "scn_01HX7Z9K3M2N4P5Q6R7S8T9U0V",
  "status": "pending"
}

Scanning

{
  "scan_id": "scn_01HX7Z9K3M2N4P5Q6R7S8T9U0V",
  "status": "scanning"
}

Complete — clean

{
  "scan_id": "scn_01HX7Z9K3M2N4P5Q6R7S8T9U0V",
  "status": "complete",
  "verdict": "clean",
  "virus": {
    "clean": true,
    "signature": null
  },
  "nsfw": {
    "clean": true,
    "categories": [],
    "confidence": 0.01
  },
  "text": {
    "clean": true,
    "toxic": { "labels": [], "maxScore": 0.0 },
    "pii": { "entities": [], "count": 0 },
    "sentiment": { "dominant": "NEUTRAL", "scores": {} }
  },
  "file_hash": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "completed_at": "2026-03-23T12:00:00Z"
}

Complete — infected

{
  "scan_id": "scn_01HX7Z9K3M2N4P5Q6R7S8T9U0V",
  "status": "complete",
  "verdict": "infected",
  "virus": {
    "clean": false,
    "signature": "Win.Trojan.Agent-123456"
  },
  "nsfw": {
    "clean": true,
    "categories": [],
    "confidence": 0.02
  },
  "text": {
    "clean": true,
    "toxic": { "labels": [], "maxScore": 0.0 },
    "pii": { "entities": [], "count": 0 },
    "sentiment": { "dominant": "NEUTRAL", "scores": {} }
  },
  "file_hash": "sha256:a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "completed_at": "2026-03-23T12:01:30Z"
}

Complete — nsfw

{
  "scan_id": "scn_01HX7Z9K3M2N4P5Q6R7S8T9U0V",
  "status": "complete",
  "verdict": "nsfw",
  "virus": {
    "clean": true,
    "signature": null
  },
  "nsfw": {
    "clean": false,
    "categories": ["explicit_nudity", "graphic_violence"],
    "confidence": 0.97
  },
  "text": {
    "clean": true,
    "toxic": { "labels": [], "maxScore": 0.0 },
    "pii": { "entities": [], "count": 0 },
    "sentiment": { "dominant": "NEUTRAL", "scores": {} }
  },
  "file_hash": "sha256:f1e2d3c4b5a6f1e2d3c4b5a6f1e2d3c4b5a6f1e2d3c4b5a6f1e2d3c4b5a6f1e2",
  "completed_at": "2026-03-23T12:02:45Z"
}

Failed

{
  "scan_id": "scn_01HX7Z9K3M2N4P5Q6R7S8T9U0V",
  "status": "complete",
  "verdict": "failed"
}

Error responses

Status	Error	Cause
`401`	`"Invalid or missing API key"`	Missing or invalid `x-api-key` header.
`404`	`"Scan not found"`	No scan exists with the given ID.

Polling recommendations

Poll every 2-3 seconds after submitting a scan.
Most scans complete within 15 seconds.
Stop polling when status is complete or failed.
For production use, prefer webhooks over polling to reduce unnecessary requests.