> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truedy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Scaling & Concurrency

> How to plan reliable volume with max concurrency, daily caps, rate limits, and safe retries

# Scaling & Concurrency

When you scale from “a few calls” to “lots of calls”, four things matter:

* **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)

Campaign requests include:

* `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`

These limits affect how many calls the background scheduler tries to launch.

### 2) API-level limits (your integration throughput)

Even if a campaign schedules successfully, your integration still might hit rate limits if you poll too aggressively or trigger too many requests at once.

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

See:

* [Rate Limits](/guides/rate-limits)
* [Idempotency](/guides/idempotency)

## Configure concurrency safely (batch campaign example)

Here’s an example payload that sets both pacing controls:

```bash theme={null}
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

If you need to reduce load:

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

This is critical for reliable operations: you avoid “half-processed” states where already-completed calls are affected.

For the exact semantics, see the Public API:

* [Pause Batch Call](/api-reference/batch-calls#pause-batch-call)
* [Resume Batch Call](/api-reference/batch-calls#resume-batch-call)

## Reliable retries: API and webhooks

### API writes: use `X-Idempotency-Key`

For create/update/write operations, always send:

* `X-Idempotency-Key: <uuid>`

This prevents duplicate campaign/call records when your request is retried.

### Webhook receivers: dedupe by event ID

Your webhook endpoint may receive duplicates (for example after retries).

Implement idempotency by:

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

See:

* [Webhooks](/guides/webhooks)
* [Idempotency](/guides/idempotency)
* [Error Handling](/guides/error-handling)

## Troubleshooting scaling problems

If you see unexpected behavior, check:

* 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](/guides/batch-calls-and-campaigns-overview)
* Use webhooks safely: [Webhooks](/guides/webhooks)
* Handle 429s: [Rate Limits](/guides/rate-limits)