Observability APIAPI ReferenceCalls

Ingest a call

Submit a call recording and/or transcript for analysis. RubricHQ will: 1. Store the call observation 2. Download and upload the recording to secure storage (async) 3. Run transcript-based metrics immediately if a transcript is provided 4. Run all 9 audio analysis metrics once the recording is available The response returns immediately with `analysis_status: "pending"`. Poll `GET /calls/{id}` to check when analysis is complete.

Authentication

AuthorizationBearer

JWT token from RubricHQ Settings → API Keys

Request

This endpoint expects an object.
call_identifierstringRequired
Your unique ID for this call. Used for deduplication and retrieval.
agent_idintegerRequired
RubricHQ agent ID to associate with this call.
client_idintegerRequired

RubricHQ client (workspace) ID.

observation_typeenumOptionalDefaults to voice

voice — a phone/audio call (recording available or expected). Audio-based standard metrics will run. text — a GenAI or LLM chat session with no audio. Only transcript-based LLM metrics run.

Allowed values:
recording_urlstringOptionalformat: "uri"

Publicly accessible URL to the audio recording (WAV, MP3, or M4A). RubricHQ will download and store this securely. Required for audio-based metrics (latency, interruptions, silence, WPM). Not applicable when observation_type is "text".

transcriptlist of objectsOptional
Conversation transcript as an ordered array of turn objects. Supported roles: `"AI Assistant"`, `"User"`, `"Function Call"`, `"Function Call Result"`. Any other role value returns a `422` error. If provided alongside a `recording_url`, transcript-based metrics run immediately while audio metrics run asynchronously.
call_directionenumOptionalDefaults to inbound

Whether the call was initiated by the agent (outbound) or the customer (inbound).

Allowed values:
call_end_reasonstringOptional

How the call ended (e.g. "completed", "dropped", "transferred").

customer_numberstringOptional
Customer phone number.
duration_secondsintegerOptional
Total call duration in seconds.
call_timestampdatetimeOptional

When the call occurred (ISO 8601). Defaults to ingestion time if omitted.

labelstringOptional

Free-text label for this call (visible in the dashboard).

metric_idslist of integersOptional
IDs of specific metrics to compute. Defaults to all enabled metrics for the agent.
metadatamap from strings to anyOptional

Arbitrary key-value pairs stored with the call (visible in the dashboard).

Response

Call accepted for analysis
idinteger or null
Internal RubricHQ call ID.
call_identifierstring or null
Your provided call identifier.
analysis_statusenum or null
- `pending` — analysis queued or in progress - `computed` — all metrics computed successfully - `failed` — analysis encountered an error
Allowed values:
transcription_statusenum or null
- `pending` — transcription not yet run (audio not yet available) - `completed` — transcript available (either provided or generated) - `failed` — transcription failed
Allowed values:
call_directionenum or null
Allowed values:
call_end_reasonstring or null
customer_numberstring or null
duration_secondsinteger or null
labelstring or null
call_timestampdatetime or null
recording_urlstring or null

Presigned URL to the stored recording (populated once upload completes).

enabled_metric_idslist of integers or null
metadataobject or null
created_atdatetime or null
agentobject or null

Errors