> ## Documentation Index > Fetch the complete documentation index at: https://docs.topcalls.ai/llms.txt > Use this file to discover all available pages before exploring further. # Start a campaign > Validates the campaign (lead lists attached, leads present, account quota covers a call's dial-time reserve), creates a campaign run, and marks the campaign `running` so workers begin queuing calls. If the campaign has a future `schedule_time`, validation runs the same way but the campaign is moved to `scheduled` instead, with no run created yet. It starts automatically at the scheduled time. Send an `Idempotency-Key` header to make retries safe: a request with a key that already produced a run for this campaign returns the existing run with `200` instead of creating a second one. The key represents one logical start operation, not one HTTP request. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/campaigns/{campaign_id}/start openapi: 3.0.3 info: title: TopCalls Voice API description: > TopCalls Voice Gateway API for creating and managing AI-powered phone calls. ## Authentication All API requests require authentication. Include your API key in the `Authorization` header: ``` Authorization: Bearer tc_live_xxxxx ``` ## Rate Limits Direct call creation via `POST /v1/calls` is limited to your account's `max_calls_per_minute` setting (default: 20) per minute. Exceeding it returns `429 Too Many Requests` with a `Retry-After` header. All endpoints are additionally subject to a flat limit of 120 requests per minute per account (all methods). On a `429`, wait for the number of seconds in the `Retry-After` header, then retry the same request. For automated clients, back off progressively on repeated `429`s. Limits are per account and are shared by all API keys. ## Error Format All errors follow RFC 7807 Problem+JSON format: ```json { "type": "https://api.topcalls.ai/errors/insufficient_quota", "title": "Insufficient Quota", "status": 402, "detail": "Not enough remaining call minutes to admit this call" } ``` version: 1.0.0 contact: name: TopCalls Support url: https://topcalls.ai license: name: Proprietary servers: - url: https://api.topcalls.ai description: Production security: [] tags: - name: Calls description: Create and manage phone calls - name: Phone Numbers description: Manage phone numbers and carriers - name: Account description: Account information and usage - name: Webhooks description: Webhook configuration and events - name: Configuration description: Available AI models, voices, and platform capabilities paths: /v1/campaigns/{campaign_id}/start: post: tags: - Campaigns summary: Start a campaign description: | Validates the campaign (lead lists attached, leads present, account quota covers a call's dial-time reserve), creates a campaign run, and marks the campaign `running` so workers begin queuing calls. If the campaign has a future `schedule_time`, validation runs the same way but the campaign is moved to `scheduled` instead, with no run created yet. It starts automatically at the scheduled time. Send an `Idempotency-Key` header to make retries safe: a request with a key that already produced a run for this campaign returns the existing run with `200` instead of creating a second one. The key represents one logical start operation, not one HTTP request. operationId: startCampaign parameters: - name: campaign_id in: path required: true description: Campaign UUID schema: type: string format: uuid - $ref: '#/components/parameters/IdempotencyKeyHeader' responses: '200': description: Idempotent replay. A run already exists for this Idempotency-Key content: application/json: schema: $ref: '#/components/schemas/StartCampaignReplayResponse' '201': description: Campaign started, new run created content: application/json: schema: $ref: '#/components/schemas/StartCampaignResponse' '400': description: >- No lead lists attached to the campaign, or the attached lists have no leads content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '401': $ref: '#/components/responses/Unauthorized' '402': description: >- Insufficient account quota to admit a call. Starting requires only a small dial-time reserve; each call grows its reservation toward the campaign's `max_duration` once it is answered. A dial is admitted only if the account's worst-case in-flight exposure still fits the plan; an `exposure_limit` `code` is a transient near-plan-edge refusal (retry shortly), distinct from true out-of-minutes exhaustion. content: application/problem+json: schema: $ref: '#/components/schemas/InsufficientQuotaProblem' '403': $ref: '#/components/responses/Forbidden' '404': description: Campaign not found content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '409': description: | Campaign already has an active run (`running` or `paused`), or another request with the same `Idempotency-Key` is currently being processed. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - bearerAuth: [] components: parameters: IdempotencyKeyHeader: name: Idempotency-Key in: header required: false description: | Optional client-supplied idempotency key. When present, the gateway caches the response for 24 hours and returns the same response on retried requests with the same key (account-scoped). Safe for retries on network blips. Format: 8-255 ASCII characters from `[A-Za-z0-9_-]`. schema: type: string minLength: 8 maxLength: 255 pattern: ^[A-Za-z0-9_-]+$ example: a1b2c3d4-e5f6-7890-abcd-ef0123456789 schemas: StartCampaignReplayResponse: type: object description: | Returned instead of `StartCampaignResponse` when the request's `Idempotency-Key` matches a run already created for this campaign. No new run is created and `total_leads` is omitted. properties: run_id: type: string format: uuid status: type: string message: type: string example: Campaign run already exists with this idempotency key StartCampaignResponse: type: object description: | Response for a fresh campaign start. When `schedule_time` is in the future, the campaign is validated and moved to `scheduled` instead of `running`, and no run is created yet. The gateway starts it automatically at the scheduled time. properties: run_id: type: string format: uuid nullable: true description: >- The newly created campaign run. Absent while a start is deferred to a future `schedule_time`. status: type: string enum: - running - scheduled total_leads: type: integer description: >- Leads currently in the campaign's attached lead lists, counted fresh at start time. schedule_time: type: string format: date-time description: >- Present only when the campaign was deferred to a future scheduled start. message: type: string example: Campaign started successfully Problem: type: object required: - status - title properties: type: type: string format: uri description: Error type URI title: type: string description: Error title status: type: integer description: HTTP status code detail: type: string description: Human-readable error detail code: type: string description: > Machine-readable error code for programmatic handling. Present on errors that carry a stable identifier (e.g. `PROMPT_SAFETY_FRAUD`, `job_not_found`, `too_many_ids`, `no_matches`). Distinct from the per-field `errors[].code` used for validation failures. Scenario- specific — see each endpoint's response examples for the exact value. instance: type: string format: uuid description: Request instance ID errors: type: array description: Validation errors (for 400 responses) items: type: object properties: path: type: string description: Field path (e.g., "phone_number", "metadata.from_number") message: type: string description: Error message code: type: string description: Error code (e.g., "invalid_string", "custom") details: type: string description: Additional error details (for provider errors) InsufficientQuotaProblem: description: > Returned when the account cannot admit the requested operation on quota grounds. This is either a **transient** `exposure_limit` refusal — concurrent in-flight calls are near the plan edge, so admitting this dial could breach the plan; retry shortly — or a true out-of-minutes exhaustion. Use `code` to tell them apart: `exposure_limit` is retryable, anything else means the plan is genuinely spent. How many minutes are required depends on the operation — see each endpoint's `402` description. allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: type: string description: >- Machine-readable refusal reason. `exposure_limit` = transient (retry shortly); `insufficient_quota` = true exhaustion. enum: - exposure_limit - insufficient_quota example: exposure_limit available: type: number description: Minutes currently remaining on the account example: 3.5 required: type: number description: Minutes required to admit this operation example: 2 welcome_bonus_remaining: type: number description: Remaining welcome-bonus minutes, if any example: 0 responses: Unauthorized: description: Unauthorized (missing or invalid API key) content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: status: 401 title: Unauthorized detail: Invalid or missing API key Forbidden: description: Forbidden (missing required scope) content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: status: 403 title: Forbidden detail: 'Missing required scope: calls:write' securitySchemes: bearerAuth: type: http scheme: bearer description: | Use `Authorization: Bearer tc_live_xxxxx` ````