Skip to main content
Submit multiple profile URLs in one request. The response returns a batch_id immediately; each profile is processed independently and delivers its own webhook. The scan mode is selected by the path you call — every profile in the batch runs in that mode:
ModeEndpointBehaviour
DeepPOST /api/v2/batch/deepFull analysis per profile. Each scan typically completes in under two minutes.
QuickPOST /api/v2/batch/quickCheaper and faster per profile — skips link traversal, social-media scraping, and external context search. Each scan typically completes in about 30 seconds.
Both modes accept the same request body and return the same response shape (the scan_mode field echoes which one ran). See Scan modes for the full comparison. 
POST /api/v2/batch/deep
POST /api/v2/batch/quick

​
Request body

​
profile_urls
string[]
required
Array of creator profile URLs. Each URL must be a valid HTTP or HTTPS URL.
​
callback_url
string
HTTPS endpoint Tumban will POST each result to as profiles complete. Optional: if omitted, Tumban falls back to the organization’s default_callback_url. If neither is set, the batch still runs and individual scans can be polled via GET /api/v2/scans/{scan_id} — no webhooks are sent.
​
metadata
object
default:"{}"
Arbitrary JSON object applied to every profile in the batch. Echoed back on each per-profile webhook payload.

​
Response

​
batch_id
string
required
UUID of the batch. Use it to fetch aggregate progress via GET /api/v2/batches/{batch_id}.
​
status
string
required
Always processing on submission. See Status values.
​
total_profiles
integer
required
Count of profiles accepted in the batch.
​
submitted_at
string
required
ISO 8601 UTC timestamp of when Tumban accepted the batch.
​
estimated_completion
string
required
ISO 8601 UTC timestamp of the expected completion time. Scales roughly linearly with batch size at the deployment’s concurrency cap.
​
scan_mode
string
required
Which mode ran for every profile in the batch: deep or quick. Echoes the endpoint you called.
​
daily_limit_truncated
boolean
Present and true only when the batch was partially accepted because the org’s daily_scan_limit had remaining capacity for fewer profiles than were requested. Absent (or null) when every submitted URL was accepted.
​
profiles_skipped
integer
Present only when daily_limit_truncated is true. The number of trailing profile URLs from the request that were not queued for scanning. The first total_profiles URLs (in submission order) were accepted; the last profiles_skipped URLs were dropped. Resubmit the remainder after the daily limit window resets (00:00 UTC).

​
Example

curl -X POST https://api-v2.tumban.com/api/v2/batch/deep \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_urls": [
      "https://creator.example/alice",
      "https://creator.example/bob",
      "https://creator.example/carol"
    ],
    "callback_url": "https://your-app.example/webhooks/tumban",
    "metadata": {"campaign": "may-sweep"}
  }'

{
  "batch_id": "9b8a7c6d-1234-5678-9abc-def012345678",
  "status": "processing",
  "total_profiles": 3,
  "submitted_at": "2026-04-29T12:00:00.123456+00:00",
  "estimated_completion": "2026-04-29T12:06:00.123456+00:00",
  "scan_mode": "deep"
}
To run a quick batch instead, call /api/v2/batch/quick with the same body. The response is identical except scan_mode is "quick".
The batch’s scan_ids are not returned in the response. Read each per-profile result via the webhook callback or by querying GET /api/v2/batches/{batch_id} for aggregate progress.

​
Example — partial acceptance

When the org’s daily_scan_limit has capacity for fewer profiles than were requested, the batch is accepted with the leading N profiles only and the response sets daily_limit_truncated and profiles_skipped. Worked example. Submit 50 URLs with 30 remaining in the daily quota → the first 30 URLs (in submission order) are queued; the last 20 are dropped: 
{
  "batch_id": "9b8a7c6d-1234-5678-9abc-def012345678",
  "status": "processing",
  "total_profiles": 30,
  "submitted_at": "2026-04-29T12:00:00.123456+00:00",
  "estimated_completion": "2026-04-29T13:00:00.123456+00:00",
  "scan_mode": "deep",
  "daily_limit_truncated": true,
  "profiles_skipped": 20
}
total_profiles is the count actually queued (30), not the count submitted (50). To recover the skipped URLs, take the last profiles_skipped entries from your original profile_urls array — in the same order — and resubmit them after the next daily window opens at 00:00 UTC.

​
Errors

StatusDetail
422Body failed schema validation — typically a malformed URL in profile_urls. See Errors → validation.
429The org’s daily_scan_limit is fully exhausted (no remaining capacity for even one profile). Body is structured: {"error": "daily_scan_limit_exceeded", "limit": N, "used": N}. See Rate limits. A partially-fillable batch returns 200 with daily_limit_truncated instead — see above.