Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tumban.com/llms.txt

Use this file to discover all available pages before exploring further.

Fetch the full record for a scan, including the triage report once the scan has completed. 
GET /api/v2/scans/{scan_id}

​
Path parameters

​
scan_id
string
required
The scan_id returned by POST /api/v2/scan or one of the per-profile ids from a batch.

​
Response

The response is the scan record. Fields you should rely on:
​
profile_id
string
required
Same value as scan_id. Tumban tracks scans and profile records under the same identifier.
​
batch_id
string
required
The batch id. For single scans this is single_<scan_id>.
​
url
string
required
The submitted profile URL.
​
status
string
required
See Status values.
​
created_at
string
required
ISO 8601 UTC timestamp of when the scan was submitted.
​
processing_started_at
string
When pipeline processing actually began. null while waiting for a concurrency slot.
​
processing_completed_at
string
When pipeline processing finished. null while still processing.
​
callback_url
string
The callback URL the scan was submitted with (or the org default if not provided), as a string. Empty when no callback was configured.
​
metadata
object
The metadata you submitted with the scan, echoed back unchanged.
​
error
string
Present when status is failed. Brief description of what went wrong.
​
webhook_delivered_at
string
ISO 8601 UTC timestamp of successful webhook delivery. Absent when no callback was configured or delivery has not (yet) succeeded.
​
triage_report
object
Present once status is completed or completed_with_partial. Shape below.

​
triage_report

​
recommendation
string
required
One of no_flags, review_low, review_medium, review_high. See Recommendation values.
​
risk_score
integer
required
0–100. See Recommendations.
​
confidence
string
required
low, medium, or high. See Confidence.
​
reason_codes
string[]
required
Machine-readable codes explaining the decision. See Reason codes.
​
reason_summary
string
required
Human-readable summary of what was found.
​
review_targets
string[]
required
URLs your reviewers should look at first.
​
link_chain
string
required
Short label describing the path Tumban followed (e.g. Profile → External site).
​
evidence_index
object[]
Per-URL evidence the contextual model cited. See Evidence index.
​
strategy_scores
object
required
Internal per-strategy scores: blocklist, content_safety, llm. Useful for debugging unexpected recommendations.
​
judge_model_invoked
boolean
required
Whether the judge model was invoked to resolve a borderline score.

​
Coverage

The scan record’s triage_report does not include coverage — that field is delivered as a top-level key in the webhook payload. When polling, inspect status === "completed_with_partial" to know whether anything was skipped.

​
Example

curl https://api.tumban.com/api/v2/scans/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer sk_xxx"

{
  "profile_id": "550e8400-e29b-41d4-a716-446655440000",
  "batch_id": "single_550e8400-e29b-41d4-a716-446655440000",
  "url": "https://creator.example/username",
  "status": "completed",
  "created_at": "2026-04-29T12:00:00",
  "processing_started_at": "2026-04-29T12:00:01",
  "processing_completed_at": "2026-04-29T12:01:38",
  "callback_url": "https://your-app.example/webhooks/tumban",
  "metadata": {"reviewer_id": "rv_42"},
  "webhook_delivered_at": "2026-04-29T12:01:39",
  "triage_report": {
    "recommendation": "review_high",
    "risk_score": 85,
    "confidence": "high",
    "reason_codes": ["PROHIBITED_DOMAIN", "ADULT_KEYWORDS"],
    "reason_summary": "Direct link to a prohibited platform combined with adult keywords in bio.",
    "review_targets": ["https://prohibited-platform.example/username"],
    "link_chain": "Profile → External site",
    "strategy_scores": {"blocklist": 50, "content_safety": 0, "llm": 85},
    "judge_model_invoked": false,
    "evidence_index": [
      {
        "ref": "link_1",
        "url": "https://prohibited-platform.example/username",
        "type": "traversed_link",
        "domain": "prohibited-platform.example"
      }
    ]
  }
}
The response also includes internal fields not listed above — canonical_url, username, platform, last_scanned_at, bio, profile_image_url, banner_image_url, social_links, direct_links, blob_references, updated_at, and org_id. These reflect the underlying scan record and are subject to change. Do not rely on their names, types, or presence; treat them as opaque.

​
Errors

StatusDetail
404Scan not found — the scan id does not exist within your organization.

​
Using the dashboard

Click any non-processing scan row from the Home page or the Scan page to open the scan detail. The page renders these read-only sections:
  • Summary — profile URL, scan id, status, submitted/completed timestamps, webhook delivery timestamp, error.
  • Triage — recommendation badge, risk score, confidence, reason codes, reason summary.
  • Coverage — which analysis steps ran, login-blocked URLs, referrer match counts.
  • Strategy scores — internal per-strategy scores. Useful for debugging an unexpected recommendation.
  • Raw JSON — collapsible “Show full document” panel that exposes the entire scan record.