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.

Submit multiple profile URLs in one request. The response returns a batch_id immediately; each profile is processed independently and delivers its own webhook. 
POST /api/v2/batch

​
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.

​
Example

curl -X POST https://api.tumban.com/api/v2/batch \
  -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",
  "estimated_completion": "2026-04-29T12:06:00"
}
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.