Skip to main content
POST
/
api
/
v2
/
streams
Create a stream
curl --request POST \
  --url https://api.example.com/api/v2/streams
Creates a new campaign (stream) in one call. Resolves new handles via ScrapeBadger (upserting tracked accounts + incrementing Stripe quantity), creates inline segments if provided, wires pairs through the segment-cap chokepoint.

​
Body

FieldTypeDescription
namestring (optional)Campaign name. If omitted, the server derives one from the resolved pairs: "{segment} · @{handle}" for a single account, "{segment} · N accounts" for several.
pairsarrayUp to 50 (account, segment) pairs
syncTimesarray["HH:MM"] slots (15-min boundaries). Default: one hash-distributed slot.
timezonestringIANA timezone. Default: user’s default or "UTC".
autoEnrichLinkedinbooleanAuto-enrich LinkedIn URL on new leads. Default false.
autoEnrichEmailbooleanAuto-enrich email on new leads. Default false.
emailModeenum"verified" or "any". Default "any".
emailDigestOverrideenum"after_every_sync", "daily", "weekly", "off"
telegramOverridebooleanOverride team-default Telegram digest setting
deliveryDestinationenum"leads_only" or "leads_plus_webhook"
webhookUrlstringURL for webhook delivery (when deliveryDestination = "leads_plus_webhook")
csvEmailRecipientsobject{to, cc?, format} for “email me a CSV after every run”
Each pair specifies an account (by accountId OR accountHandle) AND a segment (by segmentId OR inline segment): 
{
  "accountId": 7,
  "segmentId": 12
}
OR 
{
  "accountHandle": "yongfook",
  "accountTier": "starter",
  "segment": {
    "description": "AI founders building developer tools",
    "appliedSearchFilters": { "job_role": ["Founder", "CEO"] }
  }
}

​
Response

{
  "id": 42,
  "accounts": [
    { "handle": "yongfook", "accountId": 7, "accountCreated": true, "billingDelta": "stripe_quantity_incremented" }
  ],
  "segments": [
    { "segmentId": 12, "segmentCreated": true }
  ]
}

​
Error codes

CodeHTTPWhen
handle_not_found404X handle didn’t resolve
handle_protected422Handle is a private account
handle_lookup_failed503X lookup service down
free_account_limit403Free user adding 2nd account
subscription_required403Paid user with lapsed sub
stream_cap_exceeded400Tier cap of automated streams per account exceeded
stream_multi_segment400Pairs span more than one segment (a stream targets exactly one segment)
orphan_label400Inline segment had labels with no canonical match

​
Auth

Bearer or session cookie.