Place a call

Place one outbound call now, or schedule it for later.

The response always carries execution_id — the id the call runs under for its entire lifetime, minted here BEFORE anything can fail. That is what makes an unconfirmed dial safe: if the dial is not confirmed before this request returns, the call may already be live, and a client that redials would ring the customer twice. Poll GET /v2/calls/{execution_id} instead; the id is already yours.

The same id is sent in the X-Execution-Id response header — on every 201 and 202, and on any error raised once the request has been authenticated, authorized and its body parsed (an unusable phone number, an unknown agent, an empty wallet, no free line, a refused dial) — so even a failed request names the call it was about. A 401, 403, 422 or request-rate 429 is answered before any id exists and carries none.

Immediate (no scheduled_at) — 201, status: "queued". The dial is wrapped in your organization's concurrency gate, so a burst of requests queues against your line limit rather than overrunning it.

Queued for a line — 202, status: "scheduled", reason: "waiting_for_a_free_line". When every line your organization may use is busy, or the call cannot be placed at that moment, an immediate call is not refused: it is armed under the id you were given and placed automatically, within the agent's calling hours. scheduled_at is when it will next be tried; a call waiting for a line is dialled the moment one frees, which can be sooner. Do not resend it. Only if the call cannot be queued at all do you get the old answer — a 429 naming the limit with Retry-After: 5 (busy lines), or a 503/504 (calling is temporarily unavailable).

Outside the agent's calling window — 202, status: "scheduled", deferred_by_calling_guard: true. An immediate call the agent may not place right now is booked for a time inside its next open window instead of being refused; scheduled_at says when, and calling_window names the hours. A scheduled_at you send that falls outside the window is moved the same way.

Scheduled (scheduled_at set) — 202, status: "scheduled". The call is stored durably and armed: it is placed at its time even if the platform restarts in between. Cancel it any time before it dials with POST /v2/calls/{execution_id}/stop. It is listed in GET /v2/calls from this moment, not from the moment it rings, so a call waiting for its window is visible in the call history like any other. Until it dials it reads status: "scheduled"; if its window has closed when it comes due it stays scheduled with a new scheduled_at.

Unconfirmed — 202, status: "queued", dispatch: "pending_confirmation". The dial was sent but its confirmation did not come back in time. The call may or may not be live. Poll; do not redial.

402 — error 1400: your organization's credit balance cannot fund the call. An immediate call is refused by the credit check made as it dials, and a scheduled_at request is refused before anything is booked. The message wording differs between the two; branch on the code.

409 — error 1205: the number is on your do-not-call list. Nothing is dialled, queued or booked. Error 1202: the agent is switched off, so it takes no new calls; error 1203: the agent was deleted. Nothing is dialled, queued or booked. Switch the agent on and send the request again. Error 1204: a workflow's "Before a call is placed" holds this agent's calls, and the number has had its calls for now, and the call could not be queued. Nothing is dialled; Retry-After (seconds) and the message say when it can be called again.

Held by the call limit — 202, status: "scheduled", reason: "held_by_call_limit". A workflow's "Before a call is placed" holds this agent's calls and the number has had its calls for now: the call is queued under the id you were given and placed automatically at scheduled_at, when the person can be called again. A call sent with scheduled_at is held the same way when its time comes.

variables fills the {tokens} in your agent's prompt and welcome message. metadata is merged over it, so a key in both takes the metadata value. The merged object is what GET /v2/calls/{id} returns as variables from the moment this response is sent.

Starting language — variables.agent_language starts the call in one of an agent's languages: its code, such as "ta"; case does not matter. On an agent with two or more languages, a code it doesn't have is a 400 (error 1000) whose message lists the agent's languages, and nothing is dialled, queued or booked. Leave it out, or empty, to start in the agent's default language. On an agent with one language it is an ordinary variable.

Rate limit: 1200 requests per minute per organization, shared by the endpoints that place, stop and transfer calls and create campaigns. Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.

curl -X POST "https://api.graine.ai/v2/calls?organization_id=string" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "6c6f4cc3-f56c-479d-8422-7f76694daa29",
    "to_number": "+919812345678",
    "from_number": "+917971442184",
    "variables": {
      "callee_name": "Raju",
      "scheme": "Bullet Mega Cistern"
    },
    "metadata": {
      "crm_lead_id": "LD-88421"
    },
    "scheduled_at": "2027-03-02T09:30:00+05:30",
    "record": true,
    "timeout_seconds": 30
  }'

{
  "execution_id": "dbcffa37-92a1-4ae7-9814-71ca7b8ab3d3",
  "status": "queued",
  "call_sid": "0d76fa8c-ea49-4d78-9e5b-1a15ab7b3ac2",
  "agent_id": "6c6f4cc3-f56c-479d-8422-7f76694daa29",
  "to_number": "+919812345678",
  "from_number": "+917971442184",
  "created_at": "2026-08-26T12:19:54.580Z"
}