Skip to main content
A scan is a single profile URL being analyzed. A batch is a set of scans submitted together; each profile in a batch is processed independently.

​
Scan modes

Every scan runs in one of two modes, chosen by the endpoint you call:
ModeSubmit viaWhat runsTypical time
DeepPOST /api/v2/scan/deep, POST /api/v2/batch/deepFull pipeline: profile data plus external context search, social-media scraping, and link traversal.Under 2 minutes per scan
QuickPOST /api/v2/scan/quick, POST /api/v2/batch/quickProfile data only, scored by a fast model. Skips external search, social scraping, and link traversal.~30 seconds per scan
Both modes return the same response shape and the same triage report fields (recommendation, risk_score, confidence, reason_codes, evidence_index). The submission response and the scan record both carry a scan_mode field (deep or quick) so you can tell which ran. Because a quick scan skips steps, read the coverage object to see what was and wasn’t analyzed. Use quick scans for cheap, high-volume triage where profile-level signals are enough; use deep scans when you need the full external footprint behind a decision.

​
Lifecycle

When you submit a scan, Tumban returns a scan_id and begins processing asynchronously. The scan moves through these statuses:
StatusMeaning
processingThe scan is in flight.
completedScan reached a terminal state with a usable triage report. Some steps may have been skipped — read the coverage object to see what ran.
failedThe scan could not produce a triage report. The error field explains why.
See Status values for the canonical reference.

​
Concurrency and timing

Tumban processes scans concurrently and enforces a hard 450-second timeout per scan. A typical scan completes in under two minutes. If you submit a batch of N profiles, the estimated completion time scales roughly linearly with batch size while staying within the concurrency cap.

​
Identifiers

  • scan_id — UUID returned from POST /api/v2/scan/deep or POST /api/v2/scan/quick. Use it to fetch the scan via GET /api/v2/scans/{scan_id}.
  • batch_id — UUID returned from POST /api/v2/batch/deep or POST /api/v2/batch/quick. Single scans get a synthetic single_<scan_id> batch id for internal bookkeeping; you don’t need it for single scans.

​
Deduplication

Tumban canonicalizes the submitted URL and treats the canonical form as a unique key per organization and scan mode. Re-submitting the same canonical URL in the same mode archives the previous scan and starts a new one, so the most recent result is always the one you read back. Quick and deep scans of the same URL are deduplicated independently — a deep scan and a quick scan of one profile coexist as separate records, each kept current on its own.