​

Scaling & Concurrency

• Your scheduling limits (campaign caps)
• Concurrency controls (how many calls happen at once)
• API rate limits (429 responses)
• Idempotency & deduplication (safe retries for API + webhooks)

​

Who this is for

• Teams launching outbound campaigns or high-volume automations.
• Developers designing a reliable integration (no duplicate side effects).

​

Understand the two layers of limits

​

1) Campaign-level limits (batch engine pacing)

• max_concurrent_calls: how many calls can be in-flight at once for that campaign
• max_calls_per_day: a daily cap for how many calls the campaign will place
• Schedule parameters that determine when contacts are eligible:
  • timezone
  • working_days
  • start_time / end_time

​

2) API-level limits (your integration throughput)

• On 429, handle retries using backoff.
• Use idempotency keys for create/write endpoints so retries do not create duplicates.

• Rate Limits
• Idempotency

​

Configure concurrency safely (batch campaign example)

curl -X POST "https://api.truedy.ai/api/public/v1/batch-calls" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 22222222-3333-4444-5555-666666666666" \
  -d '{
    "name": "Scaling Test Campaign",
    "agent_id": "1f4baf16-1540-4d91-9696-7f34b2f2cb77",
    "contact_source": "folder",
    "contact_folder_id": "6f4af8be-0a96-49b0-ac2a-a359f46cc966",
    "schedule_type": "scheduled",
    "scheduled_at": "2026-03-20T14:30:00Z",
    "timezone": "America/New_York",
    "start_time": "10:00",
    "end_time": "17:00",
    "working_days": [1,2,3,4,5],
    "max_concurrent_calls": 8,
    "max_calls_per_day": 120
  }'

​

Pause/Resume to adjust without breaking history

• Use Pause to stop future scheduled calls from firing.
• Use Resume to continue when things look good again.

• Pause Batch Call
• Resume Batch Call

​

Reliable retries: API and webhooks

​

API writes: use X-Idempotency-Key

• X-Idempotency-Key: <uuid>

​

Webhook receivers: dedupe by event ID

• Persisting the webhook id / event_id you’ve processed.
• Ignoring duplicates.

• Webhooks
• Idempotency
• Error Handling

​

Troubleshooting scaling problems

• Are you sending a unique X-Idempotency-Key on every retry?
• Are you respecting rate limits (429)?
• Are you increasing max_concurrent_calls gradually?
• Are you using webhooks (push) instead of polling too frequently?

​

Next steps

• Learn how to build campaigns: Batch Calls & Campaigns Overview
• Use webhooks safely: Webhooks
• Handle 429s: Rate Limits