Calls

Place outbound calls, then list and read call records with their transcript, recording, cost, status and end reason.

Every call, inbound or outbound, phone or web, becomes a call record. You place outbound calls with one request and read the records back with two: list them with filters, or fetch one by id.

Place an outbound call

POST /v1/calls/outbound dials a number from one of your own.

Field	Meaning
`to`	The number to dial, in E.164 form such as `+14155550123`. Required.
`from_`	A number on your organization, exactly as stored. Required. Note the trailing underscore.
`agent_id`	The agent that talks. Leave it out and the number's outbound agent is used.
`agent_version`	`0` (the default) follows the number's own setting, or the draft if it sets none. An integer pins a published version, and `"latest_published"` uses the newest. Naming a version needs `agent_id`.
`dialgem_llm_dynamic_variables`	An object of values the agent's prompt can use.
`metadata`	Your own JSON object, up to 16 KB. It comes back on the call record and in webhooks.

curl https://api.dialgem.com/v1/calls/outbound \
  -H "X-API-Key: $DIALGEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550123",
    "from_": "+14155550188",
    "agent_id": "3f1c2a52-8d6e-4a59-9b0a-5c1e7f2d4a10",
    "dialgem_llm_dynamic_variables": { "customer_name": "Maya" },
    "metadata": { "order_id": "A-1042" }
  }'

The reply is 201 with call_id, call_sid and origination_state (queued). The call is still ringing at that point, so follow it with webhooks or by fetching the record.

The request is refused before anything is dialled when:

from_ is not a number on your organization, or agent_id is not one of your agents (404).
The agent has no such published version (422), or metadata is over the limit (422).
The destination is on your do-not-call list (409, code do_not_call).
Your prepaid balance is spent. See Billing and pricing.

The SDKs do not retry this request on a failure, because a retry could ring the person twice. To dial a whole list, use campaigns.

Read a call

GET /v1/calls/{call_id} returns the call record. An id that belongs to another organization is a 404.

curl https://api.dialgem.com/v1/calls/CALL_ID \
  -H "X-API-Key: $DIALGEM_API_KEY"

The fields you will use most:

Field	What it holds
`status`	`queued`, `active`, `completed` or `failed`. `call_status` says the same as `registered`, `ongoing`, `ended` or `error`.
`disconnection_reason`	Why the call ended, or `null` while it runs. See the list in Webhook events.
`transcript`	One entry per turn, with `role`, `text` and `timestamp`. `transcript_text` is the same thing as `Agent:` and `User:` lines.
`recording_url`	A short-lived signed link, or `null` if there is no recording. Download it promptly rather than storing the link.
`call_cost`	Integer amounts in units of $0.0001, so `combined_cost: 1700` is $0.17. `null` until the call is finalized.
`analysis`	Summary, `user_sentiment` and `call_successful`, once post-call analysis has run.
`in_voicemail`	Whether the call reached an answering machine.
`duration_s`, `start_timestamp`, `end_timestamp`	Length in seconds, and start and end in epoch milliseconds.

The full object, with every field, is described under Webhook events, and it is the same shape the API returns.

Who sees cost

call_cost is spend data. API keys receive it. A dashboard sign-in with the member role gets null there.

List calls

GET /v1/calls returns your calls, newest first. Add filters to narrow them.

Filter	Matches
`status`	One or more statuses. Repeat the parameter or separate values with commas.
`agent_id`	One or more agents.
`direction`	`inbound` or `outbound`.
`call_type`	`phone_call` or `web_call`.
`disconnection_reason`	One or more end reasons.
`from_number`, `to_number`	An exact number.
`user_sentiment`	`Positive`, `Neutral` or `Negative`.
`call_successful`	`true` or `false`.
`start_after`, `start_before`	Start time in epoch milliseconds. `start_after` is inclusive and `start_before` is not.
`date_from`, `date_to`	`YYYY-MM-DD` or an ISO 8601 time, both inclusive. A bare `date_to` covers the whole day.
`metadata.<key>`	The value you stored under that key, such as `metadata.order_id=A-1042`.
`search`	Part of the agent name, ignoring case.
`sort_order`	`desc` (default) or `asc`.

curl "https://api.dialgem.com/v1/calls?direction=outbound&status=completed&disconnection_reason=voicemail_reached&date_from=2026-11-01&limit=50" \
  -H "X-API-Key: $DIALGEM_API_KEY"

Paging

Give limit (1 to 100) and the reply is calls, has_more and a pagination_key. Send that key back to get the next page. Pages stay stable while new calls arrive, and a key only works with the sort_order it was issued for. The SDKs walk the pages for you when you iterate.

Without limit, you get numbered pages instead: page (from 1) and page_size (default 10, up to 100), and the reply adds total.

Stop, re-analyze or delete

POST /v1/calls/{call_id}/stop ends a live call, as if the agent had hung up. It returns 202, and the record becomes completed with manual_stopped a moment later. A call that has already ended, or has not yet connected to an agent, returns 409.
POST /v1/calls/{call_id}/rerun-analysis runs post-call analysis again with the agent's current settings and returns the updated call. It does not bill the call again.
DELETE /v1/calls/{call_id} permanently removes a finished call with its transcript, analysis and recording. A call in progress returns 409, so stop it first.

How long call content is kept is covered in Data retention. For every field and response, see the Calls API reference.