Driving multiple profiles

Santiago keeps every profile fully isolated — its own fingerprint, proxy and cookie store — so you can run the same automation across many of them in parallel without the profiles being linked. This guide shows how to create profiles in bulk, launch them within your plan limits, and drive a task across the set.

All examples assume the daemon at http://localhost:7891/api.

1. Create profiles in bulk

Each profile needs its own fingerprint and (ideally) its own proxy. Generate a realistic fingerprint server-side, then create the profile with it.

FP=$(curl -s localhost:7891/api/generate-fingerprint -X POST \
  -H 'Content-Type: application/json' -d '{"os":"windows"}' | jq .data)

curl -s localhost:7891/api/profiles -X POST -H 'Content-Type: application/json' -d "{
  \"name\": \"worker-01\",
  \"tags\": [\"batch-jan\"],
  \"proxy\": {\"type\":\"socks5\",\"host\":\"1.2.3.4\",\"port\":1080,\"username\":\"u\",\"password\":\"p\"},
  \"fingerprint\": $FP
}"

Loop it to create as many as you need, each with a different proxy:

i=1
for PROXY in $(cat proxies.txt); do
  HOST=${PROXY%%:*}; PORT=${PROXY##*:}
  FP=$(curl -s localhost:7891/api/generate-fingerprint -X POST -H 'Content-Type: application/json' -d '{"os":"windows"}' | jq .data)
  curl -s localhost:7891/api/profiles -X POST -H 'Content-Type: application/json' -d "{
    \"name\": \"worker-$(printf '%02d' $i)\",
    \"tags\": [\"batch-jan\"],
    \"proxy\": {\"type\":\"socks5\",\"host\":\"$HOST\",\"port\":$PORT},
    \"fingerprint\": $FP
  }" > /dev/null
  i=$((i+1))
done

Tag the batch (batch-jan above) so you can find and filter the set later — see Organize profiles.

2. Launch within the concurrent limit

The number of profiles you can run at the same time is also capped by your plan. Launching past the limit returns 403 CONCURRENT_LIMIT_REACHED. Launch in waves sized to your plan.

for ID in $(curl -s localhost:7891/api/profiles | jq -r '.data[] | select(.tags[]? == "batch-jan") | .id'); do
  curl -s localhost:7891/api/profiles/$ID/launch -X POST            # async 202
  # poll until running
  until [ "$(curl -s localhost:7891/api/profiles/$ID/status | jq -r .data.status)" = "running" ]; do :; done

  # ... drive the profile here (navigate / fill-page / extract) ...

  curl -s localhost:7891/api/profiles/$ID/stop -X POST              # syncs cookies + tabs
done

Run profiles sequentially as above, or in parallel up to your concurrent limit — just don’t exceed it.

3. Drive the same task across profiles

Inside each launched profile, use the normal automation endpoints — see Filling forms for the form workflow and the API reference for everything else. The same fingerprint and proxy you configured are applied automatically; your task code never touches them.

4. Reset session between runs

To start a profile from a clean state without relaunching, clear its cookies:

curl -s localhost:7891/api/profiles/$ID/cookies -X DELETE
# or scope it to one domain
curl -s "localhost:7891/api/profiles/$ID/cookies?domain=.example.com" -X DELETE