Calls & Logs
Public API endpoints for call history, call transcripts, and agent runtime logs.
Use these endpoints to inspect what your agents did on calls: recent call history, per-call transcripts and tool invocations, and agent runtime logs for debugging webhook and tool issues.
All endpoints on this page use API key authentication:
Authorization: Bearer $ORBITALI_API_KEY
For push notifications instead of polling, configure Call Lifecycle Webhooks. Organization notifications report call start, end (with retained transcript), and the first saved summary. They work with every agent type and use a separate timestamped signature from agent tool webhooks.
Public call and log endpoints
| Method | Path | Description |
|---|---|---|
GET | /public/v1/calls | List recent call history |
GET | /public/v1/calls/{call_id} | Get one call with transcript and tool usage |
GET | /public/v1/agents/{agent_id}/logs | List an agent's runtime logs (last 24 hours) |
List calls
Returns 200 with an array of the organization's recent call history, newest first. This endpoint supports the filters below, not cursor or offset pagination; it returns at most 100 calls.
Query parameters:
| Parameter | Type | Description |
|---|---|---|
agentId | UUID | Optional. Only return calls for this agent |
limit | number | Optional. 1-100, defaults to 25 |
curl "https://api.orbitali.ai/public/v1/calls?agentId=$AGENT_ID&limit=25" \
-H "Authorization: Bearer $ORBITALI_API_KEY"
Response:
[
{
"id": "7c1a9a1e-3f42-4a52-9f0d-6a1f9d1b2c3e",
"agentName": "Receptionist",
"fromNumber": "+15550002000",
"toNumber": "+15550001000",
"status": "completed",
"durationSeconds": 184,
"startedAt": "2026-05-15T12:00:00.000Z",
"toolInvocations": 2,
"billableMinutes": 3.17,
"includedMinutes": 3.17,
"overageMinutes": 0,
"usageClassification": "included"
}
]
status is one of completed, active, or failed.
Usage is billed in 10-second intervals. usageClassification is included, overage,
split, trial, or unallocated; a split call crossed the plan allowance boundary.
Get call detail
Returns one call with its summary, transcript messages, tool invocations, and LLM usage.
curl https://api.orbitali.ai/public/v1/calls/$CALL_ID \
-H "Authorization: Bearer $ORBITALI_API_KEY"
Response:
{
"id": "7c1a9a1e-3f42-4a52-9f0d-6a1f9d1b2c3e",
"agentName": "Receptionist",
"fromNumber": "+15550002000",
"toNumber": "+15550001000",
"status": "completed",
"durationSeconds": 184,
"startedAt": "2026-05-15T12:00:00.000Z",
"toolInvocations": 1,
"billableMinutes": 3.17,
"includedMinutes": 1.5,
"overageMinutes": 1.67,
"usageClassification": "split",
"summary": "Caller asked about a delayed order and received a delivery update.",
"messages": [
{
"id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"role": "user",
"content": "Where is my order?",
"occurredAt": "2026-05-15T12:00:05.000Z"
}
],
"toolInvocationsLog": [
{
"id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
"agentToolId": "0e39f640-c46a-4cb8-a0a7-2a12df513b37",
"toolName": "lookup_order",
"request": { "orderId": "A-1042" },
"response": "{\"status\":\"shipped\"}",
"status": "success",
"durationMs": 420,
"createdAt": "2026-05-15T12:00:10.000Z"
}
],
"llmUsage": []
}
Call transcripts contain caller speech and can include personal data. Handle exported transcripts according to your privacy policy and retention rules.
List agent logs
Returns the agent's runtime logs from the last 24 hours, newest first. Use these to debug webhook timeouts, tool failures, and session issues.
Query parameters:
| Parameter | Type | Description |
|---|---|---|
limit | number | Optional. 1-100, defaults to 25 |
offset | number | Optional. Number of entries to skip for pagination |
severity | string | Optional. One of debug, info, warn, error |
sessionId | string | Optional. 6-character session ID to filter a single call |
curl "https://api.orbitali.ai/public/v1/agents/$AGENT_ID/logs?severity=error&limit=25" \
-H "Authorization: Bearer $ORBITALI_API_KEY"
Response:
{
"logs": [
{
"id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
"accountId": "30000000-0000-4000-8000-000000000001",
"agentId": "9dbf0d0b-2b55-45de-8c41-7a2d9b0ce8e9",
"sessionId": "a1b2c3",
"timestamp": "2026-05-15T12:00:00.000Z",
"severity": "error",
"content": { "message": "Webhook timed out after 10000ms" }
}
],
"pagination": {
"limit": 25,
"offset": 0,
"hasNextPage": false,
"hasPreviousPage": false
}
}
Errors
| Status | Description |
|---|---|
401 | Missing, malformed, or invalid API key |
400 | Invalid query parameters; the response includes validation issues |
404 | Call or agent does not exist or belongs to another organization |
Create an outbound call
POST /public/v1/calls places a Telnyx or Twilio call using an active agent and one of its assigned, claimed Telnyx or Twilio numbers. Authenticate with an organization API key. MCP exposes the same operation as create_outbound_call with the calls:write scope.
curl --fail-with-body https://api.orbitali.ai/public/v1/calls \
-H "Authorization: Bearer $ORBITALI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"agentId":"AGENT_UUID","toNumber":"+15555550100","fromNumberId":"PHONE_NUMBER_UUID","greeting":"Hello, this is Acme calling about your appointment."}'
agentId: required active agent UUID in your organization.toNumber: required destination in E.164 format.fromNumberId: assigned Orbitali phone number UUID. Optional only when exactly one usable Telnyx number is available. Multiple usable numbers return400 OUTBOUND_NUMBER_REQUIREDwithout dialing.greeting: required, nonblank opening for this call, at most 1,000 characters. Overrides stored or webhook greetings for this call; it does not change agent configuration. Mandatory AI identity disclosure still applies in the EU (and legacy routing with no configured region); non-EU voice sessions omit it.
Returns 201 with { "callId": "UUID", "providerCallId": "PROVIDER_ID", "status": "active" } for a still-active admission. Status reflects the stored snapshot: a call that already ended can return completed or failed. active means the admission remains open, not that the recipient answered. Use the call-history endpoints to inspect completion. Normal billing and concurrency admission checks apply. Do not automatically retry a timeout: the provider may already have placed the call.
The source number must have an active provider connection. Telnyx requires a Call Control application, TELNYX_MEDIA_STREAM_URL, and SERVER_SECRET. Twilio requires the number to belong directly to the connected account (connect subaccounts separately), API credentials on that account, TWILIO_MEDIA_STREAM_URL (WSS), SERVER_SECRET, and an HTTPS PUBLIC_API_URL reachable by Twilio. Twilio status callbacks use /webhooks/twilio/outbound/:callId on the API and validate the provider signature; busy, failed, canceled, and unanswered calls release their reservation. The destination must be permitted by the Twilio account’s calling permissions (and verified for trial accounts). SIP origination is not supported. The dashboard offers Test agent → Outbound for individual test calls. There is no separate outbound agent greeting setting.
Outbound media streams must claim a live admission exactly once. Replayed or completed admissions and mismatched provider identifiers are rejected. The authenticated media connection can bind provider identifiers and claim the admission even before the origination response is persisted. Signed hangup events correlate by admission ID, including when they arrive before origination returns.
Single-use admission requires migration 0075_outbound_media_claim or later. Follow the deployment order below for the shared instruction storage release.
If the provider response is lost or inconclusive, creation returns the admission callId and its latest stored state. A missing provider ID produces 202 with providerCallId: null; if persistence cannot be read, it returns 202 with status: "unknown". This reserves concurrency while signed provider events reconcile the result. A successful provider dispatch followed by a database transaction completion failure also retains the admission and returns the latest readable snapshot with the known provider ID. Do not redial automatically: the destination may already be ringing. Initiated, answered, and hangup events can attach provider identifiers independently of the origination response.
Media WebSocket connections require a valid Telnyx Ed25519 handshake signature over the exact configured TELNYX_MEDIA_STREAM_URL, including its query string. Startup failures after claiming an admission trigger bounded hangup retries; the reservation is retained if hangup cannot be confirmed, until provider events reconcile the call.
Unbound outbound admissions also have durable recovery independent of webhooks. After a two-minute settlement window, the API worker reads all pages of the application's Telnyx active-call inventory. Each batch shares one complete inventory per connection/application, acquiring all eligible per-admission dispatch locks before the scan. Lookup failures are also shared within the batch, avoiding repeated scans of an unavailable application. A matching admission is bound to its provider IDs. Two complete negative inventories at least one minute apart mark an unbound, unclaimed admission failed and release concurrency. Failed or incomplete inventories reset negative evidence and retain the reservation for retry; no calls are redialed. Postgres stores the retry deadline and first negative observation across restarts. A per-admission advisory lock prevents recovery from racing dispatch or another worker, and final row checks preserve concurrent provider events.
Apply migration 0076_outbound_reconciliation before deploying the API worker. The connected Telnyx credentials must permit reading the application's active calls; unavailable or revoked provider access leaves recovery pending rather than guessing that no call exists.
Test a phone call in the dashboard
Open an active agent, save any changes, and select Test agent → Outbound. Enter a destination number, choose an assigned Telnyx or Twilio caller number, and enter the opening message for this call. Enter the full international destination number, starting with + and the country code. The button shows the destination before you dial. These are real calls with standard charges.
The modal tracks the call and links to its call details. Closing it does not hang up; View ongoing call reopens the status view. Unknown provider responses or interrupted status checks show Confirming call status and keep redial disabled until a terminal result is known. If the request response is lost entirely, check call history before attempting another call. The greeting and destination input are retained only in memory; the tab stores the opaque call ID to resume status tracking after refresh.
Twilio uses the same request and response contract and per-call greeting as Telnyx. Greetings are passed in signed, chunked media parameters, not stored in call metadata. An uncertain Twilio dispatch is never retried automatically: callbacks can bind and finish the reserved call. If both the dispatch response and callbacks are lost, its reservation stays pending for operator reconciliation; the Telnyx inventory recovery described above does not apply to Twilio.
Twilio fetches its instructions from a short POST /webhooks/twilio/outbound/:callId/voice URL authenticated with its request signature, rather than the Calls API's 4,000-character inline Twiml field. This supports the full 1,000-character Unicode greeting limit. Apply migrations through 0078_outbound_call_instructions. The shared outbound_call_instructions table stores a provider discriminator and encrypted payload per call, preserving documents from the earlier Twilio-specific table. Provider adapters own instruction formats and authentication; storage and cleanup are shared across providers and API instances. Both providers use this storage: Twilio stores its generated TwiML, and Telnyx stores versioned per-call greeting instructions. New Telnyx client state contains signed routing identifiers and a reference marker; the runtime receives the greeting from the authenticated admission claim before cleanup can remove the document. Instructions expire after 24 hours (including provider queue time); the 30-second recovery worker removes expired instructions and those whose call ended or claimed media. Call deletion also cascades to this storage. Greetings are never placed in the voice URL.
Deploy migrations through 0078_outbound_call_instructions, then the updated agent runtime, then the API that creates referenced Telnyx calls. The runtime remains compatible with existing Telnyx calls carrying a signed inline greeting. No historical Telnyx instruction backfill is required: the previous implementation sent per-call greetings only in provider client state and did not persist them in the database. Existing call history and provider routing metadata stay in calls. The legacy agent_prompt_configs.outbound_greeting column is an agent setting, not the original per-call greeting, and must not be copied into call instructions. Existing calls finish using their inline state; new calls use encrypted shared storage. Migration 0078 already preserves temporary Twilio documents from 0077.